Example -ls manpage

This example demonstrates how to create the same set of options that the unix 'ls' command has. The options are implementated but the 'ls' command functionality is not.

The example uses a DocumentFormatter to format the options in the RootGroup into a unix manpage type output. If you compare the manpage for 'ls' command to the example output they are nearly identical.

Output: [Example -ls output]
Source unix manpage from which the descriptions were simply cut and pasted: link

Here is the example code:

import org.easylibs.args.Args;
import org.easylibs.args.Help;
import org.easylibs.args.Option;
import org.easylibs.args.RootGroupInfo;

public class ExampleManpageLS {

    @Help("do not ignore entries starting with .")
    @Option(aliases = "a")
    static boolean all;

    @Help("do not list implied . and ..")
    @Option(aliases = "A")
    static boolean almostAll;

    @Help("with -l, print the author of each file")
    @Option
    static boolean author;

    @Help("print C-style escapes for nongraphic characters")
    @Option(aliases = "b")
    static boolean escape;

    @Help("scale sizes by SIZE before printing them; e.g., "
            + "'--block-size=M' prints sizes in units of 1,048,576 bytes; see "
            + "SIZE format below")
    @Option
    static int bockSize;

    @Help("do not list implied entries ending with ~")
    @Option(aliases = "B")
    static boolean ignoreBackups;

    @Help("with -lt: sort by, and show, ctime (time of last modification "
            + "of file status information); with -l: show ctime and sort by "
            + "name; otherwise: sort by ctime, newest first")
    @Option(value = "c")
    static boolean sortByCtime;

    @Help("list entries by columns")
    @Option("C")
    static boolean listByColumns;

    @Help("colorize the output; WHEN can be 'always' (default if "
            + "omitted), 'auto', or 'never'; more info below")
    @Option(argName = "when")
    static String color;

    @Help("")
    @Option(aliases = "d")
    static boolean directory;

    @Help("list directories themselves, not their contents")
    @Option(aliases = "D")
    static boolean dired;

    @Help("generate output designed for Emacs' dired mode")
    @Option("f")
    static boolean doNotSort;

    @Help("do not sort, enable -aU, disable -ls --color")
    @Option(aliases = "F")
    static boolean classify;

    @Help("append indicator (one of */=>@|) to entries")
    @Option
    static boolean fileType;

    @Help("across -x, commas -m, horizontal -x, long -l, single-column -1, "
            + "verbose -l, vertical -C")
    @Option(argName = "word")
    static String format;

    @Help("like -l --time-style=full-iso")
    @Option
    static boolean fullTime;

    @Help("like -l, but do not list owner")
    @Option("g")
    static boolean longListNoOwner;

    @Help({
            "group directories before files;",
            "can be augmented with a --sort option, but any use of --sort=none (-U) disables grouping"
    })
    @Option
    static boolean groupDirectoriesFirst;

    @Help("in a long listing, don't print group names")
    @Option(aliases = "G")
    static boolean noGroup;

    @Help("with -l and/or -s, print human readable sizes (e.g., 1K 234M 2G)")
    @Option(aliases = "h")
    static boolean humanReadable;

    @Help("likewise, but use powers of 1000 not 1024")
    @Option
    static boolean si;

    @Help("follow symbolic links listed on the command line")
    @Option(aliases = "H")
    static boolean dereferenceCommandLine;

    @Help({
            "follow each command line symbolic link that points to a directory"
    })
    @Option(aliases = "G")
    static boolean dereferenceCommandLineSymlinkToDir;

    @Help("do not list implied entries matching shell PATTERN (overridden by -a or -A)")
    @Option(aliases = "p", argName = "word")
    static String indicatorStyle;

    @Help("print the index number of each file")
    @Option(aliases = "i")
    static boolean inode;

    @Help("do not list implied entries matching shell PATTERN")
    @Option(aliases = "I", argName = "pattern")
    static String ignore;

    @Help("default to 1024-byte blocks for disk usage")
    @Option(aliases = "k")
    static boolean kibibytes;

    @Help("use a long listing format")
    @Option(value = "l")
    static boolean longListing;

    @Help("when showing file information for a symbolic link, show "
            + "information for the file the link references rather than for "
            + "the link itself")
    @Option(aliases = "L")
    static boolean dereference;

    @Help("fill width with a comma separated list of entries")
    @Option(value = "m")
    static boolean fillWidth;

    @Help("like -l, but list numeric user and group IDs")
    @Option(aliases = "n")
    static boolean numericUidGid;

    @Help("print entry names without quoting")
    @Option(aliases = "N")
    static boolean literal;

    @Help("like -l, but do not list group information")
    @Option(value = "o")
    static boolean longListNoGroupInfo;

    @Help("print ? instead of nongraphic characters")
    @Option(aliases = "q")
    static String hideControlChars;

    @Help("show nongraphic characters as-is (the default, unless program "
            + "is 'ls' and output is a terminal)")
    @Option
    static boolean showControlChars;

    @Help("enclose entry names in double quotes")
    @Option(aliases = "Q")
    static boolean quoteName;

    @Help("use quoting style WORD for entry names: literal, locale, "
            + "shell, shell-always, shell-escape, shell-escape-always, c, "
            + "escape")
    @Option(argName = "word")
    static boolean quotingStyle;

    @Help("reverse order while sorting")
    @Option(aliases = "r")
    static boolean reverse;

    @Help("list subdirectories recursively")
    @Option(aliases = "R")
    static boolean recursive;

    @Help("print the allocated size of each file, in blocks")
    @Option(aliases = "s")
    static boolean size;

    @Help("sort by file size, largest first")
    @Option(value = "S")
    static boolean sortByFileSize;

    @Help("sort by WORD instead of name: none (-U), size (-S), time (-t), "
            + "version (-v), extension (-X)")
    @Option(argName = "word")
    static boolean sort;

    @Help("with -l, show time as WORD instead of default modification "
            + "time: atime or access or use (-u); ctime or status (-c); also "
            + "use specified time as sort key if --sort=time (newest first)")
    @Option(argName = "word")
    static String time;

    @Help("with -l, show times using style STYLE: full-iso, long-iso, "
            + "iso, locale, or +FORMAT; FORMAT is interpreted like in 'date'; "
            + "if FORMAT is FORMAT1<newline>FORMAT2, then FORMAT1 applies to "
            + "non-recent files and FORMAT2 to recent files; if STYLE is "
            + "prefixed with 'posix-', STYLE takes effect only outside the "
            + "POSIX locale")
    @Option(argName = "style")
    static boolean timeStyle;

    @Help("sort by modification time, newest first")
    @Property(value = "t")
    static boolean sortByModificationTime;

    @Help("assume tab stops at each COLS instead of 8")
    @Option(aliases = "T", argName = "COLS")
    static int tabsize;

    @Help("with -lt: sort by, and show, access time; with -l: show access "
            + "time and sort by name; otherwise: sort by access time, newest "
            + "first")
    @Option(value = "u")
    static boolean sortByAccessTime;

    @Help("do not sort; list entries in directory order")
    @Option(value = "U")
    static boolean sortInDirectoryOrder;

    @Help("natural sort of (version) numbers within text")
    @Option(aliases = "v")
    static boolean sortNatural;

    @Help("set output width to COLS.  0 means no limit")
    @Option(aliases = "w")
    static boolean width;

    @Help("list entries by lines instead of by columns")
    @Option(value = "x")
    static boolean listByLines;

    @Help("sort alphabetically by entry extension")
    @Option(aliases = "X")
    static boolean sortByExtension;

    @Help("print any security context of each file")
    @Option(aliases = "Z")
    static boolean context;

    @Help("list one file per line.  Avoid '\\n' with -q or -b")
    @Option(value = "1")
    static boolean list1FilePerLine;

    @Help("display this help and exit")
    @Option
    static boolean help;

    @Help("output version information and exit")
    @Option
    static boolean version;

    public static void main(String[] args) {
        final RootGroupInfo root = Args.parseArgs(args, ExampleManpageLS.class);

        DescriptionFormatter description = new DescriptionFormatter(new PosixDecorator());

        description.setTextOnTop(
                "List information about the FILEs (the current directory by default). "
                        + "Sort entries alphabetically if none of -cftuvSUX nor "
                        + "--sort is specified.",
                "Mandatory arguments to long options are mandatory for short options too.");

        description.setTextOnBottom(
                "The SIZE argument is an integer and optional unit (example: 10K is "
                        + "10*1024).  Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,..."
                        + "(powers of 1000).", 
                "Using color to distinguish file types is disabled both by default and "
                        + "with --color=never.  With --color=auto, ls emits color codes only "
                        + "when standard output is connected to a terminal.  The LS_COLORS "
                        + "environment variable can change the settings.  Use the dircolors "
                        + "command to set it.");

        description.printDocument("description", root);
    }
}