Path, File and Directory Annotations

@Path

The @Path annotation may be applied to fields annotated with @Option and @Arguments that take filesystem path related arguments to impose various restrictions on those e.g.

@Option(name = "--path", arity = 1)
@Path(mustExist = true)
public String pathMustExist;

Requires that the --path option refer to an existing path.

We can also restrict the kind of the path e.g.

@Option(name = "--file", arity = 1)
@Path(mustExist = true, kind = PathKind.FILE)
public String fileMustExit;

Requires that the --file option be an existing path that references a file.

Similarly we can also require a directory e.g.

@Option(name = "--directory", arity = 1)
@Path(mustExist = true, kind = PathKind.DIRECTORY)
public String dirMustExist;

Note that there is also a PathKind.ANY if we allow either files or directories.

Additionally we can specify restrictions on the access mode of the path:

@Option(name = "--readable", arity = 1)
@Path(mustExist = false, readable = true, writable = false, executable = false)
public String readable;
    
@Option(name = "--writable", arity = 1)
@Path(mustExist = false, writable = true, readable = false, executable = false)
public String writable;
    
@Option(name = "--executable", arity = 1)
@Path(mustExist = false, executable = true, readable = false, writable = false)
public String executable;

In the above examples we use the readable, writable and executable fields of the annotation to specify the access modes that the path must support.

@File and @Directory

These annotations function the same as the above described @Path annotation except that the kind field is not available since it is implied by the name of the annotation.

So @File functions the same as @Path(kind = PathKind.FILE) and @Directory the same as @Path(kind = PathKind.DIRECTORY)

Related Annotations

For enforcing certain file extensions the @EndsWith annotation may be useful.

Improving this Documentation

This documentation is itself open source and lives in GitHub under the docs/ directory.

I am not a professional technical writer and as the developer of this software I can often make assumptions of knowledge that you as a user reading this may not have. Improvements to the documentation are always welcome, if you have suggestions for the documentation please submit pull requests to the main branch.