Skip to content
Emacs command line parser
Emacs Lisp Cucumber Makefile
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
examples
features
test
vendor
.ert-runner
.gitignore
.travis.yml
Cask
LICENSE Add LICENSE file Sep 11, 2015
Makefile
README.md Should be option, not command Jun 21, 2015
commander.el

README.md

commander.el Build Status

Command line parsing for Emacs.

Installation

Add commander to your Cask file:

(depends-on "commander")

DSL

Overview

Details

commander (&rest forms)

Define schema within this block.

(commander
 ;; schema here
 )

command (&rest args)

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
Example

Define the command foo with no arguments.

(commander
 (command "foo" "Foo" fn))
Usage
$ emacs -Q -- foo
Example

Define the command foo with a required argument.

(commander
 (command "foo <bar>" "Foo" fn))
Usage
$ emacs -Q -- foo bar
Example

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"))
Usage
$ emacs -Q -- foo
$ emacs -Q -- foo qux
Example

Define the command foo with at least one required argument.

(commander
 (command "foo <*>" "Foo" fn))
Usage
$ emacs -Q -- foo bar
$ emacs -Q -- foo bar baz qux
Example

Define the command foo with zero or more arguments.

(commander
 (command "foo [*]" "Foo" fn))
Usage
$ emacs -Q -- foo
$ emacs -Q -- foo bar baz qux
Example

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))
Usage
$ emacs -Q

option (&rest args)

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
Example

Define the option --foo with no arguments.

(commander
 (option "--foo" "Foo" fn))
Usage
$ emacs -Q -- --foo
Example

Define the option --foo with a required argument.

(commander
 (option "--foo <bar>" "Foo" fn))
Usage
$ emacs -Q -- --foo bar
Example

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"))
Usage
$ emacs -Q -- --foo
$ emacs -Q -- --foo qux
Example

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

(commander
 (option "--foo <*>" "Foo" fn))
Usage
$ emacs -Q -- --foo bar
$ emacs -Q -- --foo bar baz qux
Example

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

(commander
 (option "--foo [*]" "Foo" fn))
Usage
$ emacs -Q -- --foo
$ emacs -Q -- --foo bar baz qux
Example

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

(commander
 (option "--foo, -f" "Foo" fn))
Usage
$ emacs -Q -- --foo
$ emacs -Q -- -f
Example

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))
Usage
$ emacs -Q

name (name)

Specify name in usage information.

Example

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))
Usage
$ emacs -Q -- --help

description (description)

Specify description in usage information.

Example

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))
Usage
$ emacs -Q -- --help

default (command-or-function &rest arguments)

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.

Example

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))
Usage
$ emacs -Q -- show me
$ emacs -Q -- hide you
$ emacs -Q
Example

For each file argument, print the content.

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

(commander
 (default print-file-content "foo.txt"))
Usage
$ emacs -Q -- foo.txt bar.txt
$ emacs -Q

config (file)

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

Example

For each file argument, print the content.

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

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

parse (arguments)

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)
 )

Examples

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

Contribution is much welcome!

Install cask if you haven't already, then:

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

Run all tests with:

$ make
Something went wrong with that request. Please try again.