Package org.apache.juneau.commons.runtime

Class Args

java.lang.Object
org.apache.juneau.commons.runtime.Args
public class Args extends Object
Lean parser for command-line arguments passed in through a main(String[] args) method.

Supports the following grammars (all enabled by default; toggle via Args.Builder):

  • Positional arguments — any token that does not start with a recognized flag prefix.
  • Short flags — -key value (and repeated -key v1 -key v2 to collect multiple values).
  • Long flags — --key value.
  • Equals form — --key=value / -key=value.
  • System-property style — -Dkey=value (the leading D is stripped).

Positional arguments are only collected before the first flag is seen; once a flag appears, every subsequent non-flag token becomes a value of the most recently seen flag. This matches the legacy parsing rule and is preserved for backwards compatibility.

Example:

// Wrap raw command-line args. Args args = new Args(argv); // Positional access. args.get(0).ifPresent(System.out::println); // Named lookup with conversion via Optional.map(...). int port = args.get("port").map(Integer::parseInt).orElse(8080); // Multi-value flag. List<String> tags = args.getAll("tag"); // Custom grammar. Args strict = Args.create().allowEquals(false).caseSensitive(false).build(argv);

Notes:
  • This class is immutable and thread-safe once constructed.
  • get(String) returns the first value when a flag is repeated; use getAll(String) for the full list.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Args.Builder
    Builder for Args with configurable grammar hooks.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Args(String line)
    Constructor that parses a raw command-line string using the default grammar.
    Args(String[] argv)
    Constructor that parses an argv array using the default grammar.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    argCount()
    Returns the number of positional arguments.
    Map<String,List<String>>
    asMap()
    Returns the named-option contents as an unmodifiable map.
    static Args.Builder
    create()
    Creates a new builder for parsing arguments with non-default grammar.
    Optional<String>
    get(int index)
    Returns the positional argument at the specified zero-based index.
    Optional<String>
    get(String key)
    Returns the first value of the named option, or empty if the option was not set.
    List<String>
    getAll(String key)
    Returns all values for the named option in the order they appeared on the command line.
    boolean
    has(int index)
    Returns true if a positional argument exists at the given index.
    boolean
    has(String key)
    Returns true if the named option appears in the parsed args (even if no values were supplied).
    boolean
    isEmpty()
    Returns true if no positional arguments and no named options were captured.
    int
    optionCount()
    Returns the number of distinct named options.
    List<String>
    positional()
    Returns the positional arguments in the order they appeared on the command line.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Args

      public Args(String line)
      Constructor that parses a raw command-line string using the default grammar.

      The string is split on whitespace honouring single- and double-quoted segments via StringUtils.splitQuoted(String).

      Parameters:
      line - The raw command line. Can be null (treated as an empty argv).

    • Args

      public Args(String[] argv)
      Constructor that parses an argv array using the default grammar.
      Parameters:
      argv - The arguments passed in through a main(String[] args) method. Can be null (treated as an empty argv).

  • Method Details

    • create

      public static Args.Builder create()
      Creates a new builder for parsing arguments with non-default grammar.
      Returns:
      A new builder.

    • get

      public Optional<String> get(int index)
      Returns the positional argument at the specified zero-based index.
      Parameters:
      index - The position.
      Returns:
      The argument value, or empty if index is out of range.

    • get

      public Optional<String> get(String key)
      Returns the first value of the named option, or empty if the option was not set.

      If the option was specified multiple times (e.g. -tag a -tag b), this returns only the first value. Use getAll(String) to get the full list.

      Parameters:
      key - The option name (without the flag prefix).
      Returns:
      The first value, or empty if the key is unset or has no values.

    • getAll

      public List<String> getAll(String key)
      Returns all values for the named option in the order they appeared on the command line.
      Parameters:
      key - The option name (without the flag prefix).
      Returns:
      All values, or an empty list if the key is unset.

    • positional

      public List<String> positional()
      Returns the positional arguments in the order they appeared on the command line.
      Returns:
      An unmodifiable list of positional arguments.

    • argCount

      public int argCount()
      Returns the number of positional arguments.
      Returns:
      The count.

    • optionCount

      public int optionCount()
      Returns the number of distinct named options.
      Returns:
      The count.

    • isEmpty

      public boolean isEmpty()
      Returns true if no positional arguments and no named options were captured.
      Returns:
      true if both axes are empty.

    • has

      public boolean has(int index)
      Returns true if a positional argument exists at the given index.
      Parameters:
      index - The zero-based index.
      Returns:
      true if an argument exists at that index.

    • has

      public boolean has(String key)
      Returns true if the named option appears in the parsed args (even if no values were supplied).
      Parameters:
      key - The option name.
      Returns:
      true if the option was set.

    • asMap

      public Map<String,List<String>> asMap()
      Returns the named-option contents as an unmodifiable map.

      Positional arguments are not included — use positional() for those.

      Returns:
      An unmodifiable map of named options to their value lists.