com.github.themrmilchmann.kopt:kopt

kopt

kopt is a small command line parser library for the JVM.

kopt is fully compatible with Java 8 and Kotlin 1.1 (or later).

Specification

• Command line
  

  • Terminating option parsing
    A double hyphen delimiter followed by a whitespace character (e.g. -- ) terminates option parsing. Thus, section (3) is effectively irrelevant for anything that is parsed after this character sequence and even literals prefixed with hyphens are interpreted as arguments.

• Arguments
  Arguments are interpreted index-based.

  • Optional arguments
    An argument may be optional, that is, it is not required to pass a value for said argument.

    • An optional argument must only be followed by other optional arguments.

  • Vararg arguments
    The trailing argument may be a vararg argument, that is,

    • A vararg argument must always be the trailing argument.
    • A vararg argument may be optional.

• Options
  Options are interpreted key-based.

  • Option tokens An option token is used to identify an option. Two different kinds of tokens exist.

    • Option tokens are case-sensitive.

    • Long token
      A long token is an alphanumeric literal.

      An alphanumeric literal prefixed with a double hyphen delimiter (--) is interpreted as long option token.

    • Short token
      A short token is an alphabetic character.

      An alphabetic character prefixed with a single hyphen delimiter (-) is interpreted as short option token.

      Multiple short tokens may be chained behind a single hyphen delimiter. Thus, -a -b -c and -abc are equivalent. (Furthermore, -a <value> -b <value> -c <value> and -abc <value> are equivalent.) Short tokens may only be chained if the way the represented options parse values do not conflict.

      • Default options and marker options must be followed by a value.
      • Marker options and marker-only options may not be followed by a value.
      • Default options and marker-only options may not be chained.

      An alphabetic literal prefixed with a single hyphen delimiter (-) is interpreted as a set of chained short option tokens.

    If an option token and a following string are separated by either an equals sign (=) or a single whitespace character (e.g. a space ), the string is interpreted as a value for the option represented by the token.

  • Marker options
    An option may be a marker option, that is, the option does not require a value to be passed and will instead use a predefined value if the option is present and no value is passed.
    Additionally, an option may be a marker-only option, that is, the option does not accept a value to be passed.

Grammar

Notation

This section informally explains the grammar notation used below.

Symbols and naming

• Terminal symbol names start with an uppercase letter, e.g. String.
• Nonterminal symbol names start with lowercase letter, e.g. commandLine.
• Each production starts with a colon (:).
• Symbol definitions may have many productions and are terminated by a semicolon (;).
• Symbol definitions may be prepended with attributes, e.g. start attribute denotes a start symbol.

EBNF expressions

• Operator | denotes alternative.
• Operator * denotes iteration (zero or more).
• Operator + denotes iteration (one or more).
• Operator ? denotes option (zero or one).

Syntax

start
commandLine
    : argument+ ("--" string*)?
    ;

argument
    : string
    : option
    ;
    
option
    : defaultOption
    : markerOption
    : markerOnlyOption
    ;
    
defaultOption
    : "-" ShortToken+ "=" String
    : "-" ShortToken+ " " String
    : "--" LongToken "=" String
    : "--" LongToken " " String
    ;
    
markerOption
    : defaultOption
    : markerOnlyOption
    ;

markerOnlyOption
    : "-" ShortToken+
    : "--" LongToken
    ;

ShortOptionToken
    : <any alphabetic character>
    ;
    
LongOptionToken
    : <any alphanumeric character>+
    ;

String
    : Literal
    : "\"" <any character>* "\""
    ;