Command line parsing for Emacs.

Add commander to your Cask file:

(depends-on "commander")

• commander (&rest forms)
• command (&rest args)
• option (&rest args)
• name (name)
• description (description)
• default (command-or-function &rest arguments)
• parse (arguments)

Define schema within this block.

(commander
 ;; schema here
 )

Define a command.

• First argument is the name of the command.
• Second argument either:
  • a description of the command
  • the command function (the function doc-string will be used as description)
• Third argument is command function if description is specified
• Rest of args are command default values

Define the command foo with no arguments.

(commander
 (command "foo" "Foo" fn))

$ emacs -Q -- foo

Define the command foo with a required argument.

(commander
 (command "foo <bar>" "Foo" fn))

$ emacs -Q -- foo bar

Define the command foo with an optional argument. If argument is not specified, "baz" will be used as the argument value.

(commander
 (command "foo [bar]" "Foo" fn "baz"))

$ emacs -Q -- foo
$ emacs -Q -- foo qux

Define the command foo with at least one required argument.

(commander
 (command "foo <*>" "Foo" fn))

$ emacs -Q -- foo bar
$ emacs -Q -- foo bar baz qux

Define the command foo with zero or more arguments.

(commander
 (command "foo [*]" "Foo" fn))

$ emacs -Q -- foo
$ emacs -Q -- foo bar baz qux

Define the command foo without description. The foo doc-string will be used as description.

(defun foo ()
  "Return FOO.")

(commander
 (default commander-print-usage-and-exit)
 (command "foo" foo))

$ emacs -Q

Define an option.

• First argument is the flags.
• Second argument either:
  • a description of the option
  • the option function (the function doc-string will be used as description)
• Third argument is option function if description is specified
• Rest of args are option default values

Define the option --foo with no arguments.

(commander
 (option "--foo" "Foo" fn))

$ emacs -Q -- --foo

Define the option --foo with a required argument.

(commander
 (option "--foo <bar>" "Foo" fn))

$ emacs -Q -- --foo bar

Define the option --foo with an optional argument. If argument is not specified, "baz" will be used as the argument value.

(commander
 (option "--foo [bar]" "Foo" fn "baz"))

$ emacs -Q -- --foo
$ emacs -Q -- --foo qux

Define the option --foo with at least one required argument.

(commander
 (option "--foo <*>" "Foo" fn))

$ emacs -Q -- --foo bar
$ emacs -Q -- --foo bar baz qux

Define the option --foo with zero or more arguments.

(commander
 (option "--foo [*]" "Foo" fn))

$ emacs -Q -- --foo
$ emacs -Q -- --foo bar baz qux

Define the option --foo with with an alias -f.

(commander
 (option "--foo, -f" "Foo" fn))

$ emacs -Q -- --foo
$ emacs -Q -- -f

Define the option --foo without description. The foo doc-string will be used as description.

(defun foo ()
  "Return FOO.")

(commander
 (default commander-print-usage-and-exit)
 (option "--foo" foo))

$ emacs -Q

Specify name in usage information.

Define the option --help that prints usage information with my-awesome-program as program name.

(commander
 (name "my-awesome-program")
 (option "--help" "Show usage information" commander-print-usage))

$ emacs -Q -- --help

Specify description in usage information.

Define the option --help that prints usage information with description.

(commander
 (name "my-awesome-program")
 (description "Truly awesome program, does what you wish for")
 (option "--help" "Show usage information" commander-print-usage))

$ emacs -Q -- --help

Specify default behaviour when no matching commands.

If command-or-function is a string, use that command if no command is specified. If symbol, call that function with all arguments if first argument does not match a command.

Define two commands show and hide and make show the default with everyone as argument.

(commander
 (default "show" "everyone")
 (command "show <stuff>" "Show stuff" show)
 (command "hide <stuff>" "Hide stuff" hide))

$ emacs -Q -- show me
$ emacs -Q -- hide you
$ emacs -Q

For each file argument, print the content.

(defun print-file-content (file)
  (princ (f-read file)))

(commander
 (default print-file-content "foo.txt"))

$ emacs -Q -- foo.txt bar.txt
$ emacs -Q

Parse file for default arguments and command. Each line is a command or option, including arguments.

For each file argument, print the content.

;; cmd.opts
;;
;;  --foo bar

(commander
 (config "cmd.opts")
 (option "--foo <arg>" "..." ignore)
 (option "--bar <arg>" "..." ignore))

$ emacs -Q -- --bar arg
$ emacs -Q

Parse arguments with defined schema. If #parse is not called explicitly, it is done automatically with commander-args first and if that's not present, it is called with the value of (cdr command-line-args-left).

(commander
 ;; schema

 (parse some-custom-variable)
 )

Create a new project, with optional dev mode:

;; emacs -Q -- create
;; emacs -Q -- create --dev
(commander
 (command "create" "Create new project" create)
 (option "--dev" "Run command in dev mode" dev-mode))

Simple find task:

;; emacs -Q -- find
;; emacs -Q -- find path/to/dir --name 'foo.el' --type f
(commander
 (command "find [path]" "Find stuff" find)
 (option "--name <path>" "Specify file name" name)
 (option "--type <type>" "Specify file type" type))

Automatic usage information (note that if description is not specified, the function doc-string is used as description):

(commander
 (command "find [path]" "Find stuff" find)
 (command "help" "Show usage information" commander-print-usage)
 (option "--name <path>" "Specify file name" name)
 (option "--type <type>" "Specify file type" type))

The command emacs -Q -- help will print:

USAGE: find COMMAND [OPTIONS]

COMMANDS:
 helpShow usage information
 findFind stuff

OPTIONS:
 --type  Specify file type
 --name  Specify file name

For more examples, check out: https://github.com/rejeep/commander.el/tree/master/examples

Contribution is much welcome!

Install cask if you haven't already, then:

$ cd /path/to/commander.el
$ cask

Run all tests with:

$ make