args Command-Line Interaction

args is Alia's standard library command-line interaction module, providing command-line argument definition, parsing, callback triggering, help generation, and more.

Importing the Module

import 'args' as args ~ import as a variable
import 'args' ~ import into scope

Creating a Parser

create

Creates an argument parser instance and returns an ArgsParser object.

Parameter	Type	Required	Description
Argument after named	String	No	Application name, used in help text
Argument after described	String	No	Application description, used in help text

const parser = args.create named 'myapp' described 'My application'

Parser Methods

addOption

Adds a command-line option that takes a value (e.g. --name value).

Parameter	Type	Required	Description
First positional argument	String	Yes	Flag definition, e.g. '-n --name', with the short/long flags separated by spaces
type	String	No	Value type: 'String' (default), 'Number', 'Boolean'
default	Value	No	Default value
required	Boolean	No	Whether it is required, defaults to false
description	String	No	Option description, used in help text
action	Alias	No	Callback, triggered when the option is parsed; receives the parsed value

parser.addOption '-n --name' type 'String' required true description 'Your name' action (alias -> <String value> {
  print 'Hello, ' .. value
})

parser.addOption '-c --count' type 'Number' default 1 description 'Repeat count'

addFlag

Adds a boolean flag (no value needed; its presence means true).

Parameter	Type	Required	Description
First positional argument	String	Yes	Flag definition, e.g. '-v --verbose'
description	String	No	Flag description
action	Alias	No	Callback, triggered when the flag is parsed; takes no arguments

parser.addFlag '-v --verbose' description 'Enable verbose mode' action (alias -> {
  print 'Verbose mode enabled'
})

addArgument

Adds a positional argument definition.

Parameter	Type	Required	Description
First positional argument	String	Yes	Argument name
description	String	No	Argument description
required	Boolean	No	Whether it is required, defaults to false
default	Value	No	Default value
action	Alias	No	Callback, triggered when the argument is parsed; receives the parsed value

parser.addArgument 'input' description 'Input file path' required true action (alias -> <String value> {
  print 'Reading from ' .. value
})
parser.addArgument 'output' description 'Output file path'

parse

Performs argument parsing and returns the parsed result object. During parsing, the action callback of each argument is triggered in match order.

Parameter	Type	Required	Description
Arguments to parse	String	No	Can be passed one by one; if omitted, process.argv is used

The returned object has the following structure:

Property	Type	Description
options	Object	Option key-value pairs
arguments	Object	Positional argument key-value pairs

const parsed = call parser.parse
print parsed.options.name
print parsed.arguments.input

get

Gets the value with the given name from the parse result. Returns Null if nothing has been parsed or the name does not exist.

const name = parser.get 'name'
const verbose = parser.get 'verbose'

help

Generates and returns a formatted help text string.

print call parser.help

Parsing Rules

Input form	Description
--long value	Long option with a value (space-separated)
--long=value	Long option with a value (equals-separated)
--flag	Boolean flag; its presence means true
-v	Short flag
-vf	Combined short flags, equivalent to -v -f
-n value	Short option with a value
Not starting with -	Matched as a positional argument in definition order
--	Everything after it is treated as positional arguments

Example Code

import 'args' as args

const parser = args.create named 'greet' described 'A greeting CLI tool'

parser.addFlag '-v --verbose' description 'Enable verbose output' action (alias -> {
  print '[verbose] Starting...'
})

parser.addOption '-n --name' type 'String' required true description 'Name to greet'

parser.addOption '-c --count' type 'Number' default 1 description 'Greeting count'

parser.addArgument 'greeting' description 'Greeting word' default 'Hello'

const parsed = call parser.parse

const name = parser.get 'name' as String
const count = parser.get 'count' as Number
const greeting = parser.get 'greeting' as String

let i = 0
while i < count {
  print greeting .. ', ' .. name .. '!'
  i++
}

Command-line invocation:

alia greet.alia -v --name Alice -c 3 Hi
~ [verbose] Starting...
~ Hi, Alice!
~ Hi, Alice!
~ Hi, Alice!

Next Steps

• io Input and Output