hoist

Types

Args

The result of parsing CLI arguments.

pub type Args {
  Args(arguments: List(String), flags: List(Flag))
}

Constructors

```
Args(arguments: List(String), flags: List(Flag))
```
Arguments

arguments

Positional arguments.

flags

Parsed flags.

Flag

</>

A parsed flag.

pub type Flag {
  ValueFlag(name: String, value: String)
  ToggleFlag(name: String)
  CountFlag(name: String, count: Int)
}

Constructors

```
ValueFlag(name: String, value: String)
```
A flag with a value, e.g. from --name=val, --name val, -n val or -nval.
```
ToggleFlag(name: String)
```
A flag toggle (bool), e.g. from --dry-run or -d.
```
CountFlag(name: String, count: Int)
```
A flag count, e.g. from -vvv.

FlagSpec

opaque </>

A specification for a flag in Hoist.

pub opaque type FlagSpec

FlagSpecValidationError

</>

Errors that occur when building flags

pub type FlagSpecValidationError {
  EmptyName(FlagSpec)
  InvalidNameOrAlias(name: String, flag_spec: FlagSpec)
  InvalidShortAlias(short: String, flag_spec: FlagSpec)
}

Constructors

```
EmptyName(FlagSpec)
```

InvalidNameOrAlias(name: String, flag_spec: FlagSpec)

InvalidShortAlias(short: String, flag_spec: FlagSpec)

ParseError

</>

pub type ParseError(error) {
  UnknownFlag(String)
  ValueNotProvided(flag: String)
  ValueNotSupported(flag: String, given: String)
  CustomError(value: error)
}

Constructors

```
UnknownFlag(String)
```
A flag was encountered that was not defined upfront.
```
ValueNotProvided(flag: String)
```
A value was not defined for a value-type flag.
```
ValueNotSupported(flag: String, given: String)
```
A value was passed to a count-kind or toggle-kind flag.
```
CustomError(value: error)
```
A user provided error.

ValidatedFlagSpecs

opaque </>

A collection of validated flag specs.

pub opaque type ValidatedFlagSpecs

Values

as_count

</>

pub fn as_count(flag: FlagSpec) -> FlagSpec

Designates this flag as a count-kind flag. Often used for verbosity levels, e.g. -vvv would have a count of 3.

as_toggle

</>

pub fn as_toggle(flag: FlagSpec) -> FlagSpec

Designates this flag as a toggle-kind flag. Generally used to enable or disable an option, e.g. --colour, --no-colour. Does not receive a value.

new_flag

</>

pub fn new_flag(name: String) -> FlagSpec

Creates a new flag with the given long name, e.g. --name. Case sensitive.

parse

</>

pub fn parse(
  input: List(String),
  flags: ValidatedFlagSpecs,
) -> Result(Args, ParseError(error))

Parses positional args and flags from a list of args.

Note: this function does not sanitise input in any way. If you require sanitisation, e.g. removal of whitespace-only arguments, you must handle that yourself.

parse_with_hook

</>

pub fn parse_with_hook(
  input: List(String),
  flags: ValidatedFlagSpecs,
  hook_state: hook_state,
  parse_hook: fn(hook_state, String, Args, ValidatedFlagSpecs) -> Result(
    #(hook_state, ValidatedFlagSpecs),
    error,
  ),
) -> #(hook_state, Result(Args, ParseError(error)))

Similar to parse but allows passing a custom hook that gets called after a positional argument is parsed.

The hook accepts the current hook state, the most recent positional argument, the currently parsed arguments and flags, and the available flag specs.

The hook can return a new set of flags to be used for parsing the next argument, along with a new state value.

Useful when the flags available for parsing depend on the value of a previous positional argument.

validate_flag_specs

</>

pub fn validate_flag_specs(
  flags: List(FlagSpec),
) -> Result(ValidatedFlagSpecs, List(FlagSpecValidationError))

Validates flag specs.

Ensures that every defined long flag and its aliases:

Have at least a one character name
Start with a letter or number
Only contain letters, numbers, hyphens and underscores

Ensures that every defined short flag:

Has exactly one character
Is a letter or number

with_long_alias

</>

pub fn with_long_alias(flag: FlagSpec, alias: String) -> FlagSpec

Adds a long alias for a command, e.g. --name, --first-name.

A flag can have multiple long aliases. These are stored in a set and will be deduplicated. Case sensitive.

with_short_alias

</>

pub fn with_short_alias(
  flag: FlagSpec,
  short: String,
) -> FlagSpec

Adds a short alias for a command, e.g. --name, -n.

A flag can have multiple short aliases. These are stored in a set and will be deduplicated. Case sensitive.

Constructors

Arguments

Constructors

Constructors

Constructors