tur/args
CLI argument parser with a builder-pattern API.
Since: Phase B1
ArgSpec
(ArgSpec)
ArgResult
(ArgResult)
args/spec-new
(args/spec-new :)
create a new empty argument specification.
A fresh ArgSpec handle. Free with args/spec-free when done.
(let [spec (args/spec-new)] ...)
Since: Phase A1
args/spec-prog
(args/spec-prog [spec : ArgSpec name : cstr] :)
set the program name displayed in help text.
| spec | ArgSpec handle from args/spec-new | |
| name | program name cstr |
The same ArgSpec (mutated in place).
(args/spec-prog spec "mytool")
Since: Phase A1
args/spec-flag
(args/spec-flag [spec : ArgSpec name : cstr] :)
register a boolean flag in the arg spec.
| spec | ArgSpec handle | |
| name | flag name including dashes (e.g., "--verbose") |
The same ArgSpec (mutated in place).
(args/spec-flag spec "--verbose")
Since: Phase A1
args/-no-default
(args/-no-default :)
the NULL cstr the option cell stores for "required".
args/-spec-option-raw
(args/-spec-option-raw [spec : ArgSpec name : cstr type : cstr dflt : cstr] :)
register an option whose default is a cstr or NULL.
args/spec-option
(args/spec-option [spec : ArgSpec name : cstr type : cstr dflt : (Option cstr)] :)
register a named option in the arg spec.
| spec | ArgSpec handle | |
| name | option name with dashes (e.g., "--input") | |
| type | one of "string", "int", "float", "bool" | |
| dflt | (some "value") for a default, (none) if the option is required |
The same ArgSpec (mutated in place).
(args/spec-option spec "--input" "string" (none)) (args/spec-option spec "--count" "int" (some "1"))
Since: Phase A1
args/spec-subcommand
(args/spec-subcommand [spec : ArgSpec name : cstr sub-spec : ArgSpec] :)
register a nested subcommand.
| spec | parent ArgSpec handle | |
| name | subcommand name (e.g., "build") | |
| sub-spec | ArgSpec for the subcommand (from args/spec-new) |
The same parent ArgSpec (mutated in place).
(let [sub (args/spec-new)]
(args/spec-flag sub "--release")
(args/spec-subcommand spec "build" sub))
Since: Phase A1
args/parse
(args/parse [spec : ArgSpec argv : int] :)
parse a Turmeric *args* cons list against an arg spec.
| spec | ArgSpec handle from args/spec-new | |
| argv | Turmeric *args* cons list (the elaborator declares *args* itself | |
| as :int, so this slot matches that global's own type) |
An ArgResult handle. Free with args/result-free when done.
(let [res (args/parse spec *args*)] ...)
Since: Phase A1
args/has?
(args/has? [result : ArgResult key : cstr] :)
check whether a key is present in the result.
| result | ArgResult handle from args/parse | |
| key | option or flag name without dashes (e.g., "verbose") |
true if the key was parsed or injected via a default.
(args/has? res "verbose") ; => true if --verbose was passed
Since: Phase A1
args/get-str
(args/get-str [result : ArgResult key : cstr] :)
look up a string value in the result.
| result | ArgResult handle from args/parse | |
| key | option name without dashes (e.g., "input") |
The string value, or 0 (NULL) if the key is not present.
(args/get-str res "input") ; => "file.txt"
Since: Phase A1
args/get-int
(args/get-int [result : ArgResult key : cstr] :)
look up an integer value in the result.
| result | ArgResult handle from args/parse | |
| key | option name without dashes |
The parsed integer value, or 0 if the key is not present.
(args/get-int res "count") ; => 5
Since: Phase A1
args/get-bool
(args/get-bool [result : ArgResult key : cstr] :)
look up a boolean flag value in the result.
| result | ArgResult handle from args/parse | |
| key | flag name without dashes (e.g., "verbose") |
true if the flag was set (value is "1", "true", "yes", or "on").
(args/get-bool res "verbose") ; => true if --verbose was passed
Since: Phase A1
args/subcommand
(args/subcommand [result : ArgResult] :)
return the matched subcommand name, or 0 if none.
| result | ArgResult handle from args/parse |
The subcommand name cstr, or 0 if no subcommand was matched.
(args/subcommand res) ; => "build"
Since: Phase A1
args/-sub-result-raw
(args/-sub-result-raw [result : ArgResult] :)
the raw sub-result slot (0 when no subcommand ran).
args/sub-result
(args/sub-result [result : ArgResult] :)
the result from subcommand parsing, if one matched.
| result | ArgResult handle from args/parse |
(some sub-result) if a subcommand was matched, (none) otherwise.
(let [sub (args/sub-result res)]
(match sub
(Some s) (args/get-bool s "release")
(None) false))
Since: Phase A1
args/positional
(args/positional [result : ArgResult] :)
return the positional arg cons list from the result.
| result | ArgResult handle from args/parse |
A Turmeric cons list (int64_t) of remaining positional cstr args.
(args/positional res) ; => cons list
Since: Phase A1
args/error?
(args/error? [result : ArgResult] :)
check whether parsing produced an error.
| result | ArgResult handle from args/parse |
true if the result contains a parse error.
(args/error? res) ; => true if an unknown flag was passed
Since: Phase A1
args/error-msg
(args/error-msg [result : ArgResult] :)
return the parse error message, or 0 if no error.
| result | ArgResult handle from args/parse |
The error message cstr, or 0 if there was no error.
(args/error-msg res) ; => "required option --input not provided"
Since: Phase A1
args/print-help
(args/print-help [spec : ArgSpec] :)
print usage information to stdout.
| spec | ArgSpec handle from args/spec-new |
(args/print-help spec)
Since: Phase A1
args/spec-free
(args/spec-free [spec : ArgSpec] :)
free a spec created by args/spec-new.
| spec | ArgSpec handle to free |
(args/spec-free spec)
Since: Phase A1
args/result-free
(args/result-free [result : ArgResult] :)
free a result created by args/parse (including sub-results).
| result | ArgResult handle to free |
(args/result-free result)
Since: Phase A1