DOCSEARCHbyAlgolia
Submit Docs

args4j Documentation

repository·master·Indexed 21 days ago

https://github.com/kohsuke/args4j

A lightweight Java library for command-line argument parsing using annotations. It supports javac-style option parsing, automatic usage text generation, and localization. The library includes args4j-tools, an Annotation Processing Tool (APT) capable of generating HTML, XML, or TXT documentation from Java source files.

Tokens
977
Snippets
3
Records
4
Agent score
24%

What's inside args4j

  1. Overview of args4j

    master

    args4j is a lightweight Java library designed to simplify command-line argument parsing for CUI (Character User Interface) applications. It uses annotations to map command-line options directly to Java fields, making the parsing process intuitive and reducing boilerplate code.

    Key features include:

    • Annotation-based parsing: Map arguments to fields using simple annotations.
    • Automatic usage generation: Easily generate usage text for your CLI.
    • Documentation generation: Generate HTML or XML documentation listing all available options.
    • Localization: Full support for localizing command-line interface text.
    • javac-style parsing: Designed to parse options in the style of javac rather than GNU-style (e.g., it treats -lR as a single option with two flags rather than two separate options l and R).
    • MIT License: Permissive licensing for use in any project.

  2. How to use args4j in your project

    master

    To integrate args4j into your Java application, follow these steps:

    1. Add the dependency: Download the distribution or include the library via the Maven Repository.
    2. Define your arguments: Create a Java class where fields represent your command-line options. Annotate these fields to define how they should be parsed.
    3. Parse the arguments: Use the CmdLineParser to populate your annotated class with values from the String[] args array provided to your main method.

    For a concrete implementation pattern, refer to the SampleMain.java example in the repository.

    // Conceptual pattern based on args4j usage
public class MyArgs {
    @Option(name="-f", usage="the file to process")
    String filename;

    @Option(name="-v", usage="verbose mode")
    boolean verbose;
}

// In your main method:
MyArgs args = new MyArgs();
CmdLineParser parser = new CmdLineParser(args);
parser.parseArgument(argsArray);

  3. Configure args4j-tools CLI options

    master

    When running the args4j-tools command, you can use the following options to control the output format and location:

    OptionUsageDescription
    -ooutput directoryThe directory where the generated HTML/XML files will be placed.
    -mode'XML', 'TXT', or 'HTML'The output format for the generated documentation. Defaults to HTML.
    -resresource file nameA resource file used to obtain usage strings. When provided, the value of Option.usage() is treated as a key to look up strings in this resource.

    Note: The command requires at least one source file as an argument to execute.

    -o <directory>      output directory to place generated HTML/XML
-mode <format>       output format. 'XML' 'TXT' or 'HTML'
-res <resource>      resource file name to obtain usage strings from.
                     Using this option will cause Option.usage() to be used as a key to this resource

  4. Use the args4j-tools CLI to generate documentation

    master

    The args4j-tools CLI (implemented via org.kohsuke.args4j.apt.Main) is an Annotation Processing Tool (APT) that generates documentation (HTML, XML, or TXT) from command line annotations in your Java source files. It works by invoking the system Java compiler with a specific annotation processor that extracts usage information.

    args4j-tools [options...] sourcefiles...