cl-cli

# CL-CLI

Simple and easy to use modern command line argument parser for common lisp.


## Definition

A typical command line consists of a *program name*, eventually *options*,
*sub-commands*, *sub-command options* and a remaining.

A modern command line would look like:

	./tool --verbose --chroot /path/to/dir server start --restart \
		--delay 10 instance1 instance2

A program get its argument by the mean of list (or a vector) of strings such
as:

	'("./tool" "--verbose" "--chroot" "/path/to/dir" "server" "start"
		"--restart" "--delay" "10" "instance1" "instance2")

It is up to the programmer's responsibility to parse and interpret the
command line. We can split that command line into several parts:


* The *program name*: `./tool`. This is how the program is called.
* Some *global options*: `--verbose --chroot /path/to/dir`. Each option can
  be a *switch*, such as `--verbose`, which is argument less, or can have
  one (or many) argument: `/path/to/dir` is an argument of the `--chroot`
  option.
* A *sub-command*: `server start`. A sub command can be one or many verbs
  (or terms).
* Some *sub-command options*: `--restart --delay 10`. This is the same as
  the *global options* but specific to the *sub-command*.
* A *rest*: `instance1 instance2` its the command line remains after parsing
  process.

## CL-CLI usage


### Basic usage

Think of a global option as a global variable as defined with
`DEFPARAMETER` or `DEFVAR`. For example you would define `*DEBUG*`:

	(defparameter *debug* nil "Run in debug mode")

Or in a more laconic way:

	(defvar *debug*)

Now you only need to defined an option list suitable for `CL-CLI:PARSE-CLI`:

	CL-USER> (defparameter *options*
	'((*debug* nil "Run in debug mode" :alias ("-d"))
	  (*dir* "/tmp" "Change to directory" :params ("DIR"))))


Now you can parse the command line:

	CL-USER> (cl-cli:parse-cli '("./tool" "--dir" "/path/to/chroot" "--debug"
				      "server" "start" "--restart" "--delay" "3"
				      "instance1" "isntance2") *options*)
	(*DEBUG* *DIR*)
	(T "/path/to/chroot")
	NIL
	NIL
	NIL
	CL-USER> 

The first two returned values are the variable list and their values
suitable for `PROGV`. You can now bind these variables and execute code
using the `CL-CLI:WITH-ENVIRONMENT` macro:

	CL-USER> (multiple-value-bind (vars vals)
		     (cl-cli:parse-cli '("./tool" "--dir" "/path/to/chroot" "--debug"
					  "server" "start" "--restart" "--delay" "3"
					  "instance1" "isntance2") *options*)
		   (cl-cli:with-environment vars vals
					     (format t "dir: ~a, debug: ~a~%" *dir* *debug*)))
	dir: /path/to/chroot, debug: T
	NIL

The 3rd and 4th values are the sub-command to be run (if any, see below) and
its arguments. The 5th value is the cli rest after parsing.

### Advanced usage

A more advanced usage would use sub-commands. A sub-command defined by using
`CL-CLI:DEFCOMMAND` which requires a dispatch verb list, an options list, a
docstring and a body.

	CL-USER> (cl-cli:defcommand
		     ("server" "start")
		     ((restart nil "restart instead of start")
		      (delay 2 "Second to wait" :params ("DELAY")))
		     "Start or restart server"
		   (when *debug*
		     (format t "Delay: ~a Restart: ~a~%" delay restart))
		   (format t "Server ~a in ~a~%"
			   (if restart "restarted" "started") *dir*)
		   'start)
	#S(CL-CLI:SUB-COMMAND
	   :VERBS ("server" "start")
	   :OPTIONS ((RESTART NIL "restart instead of start")
	             (DELAY 2 "Second to wait" :METAVARS ("DELAY")))
	   :DOCSTRING "Start or restart server"
	   :FUNC #<FUNCTION (LAMBDA (&KEY (RESTART ()) (DELAY 2))) {1003B1B4DB}>)



`CL-CLI:DEFCOMMAND` create the function and returns a `CL-CLI:COMMAND`
structure:

	CL-USER> (cl-cli:defcommand server-start
		     (:help "Start server"
		      :verbs ("server" "start")
		      :options ((restart :help "restart instead of start")
				(:name delay :default 2 :params ("DELAY") :help "Seconds to wait")))
	  "Start or restart server"
	  (when *debug*
	    (format t "Delay: ~a Restart: ~a~%" delay restart))
	  (format t "Server ~a in ~a~%" (if restart "restarted" "started") *dir*))
	#S(CL-CLI:SUB-COMMAND
	   :NAME SERVER-START
	   :FUNCTION #<FUNCTION (LAMBDA (&KEY (DELAY 2) (RESTART ()))) {1006330A7B}>
	   :ARGS #<HASH-TABLE :TEST EQUAL :COUNT 2 {1006153A43}>
	   :VERBS ("server" "start")
	   :DOCSTRING "Start or restart server"
	   :HELP "Start server")
	CL-USER> 


A full working example would be something like:

	CL-USER> (let ((options
		(list
		 (cl-cli:defoption '*debug* :default nil)
		 (cl-cli:defoption '*dir* :default "/tmp" :params '("DIR"))))
	      (argv '("./tool" "--dir" "/path/to/chroot" "--debug"
		      "server" "start" "--restart" "--delay" "3"
		      "instance1" "isntance2"))
	      (sub-commands
		(list (cl-cli:defcommand server-start
			  (:help "Start server"
			   :verbs ("server" "start")
			   :options ((restart
				      :help "restart instead of start")
				     (delay :default 2 :params '("DELAY")
				      :help "Seconds to wait")))
			"Start or restart server"
			(when *debug*
			  (format t "Delay: ~a Restart: ~a~%" delay restart))
			(format t "Server ~a in ~a~%"
				(if restart "restarted" "started") *dir*))
		      (cl-cli:defcommand server-stop
			  (:help "Stop server"
			   :verbs ("server" "stop")
			   :options ((:name delay :default 2 :params '("DELAY")
				      :help "Seconds to wait")))
			"Stop server"
			(when *debug*
			  (format t "Delay: ~a~%" delay))
			(format t "Server stopped in ~a~%" *dir*)))))
	  (cl-cli:run (:argv argv :options options :sub-commands sub-commands)))
	
	
	Delay: 3 Restart: T
	Server restarted in /path/to/chroot
	NIL
	CL-USER> 

## API

### The options list

This is a list of options you pass to te parser. Each option is defined as:

	(name default help &key long alias params type)

* `name`: the option name, or variable to which the option is bound to.
* `default`: The option default value.
* `help`: a docstring that is used to display help.
* `long`: the option long form generated against `name`. For example
  `*foo-bar*`: will result as `--foo-bar`.
* `alias`: a list of option aliases. This is a good place to define
  shortcuts such as `-f` for `--foo` or `-b` for `--bar`.
* `params`: a list of option parameters that define how many arguments the
  option requires. If `params` is `nil` no option is required. n the other
  hand if you need to defined a chroot diretory you can setup `params` to
  `("dir")`. Thus `--chroot` requires one mandatory argument. The `"dir"`
  string is used in help display.
* `type`: A type to which the option should be converted to.

### The commands list

As for options, the command list defined all known commands the parser
should be aware of. A command is created using the `CL-CLI:DEFCOMMAND`
macro.

	(defcommand verbs options positional docstring func)

* `verbs`: A list of words that triggers the command.
* `options`: a list of command options.
* `positional`: a list of mandatory positional arguments (order
  maters). This is like an option but with no default value.
* `docstring`: a string that is used to display help.
* `func`: a function body that should handle the command.

### Functions

#### parse-cli

	parse-cli (argv &optional options commands)

Parse `ARGV` using `OPTIONS` both and `COMMANDS` directives.

Returns
* options variables
* options values
* matched command dispatch function
* dispatch function keyword arguments
* the rest of the command line argument"

#### with-environment

	with-environment (vars vals &body body)

Run `BODY` after binding `VARS` to `VALS`.

The 2 first values of `parse-cli` can be used to feen `with-environment`.

#### run-command

	run-command (argv &optional options commands)

Run `parse-cli` and execute the matched dispatch function.

#### help

	help (options sub-commands &key prog-name version prolog epilog)

Display help screen.

* `prog-name`: the program name.
* `version`: the program version.
* `prolog`: a text that should be displayed at the beging.
* `epilog`: a text that should be diplayed at the end.




## Copyright

Author: Sébastien Gross <seb•ɑƬ•chezwam•ɖɵʈ•org>
License: WTFPL, grab your copy here: http://www.wtfpl.net




split-sequence

Simple and easy to use modern command line argument parser for common lisp.

cl-cli

Upstream URL

Author

Maintainer

License

cl-cli

Version:

License:

Authors:

Maintainers:

Dependencies:

Dependencies (1)

Dependents (0)