[](https://github.com/jodersky/commando/actions)
# Commando
An opinionated command line parsing utility for Scala.
```scala
libraryDependencies += "io.crashbox" %% "commando" % "<latest_version>"
```
Commando is available for Scala, Scala JS and Scala Native.
## Concepts
Commando's API is designed around two main concepts: commands and
parameters. It is recommended to read this section before diving into
the Scala API.
### Commands
Commands represent an action and have side effects when
run. Well-known examples include `ls`, `cp`, `git`, etc.
On a single command line, only one command is ever invoked. However,
commands can be nested and share *parameters*. `git` for example, fits
into this model:
```
git -p clone https://github.com/jodersky/commando
```
In the above, the top-level command has a parameter `-p`, followed by
a "subcommand" `clone`, which itself has a url as parameter. Typically,
a parent command will have several child commands. As such, a command
can also be thought of representing a on-of-many choice parameter.
### Parameters
Parameters define what arguments a command may take. There are two
kinds of parameters: positional and optional.
#### Positional parameters
Positional parameters simply get substituted by values from left to
right.
E.g. assume a command `command` that expects two positional parameters
`x` followed by `y`. Invoking the command as follows: `command 1 2`
will substitute 1 for `x` and 2 for `y`.
#### Optional parameters
Optional parameters define arguments that may be passed to a command
in any order. They typically represent "flags" or extra key-value
information.
In order to avoid ambiguity with positional arguments, optionals must
follow certain requiremenets:
- Optionals start with `--` and may be positioned anywhere within the
scope of a command (scope of a command are all words up to the next
subcommand).
E.g. in `command --foo <arg1> --bar subcommand --baz <arg2>` the
optionals `--foo` and `--bar` refer to `command`, and `--baz` refers
to `subcommand`.
- May have a single-character "short" alias, in which case they an be
specified with a single dash. E.g. `--force` and `-f`.
- Are **always** optional (use a command in case you need a
one-of-many choice).
- May be repeated. `command -v -v -v -v`
- May have embedded arguments after an equals sign. `command
--publish=80:80`
- If specified, may allow or require an argument. `command --publish
80:80 --publish 443:443`
- In short form, and if they do not have parameters, arguments may be
collapsed into a single string starting with a single
dash. E.g. `command -i -t -f` is equivalent to `command -itf`.
- A standalone double dash is an escape sequence. Any arguments
following are treated as positionals. E.g. `ls --
--a-directory-starting-with---`.
## Scala API
The API is focused around a recursive
[`Command`](src/main/scala/definitions.scala) object. This object
represents the "grammar" of a command line application, grouping
parameter definitions and subcommands.
It is passed to a command line *parser*, along with a sequence of
*arguments* and is typically called from an application's entry point.
Commands may be constructed directly, however it is recommended to use
the domain specific language that is provided in the [commando package
object](src/main/scala/package.scala).
For example, the following defines a subset of a docker-like command
line utility:
```scala
import commando._
object Main {
val command = cmd("docker")(
opt("debug", 'D')
).sub(
cmd("run")(
opt("interactive", 'i'),
opt("tty", 't'),
pos("container")
).run{ arguments =>
// run container with arguments
println("running container " + arguments("container").head)
},
cmd("ps")(
opt("all", 'a')
).run{ arguments =>
if (arguments.contains("all")) {
// list all images
} else {
// list running containers
}
}
)
def main(args: Array[String]): Unit = commando.parse(args, command)
}
```
Assuming the application is packaged and executable as `docker`, it
may be invoked as follows:
```
$ docker run -it my_container
running container my_container
```
```
$ docker -D ps --all
```
