tur/args
CLI argument parser with a builder-pattern API.
Since: Phase B1
args/spec-new
(args/spec-new :int)
create a new empty argument specification.
Opaque pointer (as :int) to an empty arg spec. Free with args/spec-free when done.
(let [spec (args/spec-new)] ...)
Since: Phase A1
args/spec-prog
(args/spec-prog [spec :int name :cstr] :int)
set the program name displayed in help text.
| spec | arg spec pointer from args/spec-new | |
| name | program name cstr |
The same spec pointer (mutated in place).
(args/spec-prog spec "mytool")
Since: Phase A1
args/spec-flag
(args/spec-flag [spec :int name :cstr] :int)
register a boolean flag in the arg spec.
| spec | arg spec pointer | |
| name | flag name including dashes (e.g., "--verbose") |
The same spec pointer (mutated in place).
(args/spec-flag spec "--verbose")
Since: Phase A1
args/spec-option
(args/spec-option [spec :int name :cstr type :cstr dflt :int] :int)
register a named option in the arg spec.
| spec | arg spec pointer | |
| name | option name with dashes (e.g., "--input") | |
| type | one of "string", "int", "float", "bool" | |
| dflt | default value as a cstr, or 0 if the option is required |
The same spec pointer (mutated in place).
(args/spec-option spec "--input" "string" 0) (args/spec-option spec "--count" "int" "1")
Since: Phase A1
args/spec-subcommand
(args/spec-subcommand [spec :int name :cstr sub-spec :int] :int)
register a nested subcommand.
| spec | parent arg spec pointer | |
| name | subcommand name (e.g., "build") | |
| sub-spec | arg spec for the subcommand (from args/spec-new) |
The same spec pointer (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 :int argv :int] :int)
parse a Turmeric *args* cons list against an arg spec.
| spec | arg spec pointer from args/spec-new | |
| argv | Turmeric *args* cons list (int representing the cons cell pointer) |
Opaque result pointer. Free with args/result-free when done.
(let [res (args/parse spec *args*)] ...)
Since: Phase A1
args/has?
(args/has? [result :int key :cstr] :bool)
check whether a key is present in the result.
| result | result pointer 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 :int key :cstr] :cstr)
look up a string value in the result.
| result | result pointer 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 :int key :cstr] :int)
look up an integer value in the result.
| result | result pointer 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 :int key :cstr] :bool)
look up a boolean flag value in the result.
| result | result pointer 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 :int] :cstr)
return the matched subcommand name, or 0 if none.
| result | result pointer from args/parse |
The subcommand name cstr, or 0 if no subcommand was matched.
(args/subcommand res) ; => "build"
Since: Phase A1
args/sub-result
(args/sub-result [result :int] :int)
return the result from subcommand parsing, or 0 if none.
| result | result pointer from args/parse |
The sub-result pointer, or 0 if no subcommand was matched.
(let [sub (args/sub-result res)] (args/get-bool sub "release"))
Since: Phase A1
args/positional
(args/positional [result :int] :int)
return the positional arg cons list from the result.
| result | result pointer 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 :int] :bool)
check whether parsing produced an error.
| result | result pointer 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 :int] :cstr)
return the parse error message, or 0 if no error.
| result | result pointer 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 :int] :void)
print usage information to stdout.
| spec | arg spec pointer from args/spec-new |
(args/print-help spec)
Since: Phase A1
args/spec-free
(args/spec-free [spec :int] :void)
free a spec created by args/spec-new.
| spec | arg spec pointer to free |
(args/spec-free spec)
Since: Phase A1
args/result-free
(args/result-free [result :int] :void)
free a result created by args/parse (including sub-results).
| result | result pointer to free |
(args/result-free result)
Since: Phase A1