glimr - v0.9.1

glimr/console/command

Glimr Console Command

Provides a fluent API for defining console commands. Commands capture their context at construction time via closures, allowing framework and user commands to coexist.

For database commands, use driver-specific command modules:

Types

Args

</>

Parsed arguments passed to command handlers. Contains positional arguments as a Dict, flags as a List, and options with values as a Dict. Use get_arg(), has_flag(), and get_option() to access values.

pub type Args {
  Args(
    arguments: dict.Dict(String, String),
    flags: List(String),
    options: dict.Dict(String, String),
  )
}

Constructors 

  • Args(
  arguments: dict.Dict(String, String),
  flags: List(String),
  options: dict.Dict(String, String),
)

Command

</>

Represents a console command. Regular commands have a simple handler function. Database commands use CommandWithDb which includes a closure that manages pool lifecycle. Cache commands use CommandWithCache for access to cache store configuration.

pub type Command {
  Command(
    name: String,
    description: String,
    args: List(CommandArg),
    handler: fn(Args) -> Nil,
  )
  CommandWithDb(
    name: String,
    description: String,
    args: List(CommandArg),
    driver_type: driver.DriverType,
    run_with_pool: fn(Args, driver.Connection) -> Nil,
  )
  CommandWithCache(
    name: String,
    description: String,
    args: List(CommandArg),
    driver_type: driver.DriverType,
    run_with_cache: fn(
      Args,
      driver.Connection,
      List(driver.CacheStore),
    ) -> Nil,
  )
}

Constructors

CommandArg

</>

Defines an argument, flag, or option that a command accepts. Use Argument for required positional arguments, Flag for boolean flags like –verbose or -v, and Option for options with values and defaults like –format=json.

pub type CommandArg {
  Argument(name: String, description: String)
  Flag(name: String, short: String, description: String)
  Option(name: String, description: String, default: String)
}

Constructors 

  • Argument(name: String, description: String)
  • Flag(name: String, short: String, description: String)
  • Option(name: String, description: String, default: String)

Values

args

</> 
pub fn args(cmd: Command, arguments: List(CommandArg)) -> Command

Sets the arguments, flags, and options for a command. Use Argument for required positional args, Flag for boolean flags, and Option for options that take values.

Example

command.new()
|> command.name("make:controller")
|> command.args([
  Argument("name", "The name of the controller"),
  Flag("resource", "r", "Generate a resource controller"),
  Option("template", "Template to use for generation", "default"),
])
|> command.handler(fn(args) { ... })

db_option

</> 
pub fn db_option() -> CommandArg

Returns the standard –database option for commands that need database access. Add this to your command args when using driver-specific handlers. Uses “_default” as the default value to use the first configured connection.

description

</> 
pub fn description(cmd: Command, description: String) -> Command

Sets the description shown in the help output. Description should be a one-liner, nice and simple. This text appears next to the command name when users run the help command.

get_arg

</> 
pub fn get_arg(parsed: Args, name: String) -> String

Gets a positional argument value from Args by name. Arguments are required and validated before the handler runs, so this will crash if the argument is missing.

get_option

</> 
pub fn get_option(parsed: Args, name: String) -> String

Gets an option value from Args by name. Returns empty string if not found, allowing safe chaining without checking for errors in command handlers.

handler

</> 
pub fn handler(cmd: Command, handler: fn(Args) -> Nil) -> Command

Sets the handler function for the command. The handler receives Args only. For database commands, use driver-specific handlers (glimr_sqlite/command.handler or glimr_postgres/command.handler) instead.

has_flag

</> 
pub fn has_flag(parsed: Args, name: String) -> Bool

Checks if a flag was provided by the user. Returns True if –name or -short was passed on the CLI. The name parameter should match the Flag’s name field.

name

</> 
pub fn name(cmd: Command, name: String) -> Command

Sets the name of the command. This is the string users will type to invoke the command. It’s best to prefix command names like “make:controller” or “glimr:greet” but it’s not required.

new

</> 
pub fn new() -> Command

Creates a new command. Use the fluent API to set the name, description, args, and handler.

Example

command.new()
|> command.name("greet")
|> command.description("Greet the user")
|> command.handler(fn(args) { ... })

run

</> 
pub fn run(cmd: Command) -> Nil

Central dispatch for command execution. Handles the common concerns (help flags, argument validation) before delegating to the appropriate handler based on command type.

✨ Search Document