Zena
On this page

zena:args

zena
import {…} from 'zena:args';

Command-line argument parsing with flags, options, positional arguments, subcommands, and help text generation.

Examples ​

zena
import { ArgParser, OptionType } from 'zena:args';
import { getArguments } from 'zena:cli';

let parser = new ArgParser('mytool')
  .addOption('verbose', {
    type: OptionType.Flag,
    abbr: 'v',
    help: 'Enable verbose logging',
  })
  .addOption('output', {
    abbr: 'o',
    defaultVal: 'out.txt',
    help: 'Output file path',
  });

let parsed = parser.parse(getArguments(), 1);
let verbose = parsed.getFlag('verbose');
let output = parsed.getOption('output') ?? 'out.txt';

Classes

ParsedValue

zena
sealed class ParsedValue

A parsed command-line option value.

Variants
zena
case Flag(value: boolean)
#
zena
case Single(value: String)
#
zena
case Multi(values: GrowableArray<String>)
#

ParsedArgs

zena
class ParsedArgs

The results of parsing command-line arguments.

Constructors
zena
new()
#
Properties
zena
options: HashMap<String, ParsedValue>
#

The parsed options by name.

zena
rest: GrowableArray<String>
#

Positional arguments not consumed as options or subcommands.

zena
commandName: String | null
#

The subcommand invoked, or null if no subcommand was matched.

zena
commandArgs: ParsedArgs | null
#

The parsed arguments for the invoked subcommand, or null.

Methods
zena
getFlag(name: String): boolean
#

Returns true if the named boolean flag was set, or its default value.

zena
getOption(name: String): inline (true, String) | inline (false, _)
#

Returns the value of the named option as an inline tuple: (true, value) if the option was set, or (false, _) if not.

To fallback to a default value, use getOption(name) ?? fallback.

zena
getInt(name: String): inline (true, i32) | inline (false, _)
#

Returns the integer value of the named option, or fallback if not set or not a valid integer.

zena
getMultiOption(name: String): Array<String>
#

Returns all values passed for a repeatable multi-option.

zena
get(name: String): inline (true, ParsedValue) | inline (false, _)
#

Returns the parsed value for the named option, or not found.

zena
hasOption(name: String): boolean
#

Returns true if the option was passed on the command line or has a default.

ArgParser

zena
class ArgParser

Configurable command-line argument parser.

ArgParser defines options, flags, and subcommands, parses raw argument strings (e.g. from zena:cli's getArguments()), and formats standard --help usage messages.

Defining Options & Commands ​

Options and subcommands can be configured either declaratively in the constructor (or new ArgParser.fromConfig(config)), or incrementally with addOption and addCommand:

zena
let parser = new ArgParser('mytool', 'A sample CLI utility', {
  'verbose' => {type: OptionType.Flag, abbr: 'v', help: 'Enable verbose
     output'},
  'output'  => {abbr: 'o', help: 'Output file path', defaultVal: 'out.txt'},
  'count'   => {type: OptionType.Int, abbr: 'n', help: 'Number of items'},
}, {
  'build'   => {help: 'Build the project', options: {'release' => {type:
     OptionType.Flag}}},
});

Supported Argument Syntax ​

  • Flags: --flag, short -f, negated --no-flag, or combined short flags -vfg
  • Options: --opt value, --opt=value, -o value, -o=value, or attached -oval
  • Delimiter: -- treats all subsequent arguments as positional rest values
  • Subcommands: Dispatched to the matching subcommand's parser

Call parser.parse(args, startIndex) to produce a ParsedArgs instance, or parser.formatHelp() to generate usage documentation.

Constructors
zena
new(options: Map<String, OptionConfig> | null = null, commands: Map<String, CommandConfig> | null = null)
#
zena
new fromConfig(config: ParserConfig)
#
Properties
zena
programName: String
#
zena
description: String
#
Methods
zena
addOption(name: String, config: OptionConfig = {}): ArgParser
#

Adds an option declaratively.

zena
addOptions(options: Map<String, OptionConfig>): ArgParser
#

Adds multiple options declaratively from a map.

zena
addCommand(name: String, config: CommandConfig = {}): ArgParser
#

Adds a subcommand with its own parser.

zena
addCommands(commands: Map<String, CommandConfig>): ArgParser
#

Adds multiple subcommands declaratively from a map.

zena
parse(args: Array<String>, startIndex: i32 = 0): ParsedArgs
#

Parses the given array of argument strings.

args

The arguments to parse (e.g. from getArguments())

startIndex

The index to start parsing from (typically 0 or 1)

zena
formatHelp(): String
#

Formats a standard help and usage message.

Enums

OptionType

zena
enum OptionType

The type of a command-line option.

Members
zena
StringVal
#

A key-value string option (--opt , --opt=, -o ). Default.

zena
Flag
#

A boolean toggle (--flag, -f, --no-flag).

zena
Int
#

An integer number option (--count 42).

zena
MultiString
#

A repeatable string option collecting multiple values (--dir ).

Type aliases

OptionConfig

zena
type OptionConfig = {name?: String, type?: OptionType, abbr?: String, defaultVal?: String | null, allowed?: Array<String> | null, help?: String, description?: String}

Configuration for a single command-line option.

CommandConfig

zena
type CommandConfig = {description?: String, help?: String, options?: Map<String, OptionConfig>}

Configuration for a subcommand.

ParserConfig

zena
type ParserConfig = {name: String, description?: String, help?: String, options?: Map<String, OptionConfig>, commands?: Map<String, CommandConfig>}

Configuration for an entire command-line parser.

Functions

parseArgs

zena
function parseArgs(args: Array<String>, options: Map<String, OptionConfig>, offset: i32 = 0): ParsedArgs

Convenience function to parse arguments using a map of option specifications.

args

The command-line argument array (e.g. from getArguments())

options

A map of option specifications

offset

The starting index in args to parse from (default: 0)

Returns

Parsed arguments result