tur/args

(defopaque ArgSpec : int)

(defopaque ArgResult : int)

(args/spec-new : ArgSpec)

create a new empty argument specification.

(let [spec (args/spec-new)] ...)

Since: Phase A1

(args/spec-prog [spec : ArgSpec name : cstr] : ArgSpec)

set the program name displayed in help text.

(args/spec-prog spec "mytool")

Since: Phase A1

(args/spec-flag [spec : ArgSpec name : cstr] : ArgSpec)

register a boolean flag in the arg spec.

(args/spec-flag spec "--verbose")

Since: Phase A1

(args/-no-default : cstr)

the NULL cstr the option cell stores for "required".

(args/-spec-option-raw [spec : ArgSpec name : cstr type : cstr dflt : cstr] : ArgSpec)

register an option whose default is a cstr or NULL.

(args/spec-option [spec : ArgSpec name : cstr type : cstr dflt : (Option cstr)] : ArgSpec)

register a named option in the arg spec.

(args/spec-option spec "--input" "string" (none))
(args/spec-option spec "--count" "int" (some "1"))

Since: Phase A1

(args/-set-implicit [spec : ArgSpec implicit : cstr] : ArgSpec)

give the most recently registered option an implicit value.

(args/spec-option-implicit [spec : ArgSpec name : cstr type : cstr dflt : (Option cstr) implicit : cstr] : ArgSpec)

register an option whose value may be left out.

Like args/spec-option, but the option may also be given bare: --name with no =value stands for implicit. A value must then be attached with = (--name=value); the next word is never taken as the value, so --isolate dist is --isolate followed by the positional dist. Left out entirely, the option takes dflt as usual.

(args/spec-option-implicit spec "--color" "string" (some "never") "always")
;; (no flag) => "never", --color => "always", --color=auto => "auto"

Since: tur serve --isolate

(args/spec-subcommand [spec : ArgSpec name : cstr sub-spec : ArgSpec] : ArgSpec)

register a nested subcommand.

(let [sub (args/spec-new)]
  (args/spec-flag sub "--release")
  (args/spec-subcommand spec "build" sub))

Since: Phase A1

(args/spec-short [spec : ArgSpec short-name : cstr long-name : cstr] : ArgSpec)

register a short spelling for a flag or an option.

A token equal to short-name is read as long-name before anything else looks at it, so -p 8080 is --port 8080 and -q is --quiet. Only the whole token is matched: -p8080 and bundled -qv are not split. long-name may also be "--help", which is always accepted.

(args/spec-short spec "-p" "--port")

Since: project-less-tools-plan PT1

(args/parse [spec : ArgSpec argv : int] : ArgResult)

parse a Turmeric *args* cons list against an arg spec.

Accepts both --key=value (preferred) and --key value forms for options; an option registered with args/spec-option-implicit takes only --key=value, and a bare --key stands for its implicit value. Flags are set to "1" when present. --help is always accepted. The first non-flag token matching a registered subcommand name triggers recursive dispatch: remaining tokens are parsed against the sub-spec. Defaults are injected after parsing; required options that are missing produce an error in the result.

(let [res (args/parse spec *args*)] ...)

Since: Phase A1

(args/has? [result : ArgResult key : cstr] : bool)

check whether a key is present in the result.

(args/has? res "verbose")  ; => true if --verbose was passed

Since: Phase A1

(args/get-str [result : ArgResult key : cstr] : cstr)

look up a string value in the result.

(args/get-str res "input")  ; => "file.txt"

Since: Phase A1

(args/get-int [result : ArgResult key : cstr] : int)

look up an integer value in the result.

(args/get-int res "count")  ; => 5

Since: Phase A1

(args/get-bool [result : ArgResult key : cstr] : bool)

look up a boolean flag value in the result.

(args/get-bool res "verbose")  ; => true if --verbose was passed

Since: Phase A1

(args/subcommand [result : ArgResult] : cstr)

return the matched subcommand name, or 0 if none.

(args/subcommand res)  ; => "build"

Since: Phase A1

(args/-sub-result-raw [result : ArgResult] : int)

the raw sub-result slot (0 when no subcommand ran).

(args/sub-result [result : ArgResult] : (Option ArgResult))

the result from subcommand parsing, if one matched.

(let [sub (args/sub-result res)]
  (match sub
    (Some s) (args/get-bool s "release")
    (None)   false))

Since: Phase A1

(args/positional [result : ArgResult] : int)

return the positional arg cons list from the result.

The list is in reverse order (last positional arg is the head).

(args/positional res)  ; => cons list

Since: Phase A1

(args/error? [result : ArgResult] : bool)

check whether parsing produced an error.

(args/error? res)  ; => true if an unknown flag was passed

Since: Phase A1

(args/error-msg [result : ArgResult] : cstr)

return the parse error message, or 0 if no error.

(args/error-msg res)  ; => "required option --input not provided"

Since: Phase A1

(args/print-help [spec : ArgSpec] : void)

print usage information to stdout.

(args/print-help spec)

Since: Phase A1

(args/spec-free [spec : ArgSpec] : void)

free a spec created by args/spec-new.

Does not free sub-specs registered via args/spec-subcommand; the caller must free those separately.

(args/spec-free spec)

Since: Phase A1

(args/result-free [result : ArgResult] : void)

free a result created by args/parse (including sub-results).

(args/result-free result)

Since: Phase A1