argletarglet

Module

arglet

src/arglet.pooka

A little argument parser, small enough to read over one cup of tea.

Arglet does two things. It fetches the command line from the Erlang runtime, and it sorts those words into flags, values and positionals, according to a short list of things you told it to expect.

Pooka
import arglet

main() {
  let expected = [
    arglet.flag("verbose", "v", "Say more about what is happening"),
    arglet.value("output", "o", "Where to write the result")
  ]
  match arglet.parse(arglet.arguments(), expected) {
    Ok(args) -> {
      echo args.positionals
      echo args.has("verbose")
      echo args.get("output")
      Nil
    }
    Error(problem) -> {
      echo arglet.describe(problem)
      Nil
    }
  }
}

For pooka run -- build -v --output=out.txt, args.positionals is ["build"], args.has("verbose") is True, and args.get("output") is Some("out.txt").

API reference

class

Arglet

src/arglet.pooka:46
class Arglet(runtime: String, program: String, arguments: List(String))

The command line, with each traveller in its own seat.

runtime is the Erlang executable. program is the escript path, or the working directory outside an escript. arguments holds the words the user typed, without runtime options or the escript path.

field

runtime

src/arglet.pooka:46
runtime: String
INFERREDString
field

program

src/arglet.pooka:46
program: String
INFERREDString
field

arguments

src/arglet.pooka:46
arguments: List(String)
INFERREDList(String)
constructor

new

src/arglet.pooka:46
INFERREDfn(String, String, List(String)) -> arglet.Arglet
function

load

src/arglet.pooka:61
load() -> Arglet
INFERREDfn() -> arglet.Arglet

Read the current invocation without parsing it.

Pooka
import arglet

main() {
  echo arglet.load().program
}
function

arguments

src/arglet.pooka:75
arguments() -> List(String)
INFERREDfn() -> List(String)

Only the words the user typed, in the order they typed them.

Pooka
import arglet

main() {
  echo arglet.arguments()
}
class

Spec

src/arglet.pooka:80
class Spec

Something the parser should expect. Make one with flag or value.

class

Flag

src/arglet.pooka:83
class Flag(name: String, short: String, help: String) is Spec

A switch that is either present or absent, such as --verbose.

field

name

src/arglet.pooka:83
name: String
INFERREDString
field

short

src/arglet.pooka:83
short: String
INFERREDString
field

help

src/arglet.pooka:83
help: String
INFERREDString
constructor

new

src/arglet.pooka:83
INFERREDfn(String, String, String) -> arglet.Flag
class

Value

src/arglet.pooka:86
class Value(name: String, short: String, help: String) is Spec

An option that carries a value, such as --output out.txt.

field

name

src/arglet.pooka:86
name: String
INFERREDString
field

short

src/arglet.pooka:86
short: String
INFERREDString
field

help

src/arglet.pooka:86
help: String
INFERREDString
constructor

new

src/arglet.pooka:86
INFERREDfn(String, String, String) -> arglet.Value
function

flag

src/arglet.pooka:96
flag(name: String, short: String, help: String) -> Spec
INFERREDfn(String, String, String) -> arglet.Spec

Expect a switch. name is used as --name, and short as -s. Pass "" for short when there is no short form.

Pooka
import arglet

let quiet = arglet.flag("quiet", "q", "Say less")
function

value

src/arglet.pooka:108
value(name: String, short: String, help: String) -> Spec
INFERREDfn(String, String, String) -> arglet.Spec

Expect an option with a value: --name value, --name=value, -s value or -svalue. Pass "" for short when there is no short form.

Pooka
import arglet

let output = arglet.value("output", "o", "Where to write the result")
class

Parsed

src/arglet.pooka:118
class Parsed(
  flags: List(String),
  values: List(#(String, String)),
  positionals: List(String),
)

The command line after sorting.

flags lists each switch once per appearance, so -vvv appears three times. values pairs each option name with its value, in order. positionals holds everything else, including every word after --. Names are always the long ones, whichever form the user typed.

field

flags

src/arglet.pooka:119
flags: List(String)
INFERREDList(String)
field

values

src/arglet.pooka:120
values: List(#(String, String))
INFERREDList(#(String, String))
field

positionals

src/arglet.pooka:121
positionals: List(String)
INFERREDList(String)
constructor

new

src/arglet.pooka:119
INFERREDfn(List(String), List(#(String, String)), List(String)) -> arglet.Parsed
method

has

src/arglet.pooka:124
has(name: String) -> Bool
INFERREDfn(String) -> Bool

Was this switch given at least once?

method

count

src/arglet.pooka:129
count(name: String) -> Int
INFERREDfn(String) -> Int

How many times was this switch given? Useful for -vvv.

method

get

src/arglet.pooka:135
get(name: String) -> Option(String)
INFERREDfn(String) -> Option(String)

The value of an option. If it was given more than once, the last one wins, as it does in most command line tools.

method

all

src/arglet.pooka:140
all(name: String) -> List(String)
INFERREDfn(String) -> List(String)

Every value given for an option, in order.

class

ArgError

src/arglet.pooka:152
class ArgError

Why a command line could not be sorted.

class

UnknownOption

src/arglet.pooka:155
class UnknownOption(option: String) is ArgError

An option nobody told the parser to expect, written as the user typed it.

field

option

src/arglet.pooka:155
option: String
INFERREDString
constructor

new

src/arglet.pooka:155
INFERREDfn(String) -> arglet.UnknownOption
class

MissingValue

src/arglet.pooka:158
class MissingValue(option: String) is ArgError

A value option at the very end, with nothing after it.

field

option

src/arglet.pooka:158
option: String
INFERREDString
constructor

new

src/arglet.pooka:158
INFERREDfn(String) -> arglet.MissingValue
class

UnexpectedValue

src/arglet.pooka:161
class UnexpectedValue(option: String) is ArgError

A switch that was handed a value, as in --verbose=yes.

field

option

src/arglet.pooka:161
option: String
INFERREDString
constructor

new

src/arglet.pooka:161
INFERREDfn(String) -> arglet.UnexpectedValue
function

describe

src/arglet.pooka:170
describe(problem: ArgError) -> String
INFERREDfn(arglet.ArgError) -> String

A sentence for the person at the keyboard.

Pooka
import arglet

assert arglet.describe(arglet.UnknownOption("--colour")) == "unknown option --colour"
function

parse

src/arglet.pooka:195
parse(arguments: List(String), specs: List(Spec)) -> Result(Parsed, ArgError)
INFERREDfn(List(String), List(arglet.Spec)) -> Result(arglet.Parsed, arglet.ArgError)

Sort a list of words into flags, values and positionals.

  • --name and -n are switches or options, as described by specs.
  • --name=value, --name value, -n value and -nvalue give a value.
  • Short switches can share a dash: -qv is -q -v.
  • -- ends the options. Every word after it is a positional.
  • - alone, and negative numbers such as -5, are positionals.
Pooka
import arglet

let expected = [arglet.flag("quiet", "q", ""), arglet.value("name", "n", "")]
let assert Ok(args) = arglet.parse(["greet", "-q", "--name", "Ada"], expected)
assert args.positionals == ["greet"]
assert args.has("quiet")
assert args.get("name") == Some("Ada")
function

usage

src/arglet.pooka:207
usage(specs: List(Spec)) -> String
INFERREDfn(List(arglet.Spec)) -> String

One line per expected option, for a --help screen.

Pooka
import arglet

let expected = [arglet.flag("quiet", "q", "Say less")]
assert arglet.usage(expected) == "  -q, --quiet  Say less"