Need help with docopt.rb?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

docopt
453 Stars 37 Forks Other 62 Commits 8 Opened issues

Description

Parse command line arguments from nothing more than a usage message

Services available

!
?

Need anything else?

Contributors list

docopt.rb
– command line option parser, that will make you smile

This is the ruby port of

docopt
, the awesome option parser written originally in python.

New in version 0.5.0:

Repeatable flags and commands are counted if repeated (a-la ssh

-vvv
). Repeatable options with arguments are accumulated into list.

Isn't it awesome how

optparse
and
argparse
generate help messages based on your code?!

Hell no! You know what's awesome? It's when the option parser is generated based on the beautiful help message that you write yourself! This way you don't need to write this stupid repeatable parser-code, and instead can write only the help message--the way you want it.

docopt
helps you create most beautiful command-line interfaces easily:
require "docopt"
doc = <...
  #{__FILE__} ship  move   [--speed=]
  #{__FILE__} ship shoot  
  #{__FILE__} mine (set|remove)   [--moored|--drifting]
  #{__FILE__} -h | --help
  #{__FILE__} --version

Options: -h --help Show this screen. --version Show version. --speed= Speed in knots [default: 10]. --moored Moored (anchored) mine. --drifting Drifting mine.

DOCOPT

begin require "pp" pp Docopt::docopt(doc) rescue Docopt::Exit => e puts e.message end

Beat that! The option parser is generated based on the docstring above that is passed to

docopt
function.
docopt
parses the usage pattern (
Usage: ...
) and option descriptions (lines starting with dash "
-
") and ensures that the program invocation matches the usage pattern; it parses options, arguments and commands based on that. The basic idea is that a good help message has all necessary information in it to make a parser.

Installation

Docopt is available via rubygems:

gem install docopt

Alternatively, you can just drop

lib/docopt.rb
file into your project--it is self-contained. Get source on github.

docopt
has been confirmed to work with 1.8.7p370 and 1.9.3p194. If you have noticed it working (or not working) with an earlier version, please raise an issue and we will investigate support.

API

Docopt
takes 1 required and 1 optional argument:
  • doc
    should be a string that describes options in a human-readable format, that will be parsed to create the option parser. The simple rules of how to write such a docstring (in order to generate option parser from it successfully) are given in the next section. Here is a quick example of such a string:
    Usage: your_program.rb [options]
    
    

    -h --help Show this. -v --verbose Print more text. --quiet Print less text. -o FILE Specify output file [default: ./test.txt].

The optional second argument contains a hash of additional data to influence docopt. The following keys are supported:

  • help
    , by default
    true
    , specifies whether the parser should automatically print the usage-message (supplied as
    doc
    ) in case
    -h
    or
    --help
    options are encountered. After showing the usage-message, the program will terminate. If you want to handle
    -h
    or
    --help
    options manually (as all other options), set
    help=false
    .
  • version
    , by default
    nil
    , is an optional argument that specifies the version of your program. If supplied, then, if the parser encounters
    --version
    option, it will print the supplied version and terminate.
    version
    could be any printable object, but most likely a string, e.g.
    '2.1.0rc1'
    .

Note, when

docopt
is set to automatically handle
-h
,
--help
and
--version
options, you still need to mention them in the options description (
doc
) for your users to know about them.

The return value is just a dictionary with options, arguments and commands, with keys spelled exactly like in a help message (long versions of options are given priority). For example, if you invoke the top example as::

naval_fate.rb ship Guardian move 100 150 --speed=15

the return dictionary will be::

{"ship"=>true,
 "new"=>false,
 ""=>["Guardian"],
 "move"=>true,
 ""=>"100",
 ""=>"150",
 "--speed"=>"15",
 "shoot"=>false,
 "mine"=>false,
 "set"=>false,
 "remove"=>false,
 "--moored"=>false,
 "--drifting"=>false,
 "--help"=>false,
 "--version"=>false}

Help message format

docopt.rb follows the docopt help message format. You can find more details at official docopt git repo

Examples

We have an extensive list of examples which cover every aspect of functionality of

docopt
. Try them out, read the source if in doubt.

Data validation

docopt
does one thing and does it well: it implements your command-line interface. However it does not validate the input data. We are looking for ruby validation libraries to make your option parsing experiene even more awesome! If you've got any suggestions or think your awesome schema validation gem fits well with
docopt.rb
, open an issue on github and enjoy the eternal glory!

Contribution

We would love to hear what you think about

docopt.rb
. Contribute, make pull requrests, report bugs, suggest ideas and discuss
docopt.rb
on issues page.

If you want to discuss the original

docopt
reference, point to it's home or drop a line directly to [email protected]!

Porting
docopt
to other languages

Docopt is an interlinguistic (?) effort, and this is the ruby port of

docopt
. We coordinate our efforts with docopt community and try our best to keep in sync with the python reference.

Docopt community loves to hear what you think about

docopt
,
docopt.rb
and other sister projects on docopt's issues page.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.