class
Jargon::CLI
- Jargon::CLI
- Reference
- Object
Defined in:
jargon/cli.crjargon/config.cr
jargon/help.cr
Constructors
-
.from_file(path : String, program_name : String = "cli") : CLI
Create a CLI from a JSON or YAML schema file.
-
.from_json(json : String, program_name : String = "cli") : CLI
Create a CLI from a JSON schema string.
-
.from_yaml(yaml : String, program_name : String = "cli") : CLI
Create a CLI from a YAML schema string.
- .new(schema : Schema, program_name : String = "cli")
- .new(program_name : String)
Instance Method Summary
-
#bash_completion(command : String = @program_name) : String
Generate a shell completion shim.
-
#completer(path : String, &block : Completion::Context -> Array(String))
Register a dynamic completer for a field, identified by its dotted path: the field name for a flat CLI, or
subcommand.field(a.b.fieldwhen nested). - #completers : Hash(String, Proc(Completion::Context, Array(String)))
-
#config_paths : Array(String)
Returns the list of config paths that would be searched
- #default_subcommand(name : String)
- #default_subcommand : String | Nil
- #fish_completion(command : String = @program_name) : String
-
#handle_completion(args : Array(String) = ARGV, *, io : IO = @output, exit_process : Bool = true) : Bool
If this invocation is a completion request (the hidden
__completeverb), print candidates and — unlessexit_process: false— exit 0. - #help(subcommand : String) : String
- #help : String
- #json(args : Array(String), input : IO, *, defaults : JSON::Any | Hash(String, JSON::Any) | Nil = nil) : JSON::Any
-
#json(args : Array(String) = ARGV, *, defaults : JSON::Any | Hash(String, JSON::Any) | Nil = nil) : JSON::Any
Return just the parsed data as JSON.
-
#load_config(*, merge : Bool = true) : JSON::Any | Nil
Load config from standard locations.
- #output : IO
- #output=(output : IO)
- #parse(args : Array(String), input : IO, *, defaults : JSON::Any | Hash(String, JSON::Any) | Nil = nil) : Result
-
#parse(args : Array(String) = ARGV, *, defaults : JSON::Any | Hash(String, JSON::Any) | Nil = nil) : Result
Parse arguments and return full Result with errors array.
- #program_name : String
- #run(args : Array(String), input : IO, *, defaults : JSON::Any | Hash(String, JSON::Any) | Nil = nil) : Result
-
#run(args : Array(String) = ARGV, *, defaults : JSON::Any | Hash(String, JSON::Any) | Nil = nil) : Result
Run the CLI with automatic --help, --completions, and error handling.
- #run(args : Array(String), input : IO, *, defaults : JSON::Any | Hash(String, JSON::Any) | Nil = nil, &) : Nil
- #run(args : Array(String) = ARGV, *, defaults : JSON::Any | Hash(String, JSON::Any) | Nil = nil, &) : Nil
- #schema : Schema | Nil
- #subcommand(name : String, schema : Schema)
- #subcommand(name : String, cli : CLI)
- #subcommand(name : String, *, json : String)
- #subcommand(name : String, *, yaml : String)
-
#subcommand(name : String, *, file : String)
Load subcommand(s) from a file.
-
#subcommand(*, file : String)
Load subcommands from a multi-document file (no parent name).
- #subcommand_key(key : String)
- #subcommand_key : String
- #subcommands : Hash(String, Schema | CLI)
-
#validate(data : Hash(String, JSON::Any), subcommand : String | Nil = nil) : Array(String)
Validate data against a schema, returning any errors.
- #validate(result : Result) : Array(String)
- #zsh_completion(command : String = @program_name) : String
Constructor Detail
Create a CLI from a JSON or YAML schema file. Auto-detects multi-doc format for subcommands.
Create a CLI from a JSON schema string. Auto-detects multi-doc format (relaxed JSONL) for subcommands.
Create a CLI from a YAML schema string. Auto-detects multi-doc format for subcommands.
Instance Method Detail
Generate a shell completion shim. By default it calls back into this
program; pass command: to point completion at a separate (e.g. lighter)
binary that answers the hidden __complete verb.
Register a dynamic completer for a field, identified by its dotted path:
the field name for a flat CLI, or subcommand.field (a.b.field when
nested). The block receives a Completion::Context and returns the
candidate strings. Raises if the path does not match a schema field, so
typos and renames fail fast.
If this invocation is a completion request (the hidden __complete
verb), print candidates and — unless exit_process: false — exit 0.
Returns true when it handled completion, false otherwise, so it can be
called early in a program (before heavy initialization) or as the whole
body of a dedicated completion helper binary. The developer never types
the verb itself; the generated shim supplies it.
Return just the parsed data as JSON. Raises ParseError on validation errors.
Load config from standard locations. Supports YAML (.yaml, .yml) and JSON (.json) files.
Paths searched (in order):
- ./.config/{program_name}.yaml/.yml/.json (project local, flat)
- ./.config/{program_name}/config.yaml/.yml/.json (project local, directory)
- $XDG_CONFIG_HOME/{program_name}.yaml/.yml/.json (user global, flat)
- $XDG_CONFIG_HOME/{program_name}/config.yaml/.yml/.json (user global, directory)
With merge: true (default), merges all configs found (project wins over user). With merge: false, returns first config found. Returns nil if no config file found.
Parse arguments and return full Result with errors array.
Run the CLI with automatic --help, --completions, and error handling. Prints help/completions and exits 0, prints errors and exits 1, otherwise returns/yields result.
Load subcommand(s) from a file.
- Single-doc file: requires name, loads as single subcommand
- Multi-doc file without name: loads each doc as top-level subcommand
- Multi-doc file with name: loads docs as nested subcommands under name
Load subcommands from a multi-document file (no parent name). Each document must have a "name" field.
Validate data against a schema, returning any errors. If no schema is provided, uses the CLI's root schema. For subcommand validation, pass the subcommand name (space-separated for nested).