# std.args

Command-line argument parsing utilities.

```tea
use args from "std.args"
```

Examples may be fragments requiring the module import or additional setup.

## std.args.all

```tea
pub def all() -> List[String]
```

Return all command-line arguments as a list of strings.

```tea
# Running: tea script.tea arg1 arg2
const all = args.all()  # ["arg1", "arg2"]
```

## std.args.program

```tea
pub def program() -> String
```

Return the program name (argv[0] with path stripped).

```tea
# Running: tea script.tea
const name = args.program()  # "script"

# Running: ./bin/myapp
const name = args.program()  # "myapp"
```

## std.args.parse

```tea
pub def parse[T](spec: T) -> CliParseResult
```

Parse command-line arguments using a declarative command spec.

## std.args.parse_with

```tea
pub def parse_with[T](spec: T, argv: List[String]) -> CliParseResult
```

Parse an explicit argv list using a declarative command spec.

```tea
use args from "std.args"
use json from "std.json"

const spec = json.decode[Dict[String, Dynamic]](`{
  "name": "greet",
  "options": [
    {"name": "count", "aliases": ["--count"], "kind": "option", "type": "int"},
    {"name": "verbose", "aliases": ["-v"], "kind": "flag"}
  ],
  "positionals": [{"name": "name", "type": "string"}]
}`)
const parsed = args.parse_with(spec, ["--count", "3", "-v", "Ada"])
@println(parsed.ok) # true
@println(args.option_int_or(parsed, "count", 1)) # 3
@println(args.flag(parsed, "verbose")) # true
@println(args.positional_or(parsed, "name", "world")) # Ada
```

## std.args.require

```tea
pub def require(parsed: CliParseResult) -> CliParseResult ! ArgsError.Usage
```

Require a parsed CLI result to be successful.

## std.args.has

```tea
pub def has(flag_name: String) -> Bool
```

Check if a flag is present in the arguments.

```tea
if args.has("--verbose")
  @println("Verbose mode enabled")
end

if args.has("-v") || args.has("--verbose")
  verbose = true
end
```

## std.args.get

```tea
pub def get(option_name: String) -> String?
```

Get the value of an option argument.

```tea
# Running: tea script.tea --output result.txt
const output = args.get("--output")  # "result.txt"

# Running: tea script.tea --verbose
const output = args.get("--output")  # nil

# With default value
const output = args.get("--output") ?? "default.txt"
```

## std.args.positional

```tea
pub def positional() -> List[String]
```

Return positional arguments (arguments that are not flags or option values).

```tea
# Running: tea script.tea --verbose file1.txt file2.txt
const files = args.positional()  # ["file1.txt", "file2.txt"]

# Running: tea script.tea -o output.txt input.txt
const files = args.positional()  # ["input.txt"]
```

## std.args.option_string

```tea
pub def option_string(parsed: CliParseResult, name: String) -> String?
```

Return an optional parsed string option value by name.

## std.args.option_int

```tea
pub def option_int(parsed: CliParseResult, name: String) -> Int?
```

Return an optional parsed integer option value by name.

## std.args.option_bool

```tea
pub def option_bool(parsed: CliParseResult, name: String) -> Bool?
```

Return an optional parsed boolean option value by name.

## std.args.flag

```tea
pub def flag(parsed: CliParseResult, name: String) -> Bool
```

Return true when a parsed command result contains a specific flag option.

## std.args.option_string_or

```tea
pub def option_string_or(parsed: CliParseResult, name: String, fallback: String) -> String
```

Return a string option value or a fallback.

## std.args.option_int_or

```tea
pub def option_int_or(parsed: CliParseResult, name: String, fallback: Int) -> Int
```

Return an integer option value or a fallback.

```tea
use args from "std.args"
use json from "std.json"

const spec = json.decode[Dict[String, Dynamic]](`{
  "name": "greet",
  "options": [{"name": "count", "aliases": ["--count"], "kind": "option", "type": "int"}]
}`)
const parsed = args.parse_with(spec, [])
@println(args.option_int_or(parsed, "count", 1)) # 1
```

## std.args.require_option_string

```tea
pub def require_option_string(parsed: CliParseResult, name: String) -> String ! ArgsError.MissingOption
```

Return a string option value or throw when it is missing.

## std.args.require_option_int

```tea
pub def require_option_int(parsed: CliParseResult, name: String) -> Int ! ArgsError.MissingOption
```

Return an integer option value or throw when it is missing.

## std.args.positional_value

```tea
pub def positional_value(parsed: CliParseResult, name: String) -> String?
```

Return an optional positional value by name.

## std.args.positional_or

```tea
pub def positional_or(parsed: CliParseResult, name: String, fallback: String) -> String
```

Return a positional value or a fallback.

## std.args.require_positional

```tea
pub def require_positional(parsed: CliParseResult, name: String) -> String ! ArgsError.MissingPositional
```

Return a positional value or throw when it is missing.

## std.args.subcommand

```tea
pub def subcommand(parsed: CliParseResult) -> String?
```

Return the selected subcommand when one was provided.

```tea
use args from "std.args"
use json from "std.json"

const spec = json.decode[Dict[String, Dynamic]](`{"name": "todo", "subcommands": [{"name": "list"}, {"name": "add"}]}`)
const parsed = args.parse_with(spec, ["list"])
@println(args.subcommand(parsed) ?? "help") # list
@println(args.command_is(parsed, "list")) # true
```

## std.args.require_subcommand

```tea
pub def require_subcommand(parsed: CliParseResult) -> String ! ArgsError.MissingCommand
```

Return the selected subcommand or throw when no subcommand was chosen.

## std.args.command_is

```tea
pub def command_is(parsed: CliParseResult, name: String) -> Bool
```

Return true when the current parsed command matches a given command name.