org.unix4j.unix.Find Maven / Gradle / Ivy
package org.unix4j.unix;
import org.unix4j.command.CommandInterface;
import org.unix4j.unix.find.FindFactory;
import org.unix4j.unix.find.FindOption;
import org.unix4j.unix.find.FindOptions;
import org.unix4j.unix.find.FindOptionSets;
/**
* Non-instantiable module with inner types making up the find command.
*
* NAME
*
* find - search for files in a directory hierarchy
*
* SYNOPSIS
*
*
* {@code find } {@code find } {@code find } {@code find } {@code find } {@code find } {@code find } {@code find [-dflxrinocamz] } {@code find [-dflxrinocamz] } {@code find [-dflxrinocamz] } {@code find [-dflxrinocamz] } {@code find [-dflxrinocamz] {@code find [-dflxrinocamz] {@code find [-dflxrinocamz] } {@code find [-dflxrinocamz] } {@code find [-dflxrinocamz] {@code find [-dflxrinocamz] {@code find [-dflxrinocamz] {@code find [-dflxrinocamz]
*
* See {@link Interface} for the corresponding command signature methods.
*
* DESCRIPTION
*
*
Find searches the directory tree by evaluating different file matching expressions. The names of the matching files found in or below the working directory or the directories specified by the {@code paths} operand are written to the standard output.
*
*
* Options
*
* The following options are supported:
*
*
* {@code -d} {@code --typeDirectory} Consider only directories {@code -f} {@code --typeFile} Consider only regular files {@code -l} {@code --typeSymlink} Consider only symbolic links {@code -x} {@code --typeOther} Consider only files that are neither of directory (d),
regular file (f) or symlink (l). {@code -r} {@code --regex} Use full regular expression syntax for the patterns specified by the
name operand
(This option is ignored if no name operand is specified).
{@code -i} {@code --ignoreCase} Use case insensitive matching when applying the file name pattern
specified by the name operand
(This option is ignored if no name operand is specified).
{@code -n} {@code --timeNewer} Consider only files that have been created, modified or accessed
after or at the time specified by the time operand (the default)
(This option is ignored if no time operand is specified).
{@code -o} {@code --timeOlder} Consider only files that have been created, modified or accessed
before or at the time specified by the time operand
(This option is ignored if no time operand is specified).
{@code -c} {@code --timeCreate} The time operand refers to the creation time of the file
(This option is ignored if no time operand is specified).
{@code -a} {@code --timeAccess} The time operand refers to the last access time of the file
(This option is ignored if no time operand is specified).
{@code -m} {@code --timeModified} The time operand refers to the last modification time of the file
(the default)
(This option is ignored if no time operand is specified).
{@code -z} {@code --print0} Print the full file name on the standard output, followed by a null
character (instead of the newline character used by default). This
allows file names that contain newlines or other types of white
space to be correctly interpreted by programs that process the find
output. This option corresponds to the --delimiter0 option of xargs.
*
* OPERANDS
*
* The following operands are supported:
*
*
* {@code } : {@code String} Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory. {@code } : {@code String} Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified. {@code } : {@code long} Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative. {@code : {@code java.util.Date} Consider only files that have been created, modified or accessed
before or after the specified {@code time} operand; consider the
{@code -time...} options for details of the comparison. {@code } : {@code String...} String arguments defining the options and operands for the command.
Options can be specified by acronym (with a leading dash "-") or by
long name (with two leading dashes "--"). Operands other than the
default "--path" operand have to be prefixed with the operand name
(e.g. "--name" for subsequent path operand values). {@code } : {@code FindOptions} Options for the file search.
*/
public final class Find {
/**
* The "find" command name.
*/
public static final String NAME = "find";
/**
* Interface defining all method signatures for the "find" command.
*
* @param
* the generic return type for all command signature methods
* to support different implementor types; the methods of a
* command factory for instance returns a command instance;
* command builders can also implement this interface, but their
* methods return the builder itself enabling for chained method
* invocation to create joined commands
*/
public static interface Interface extends CommandInterface {
/**
* Finds all files matching the search criteria specified by the given
arguments and writes the file names to the standard output.
Options can be specified by acronym (with a leading dash "-") or by
long name (with two leading dashes "--"). Operands other than the
default "--name" operand have to be prefixed with the operand name.
The files names written to the output are relative paths referring
to the working directory (or -- if provided -- relative to the path
given after the {@code "--path"} operand name).
*
* @param args String arguments defining the options and operands for the command.
Options can be specified by acronym (with a leading dash "-") or by
long name (with two leading dashes "--"). Operands other than the
default "--path" operand have to be prefixed with the operand name
(e.g. "--name" for subsequent path operand values).
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(String... args);
/**
* Finds all files in or below the directory specified by {@code path}
and writes the file names to the standard output.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(String path);
/**
* Finds all files matching the specified {@code name} in or below the
directory specified by {@code path} and writes the file names to
the standard output.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(String path, String name);
/**
* Finds all files matching the specified file {@code size} in or below
the user's current working directory and writes the file names to
the standard output. Matching files use at least {@code size} bytes
on disk if {@code size} is positive, or at most {@code abs(size)}
bytes if {@code size} is zero or negative.
The files names written to the output are relative paths referring
to the working directory.
*
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(long size);
/**
* Finds all files matching the specified file {@code size} in or below
the directory specified by {@code path} and writes the file names
to the standard output. Matching files use at least {@code size}
bytes on disk if {@code size} is positive, or at most
{@code abs(size)} bytes if {@code size} is zero or negative.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(String path, long size);
/**
* Finds all files matching the specified file {@code name} and
{@code size} in or below the user's current working directory and
writes the file names to the standard output. Matching files use
at least {@code size} bytes on disk if {@code size} is positive,
or at most {@code abs(size)} bytes if {@code size} is zero or
negative.
The files names written to the output are relative paths referring
to the working directory.
*
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(long size, String name);
/**
* Finds all files matching the specified file {@code name} and
{@code size} in or below the directory specified by {@code path}
and writes the file names to the standard output. Matching files
use at least {@code size} bytes on disk if {@code size} is positive,
or at most {@code abs(size)} bytes if {@code size} is zero or
negative.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(String path, long size, String name);
/**
* Finds all files matching the specified {@code name} in or below the
user's current working directory and writes the file names to the
standard output.
The files names written to the output are relative paths referring
to the working directory.
*
* @param options Options for the file search.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, String name);
/**
* Finds all files matching the specified {@code name} in or below the
directory specified by {@code path} and writes the file names to
the standard output.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param options Options for the file search.
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, String path, String name);
/**
* Finds all files matching the specified file {@code size} in or below
the user's current working directory and writes the file names to
the standard output. Matching files use at least {@code size} bytes
on disk if {@code size} is positive, or at most {@code abs(size)}
bytes if {@code size} is zero or negative.
The files names written to the output are relative paths referring
to the working directory.
*
* @param options Options for the file search.
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, long size);
/**
* Finds all files matching the specified file {@code size} in or below
the directory specified by {@code path} and writes the file names
to the standard output. Matching files use at least {@code size}
bytes on disk if {@code size} is positive, or at most
{@code abs(size)} bytes if {@code size} is zero or negative.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param options Options for the file search.
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, String path, long size);
/**
* Finds all files that have been created, modified or accessed before
or after the specified {@code time} (depending on the given
{@code -time...} options). The names of the matching files found in
or below the user's current working directory are written to the
standard output.
The files names written to the output are relative paths referring
to the working directory.
*
* @param options Options for the file search.
* @param time Consider only files that have been created, modified or accessed
before or after the specified {@code time} operand; consider the
{@code -time...} options for details of the comparison.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, java.util.Date time);
/**
* Finds all files that have been created, modified or accessed before
or after the specified {@code time} (depending on the given
{@code -time...} options). The names of the matching files found in
or below the directory specified by {@code path} are written to
the standard output.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param options Options for the file search.
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param time Consider only files that have been created, modified or accessed
before or after the specified {@code time} operand; consider the
{@code -time...} options for details of the comparison.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, String path, java.util.Date time);
/**
* Finds all files matching the specified file {@code name} and
{@code size} in or below the user's current working directory and
writes the file names to the standard output. Matching files use
at least {@code size} bytes on disk if {@code size} is positive, or
at most {@code abs(size)} bytes if {@code size} is zero or negative.
The files names written to the output are relative paths referring
to the working directory.
*
* @param options Options for the file search.
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, long size, String name);
/**
* Finds all files matching the specified file {@code name} and
{@code size} in or below the directory specified by {@code path}
and writes the file names to the standard output. Matching files
use at least {@code size} bytes on disk if {@code size} is positive,
or at most {@code abs(size)} bytes if {@code size} is zero or
negative.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param options Options for the file search.
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, String path, long size, String name);
/**
* Finds all files matching the given {@code name} that have been
created, modified or accessed before or after the specified
{@code time} (depending on the given {@code -time...} options). The
names of the matching files found in or below the user's current
working directory are written to the standard output.
The files names written to the output are relative paths referring
to the working directory.
*
* @param options Options for the file search.
* @param time Consider only files that have been created, modified or accessed
before or after the specified {@code time} operand; consider the
{@code -time...} options for details of the comparison.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, java.util.Date time, String name);
/**
* Finds all files matching the given {@code name} that have been
created, modified or accessed before or after the specified
{@code time} (depending on the given {@code -time...} options). The
names of the matching files found in or below the directory
specified by {@code path} are written to the standard output.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param options Options for the file search.
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param time Consider only files that have been created, modified or accessed
before or after the specified {@code time} operand; consider the
{@code -time...} options for details of the comparison.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, String path, java.util.Date time, String name);
/**
* Finds all files matching the given {@code name} and {@code size} and
have been created, modified or accessed before or after the specified
{@code time} (depending on the given {@code -time...} options).
Matching files use at least {@code size} bytes on disk if
{@code size} is positive, or at most {@code abs(size)} bytes if
{@code size} is zero or negative. The names of the matching files
found in or below the user's current working directory are written
to the standard output.
The files names written to the output are relative paths referring
to the working directory.
*
* @param options Options for the file search.
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @param time Consider only files that have been created, modified or accessed
before or after the specified {@code time} operand; consider the
{@code -time...} options for details of the comparison.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, long size, java.util.Date time, String name);
/**
* Finds all files matching the given {@code name} and {@code size} and
have been created, modified or accessed before or after the specified
{@code time} (depending on the given {@code -time...} options).
Matching files use at least {@code size} bytes on disk if
{@code size} is positive, or at most {@code abs(size)} bytes if
{@code size} is zero or negative. The names of the matching files
found in or below the directory specified by {@code path} are
written to the standard output.
The files names written to the output are paths relative to the
specified {@code path} operand.
*
* @param options Options for the file search.
* @param path Starting point for the search in the directory hierarchy;
wildcards * and ? are supported; relative paths are resolved on the
basis of the current working directory.
* @param size Consider only files using at least {@code size} bytes if {@code size}
is positive, or at most {@code abs(size)} bytes if {@code size} is zero
or negative.
* @param time Consider only files that have been created, modified or accessed
before or after the specified {@code time} operand; consider the
{@code -time...} options for details of the comparison.
* @param name Name pattern to match the file name after removing the path with the
leading directories; wildcards * and ? are supported, or full
regular expressions if either of the options {@code -regex (-r)} or
{@code -iregex (-i)} is specified.
* @return the generic type {@code } defined by the implementing class;
* the command itself returns no value and writes its result to the
* standard output; see class level parameter comments for more
* details
*/
R find(FindOptions options, String path, long size, java.util.Date time, String name);
}
/**
* Options for the "find" command: {@link FindOption#typeDirectory d}, {@link FindOption#typeFile f}, {@link FindOption#typeSymlink l}, {@link FindOption#typeOther x}, {@link FindOption#regex r}, {@link FindOption#ignoreCase i}, {@link FindOption#timeNewer n}, {@link FindOption#timeOlder o}, {@link FindOption#timeCreate c}, {@link FindOption#timeAccess a}, {@link FindOption#timeModified m}, {@link FindOption#print0 z}.
*
*
* {@code -d} {@code --typeDirectory} Consider only directories {@code -f} {@code --typeFile} Consider only regular files {@code -l} {@code --typeSymlink} Consider only symbolic links {@code -x} {@code --typeOther} Consider only files that are neither of directory (d),
regular file (f) or symlink (l). {@code -r} {@code --regex} Use full regular expression syntax for the patterns specified by the
name operand
(This option is ignored if no name operand is specified).
{@code -i} {@code --ignoreCase} Use case insensitive matching when applying the file name pattern
specified by the name operand
(This option is ignored if no name operand is specified).
{@code -n} {@code --timeNewer} Consider only files that have been created, modified or accessed
after or at the time specified by the time operand (the default)
(This option is ignored if no time operand is specified).
{@code -o} {@code --timeOlder} Consider only files that have been created, modified or accessed
before or at the time specified by the time operand
(This option is ignored if no time operand is specified).
{@code -c} {@code --timeCreate} The time operand refers to the creation time of the file
(This option is ignored if no time operand is specified).
{@code -a} {@code --timeAccess} The time operand refers to the last access time of the file
(This option is ignored if no time operand is specified).
{@code -m} {@code --timeModified} The time operand refers to the last modification time of the file
(the default)
(This option is ignored if no time operand is specified).
{@code -z} {@code --print0} Print the full file name on the standard output, followed by a null
character (instead of the newline character used by default). This
allows file names that contain newlines or other types of white
space to be correctly interpreted by programs that process the find
output. This option corresponds to the --delimiter0 option of xargs.
*/
public static final FindOptionSets Options = FindOptionSets.INSTANCE;
/**
* Singleton {@link FindFactory factory} instance for the "find" command.
*/
public static final FindFactory Factory = FindFactory.INSTANCE;
// no instances
private Find() {
super();
}
}