Don’t call this function directly. Rather, call cli.opt, clip.flag, clip.arg, clip.arg_many, or clip.arg_many1.

Parse the next positional argument built using the clip/arg module and provide it to a Command function build using clip.command()

clip.command(fn(a) { a })
|> clip.arg(arg.new("foo"))
|> clip.run(["foo"])

// Ok("foo")

arg will not attempt to parse options starting with - unless the special -- value has been previously passed or the option is a negative integer or float.

Parse the next zero or more positional arguments built using the clip/arg module and provide them as a List to a Command function build using clip.command(). arg_many is greedy, parsing as many options as possible until parsing fails. If zero values are parsed successfuly, an empty List is provided.

clip.command(fn(a) { a })
|> clip.arg_many(arg.new("foo"))
|> clip.run(["foo", "bar", "baz"])

// Ok(["foo", "bar", "baz"])

arg_many will not attempt to parse options starting with - unless the special -- value has been previously passed or the option is a negative integer or float.

Parse the next one or more positional arguments built using the clip/arg module and provide them as a List to a Command function build using clip.command(). arg_many is greedy, parsing as many options as possible until parsing fails. Parsing fails if zero values are parsed successfully.

clip.command(fn(a) { a })
|> clip.arg_many1(arg.new("foo"))
|> clip.run(["foo", "bar", "baz"])

// Ok(["foo", "bar", "baz"])

arg_many1 will not attempt to parse options starting with - unless the special -- value has been previously passed or the option is a negative integer or float.

The command function is use to start building a parser. You provide a curried function and then provide arguments to be supplied to that function.

clip.command({
  use a <- clip.parameter
  use b <- clip.parameter

  #(a, b)
})
|> clip.opt(opt.new("first"))
|> clip.opt(opt.new("second"))
|> clip.run(["--first", "foo", "--second", "bar"])

// Ok(#("foo", "bar"))

A pre-built command that takes a single argument and returns its value.

clip.command1()
|> clip.opt(opt.new("first"))
|> clip.run(["--first", "foo"])

// Ok("foo")

A pre-built command that takes two arguments and returns a tuple of their values.

clip.command2()
|> clip.opt(opt.new("first"))
|> clip.opt(opt.new("second"))
|> clip.run(["--first", "foo", "--second", "bar"])

// Ok(#("foo", "bar"))

A pre-built command that takes three arguments and returns a tuple of their values.

clip.command3()
|> clip.opt(opt.new("first"))
|> clip.opt(opt.new("second"))
|> clip.opt(opt.new("third"))
|> clip.run(["--first", "foo", "--second", "bar", "--third", "baz"])

// Ok(#("foo", "bar", "baz"))

A pre-built command that takes four arguments and returns a tuple of their values.

clip.command4()
|> clip.opt(opt.new("first"))
|> clip.opt(opt.new("second"))
|> clip.opt(opt.new("third"))
|> clip.opt(opt.new("fourth"))
|> clip.run(["--first", "foo", "--second", "bar", "--third", "baz", "--fourth", "qux"])

// Ok(#("foo", "bar", "baz", "qux"))

Creates a Command that always produces Error(message) when run.

Parse a flag built using the clip/flag module and provide it to a Command function build using clip.command()

clip.command(fn(a) { a })
|> clip.flag(flag.new("foo"))
|> clip.run(["--foo"])

// Ok(True)

Add the help (-h, --help) flags to your program to display usage help to the user. See the clip/help module for producing simple and custom help text.

Parse an option built using the clip/opt module and provide it to a Command function build using clip.command()

clip.command(fn(a) { a })
|> clip.opt(opt.new("first"))
|> clip.run(["--first", "foo"])

// Ok("foo")

The parameter function provides an alternative syntax for building curried functions. The following two code blocks are equivalent:

fn(a) {
  fn(b) {
    thing(a, b)
  }
}

{
  use a <- clip.parameter
  use b <- clip.parameter

  thing(a, b)
}

You can use either style when calling clip.command.

Use a Command(a) to parse a list of command line options. If parsing is successful, an Ok(#(a, List(String))) is returned containing the parsed value and any left over options. If parsing fails, an Error(String) is returned. The Error value is intended to be printed to the user.

You should use the clip.run function instead of clip.parse, unless you need to deal with left over options after successful parsing.

The return function takes a value val and produces a Command that, when run, produces val. You should only call this function directly when your command doesn’t require any arguments. Otherwise, use clip.command.

clip.return(1) |> clip.run(["whatever"])

// Ok(1)

See the subcommand example for idiomatic usage of return.

Run a command with a list of command line options. Running a Command(a) will return either Ok(a) or an Error(String). The Error value is intended to be printed to the user.

Build a command with subcommands. This is an advanced use case, see the examples directory for more help.

Build a command with subcommands and a default top-level command if no subcommand matches. This is an advanced use case, see the examples directory for more help.