docopt / docopt.coffee Goto Github PK

docopt - A command line option parser that will make you smile.

License: Other

CoffeeScript 84.40% Python 15.60%

docopt.coffee's Introduction

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

docopt is a language for description of command-line interfaces. This is docopt implementation in CoffeeScript, that could be used for server-side CoffeeScript and JavaScript programs.

Isn't it awesome how modern command-line arguments parsers generate help message based on your code?!

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

Now you can write an awesome, readable, clean, DRY code like that:

doc = """
Usage:
  quick_example.coffee tcp <host> <port> [--timeout=<seconds>]
  quick_example.coffee serial <port> [--baud=9600] [--timeout=<seconds>]
  quick_example.coffee -h | --help | --version

"""
{docopt} = require '../docopt'

console.log docopt(doc, version: '0.1.1rc')

Hell yeah! The option parser is generated based on doc string above, that you pass to the docopt function.

API `{docopt} = require 'docopt'`

###options = docopt(doc, {argv: process.argv[2..], help: true, version: null})

docopt takes 1 required and 3 optional keyword arguments:

doc should be a string with help message, written according to rules of docopt language. Here is a quick example of such a string:

  Usage: your_program [options]

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

argv is an optional argument vector; by default it is the argument vector passed to your program (process.argv[2..]). You can supply it with an array of strings (similar to process.argv) e.g. ['--verbose', '-o', 'hai.txt'].
help, by default true, specifies whether the parser should automatically print the help 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 null, 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 an Object with properties (giving long options precedence), e.g:

{'--timeout': '10',
 '--baud': '4800',
 '--version': false,
 '--help': false,
 '-h': false,
 serial: true,
 tcp: false,
 '<host>': false,
 '<port>': '/dev/ttyr01'}

docopt.coffee's People

Contributors

Stargazers

Watchers

Forkers

delfinof stuartcarnie 1stvamp labajo frankrousseau gitgrimbo yanlinaung msanroman mdevils kemitchell aviddiviner dundalek casualuser samhavens lurch isabella232 scottmorse

docopt.coffee's Issues

require docopt breaks connect

If I just require docopt connect throws error

TypeError: Property 'handle' of object #<Object> is not a function
    at next (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/connect/lib/proto.js:190:15)
    at Object.logger (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/connect/lib/middleware/logger.js:156:5)
    at next (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/connect/lib/proto.js:190:15)
    at Object.favicon [as handle] (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/connect/lib/middleware/favicon.js:78:7)
    at next (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/connect/lib/proto.js:190:15)
    at Function.app.handle (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/connect/lib/proto.js:198:3)
    at Server.app (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/connect/lib/connect.js:66:31)
    at Manager.handleRequest (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/socket.io/lib/manager.js:564:28)
    at Server.<anonymous> (/home/vrtak-cz/Workspace/Vrtak-CZ/servit/node_modules/socket.io/lib/manager.js:118:10)
    at Server.EventEmitter.emit (events.js:126:20)

Extra newlines break docopt

Running the following program resulted in no output:

#! /usr/bin/env node

var docopt = require('docopt');

var doc = 'Usage:\n\n' +
           '  test.js [options] [<example-name>...]\n' +
           'Options:\n' +
           '  --url=url        URL to run the tests on.\n';

var options = docopt.docopt(doc);

I removed the second \n from the first line of the usage string, then the message was output as I expected when I ran the program.

This is with docopt 0.4.1, installed via npm.

Varadic arguments after optional argument failing

I've been trying to get a varadic argument working, particularly after my options.

Usage:
  sync53 import [options]
  sync53 import [options] [<zones>...]

Options:
  -b <both>, --both <both>

So I could support calls like

sync53 -b fooga asdf asdf

The browser tester for the reference version confirms that this is valid & returns what I'd expect.

{
  "--both": "fooga", 
  "<zones>": [
    "asdf", 
    "asdf"
  ], 
  "import": true
}

docopt.coffee is doing something else, and it looks like a bug. Here's what I get trying it with a variety of inputs. The script simply console.log()s the state if it succeeded.

$>node . import asdf asdf
Usage:  sync53 import [options]
        sync53 import [options] [<zones>...]

$>node . import -b fooga asdf asdf
Usage:  sync53 import [options]
        sync53 import [options] [<zones>...]

&>node . import -b fooga
IMPORT { '--both': 'fooga', import: true, '<zones>': [] }

I've tried to dig deeper w/o success, sorry. Any ideas?

This doesn't actually match the spec or its own readme

const options = docopt(
  `
Usage: foo [options]

--bar  Description
  `,
  {
    argv: ['--bar']
  }
);

Throws because it doesn't detect --bar as an option. Looking at the code, it appears that all options must be under an *options*: heading and indented, which isn't what the readme or spec says...

Docopt prints usage instead of parsing arguments

The following example prints the usage and exits, instead of correctly parsing the arguments.

const {docopt} = require("docopt")

const usage = `
A description for my_program

Usage:
  my_program (--param1 PARAM1 | -x PARAM1)
             (--param2 PARAM2 | -y PARAM2)
             [--db DB]
             [--user USER | -u USER]
             [--password PASSWORD | -p PASSWORD]
  my_program (-h | --help | -v | --version)

Options:
  -h --help      Print this help message
  -v --version   Print version
`

const argv = docopt(usage, {
    argv: ['--param1', 'P1', '--param2', 'P2'],
    version: '1.0.0'
})
console.log(argv)

Expected output:

The python version works

Docopt breaks lots of JS modules.

Due to Docopt manipulating native objects' prototypes, it breaks lots of modules that rely on the standard behaviour. Right now, it isn't safe to use Docopt with any other module, since those modules are likely to break.

This is related to #4, but broader.

Add environment variables support

Hi there! It would be useful to add environment variables support.

Consider this example: https://robpol86.github.io/docoptcfg/fix_repeating/env_vars.html

Default value on continuation line

Currently, if a default value is defined on the continuation line, it's not parsed:

Options:
  --foo=<foo>  Blah blah blah blah blah blah blah
               blah blah [default: something].

Here, something will never be set as default with docopt.coffee while it's okay with the Python implementation.

Support for indentation with TABs

Please add support for indentation with TABs

Is this published on NPM?

It points to a different repo:
https://www.npmjs.com/package/docopt

Two long options can result in "specified ambiguously" error

When I specify --woff given two option declarations --woff and --woff, I get an error saying that --woff is specified ambiguously 2 times

One-liner repro (after npm install docopt):

require('docopt').docopt("usage:\n--woff\n--woff2", {argv:["--woff"]})
 --woff is specified ambiguously 2 times

Cleaner module.exports

In docopt.coffee you use

module.exports =
  docopt: docopt
  ...   : ...

And that is all great but your list is now very long, and you have long names in it too, which makes it a problem to align, because you will have to change "all" the lines in module.exports = {} just because a longer name comes along.

Coffeescript have a nice way to create object hashes when the key names are equal to the variable names:

module.exports = {
    docopt
    Option
    Argument
    Command
    Required
    AnyOptions
    Either
    Optional
    Pattern
    OneOrMore
    TokenStream
    Dict
    formal_usage
    parse_doc_options
    parse_pattern
    parse_long
    parse_shorts
    parse_args
    printable_usage
}

This way you don't need anything to align, and it is easy to add new key/value pairs with out change any other lines in the object hash.

Unexpected repeated arguments when using repeated option.

Docopt seems to erroneously repeat arguments when parsing an option block when:

it is a repeating option.
it has multiple matching options in the same '[ ]' block.

Environment:

NodeJS: 5.7.0
Docopt: 0.6.2

Test Cases:

const doc = `
Usage:
    foobar [-f X ... | --foo X ...]
Options:
    -f X, --foo X     bar

`
console.log(require('docopt').docopt(doc))

const doc = `
Usage:
    foobar [-f X ...] [--foo X ...]
Options:
    -f X, --foo X    bar.

`
console.log(require('docopt').docopt(doc))

Tests:

👎

<test case 1> -f 1 -f 2 -f 3 -f 4 -f 5 -f 6
{ '--foo': [ '1', '2', '3', '4', '5', '6', '2', '3', '4', '5', '6' ] }

👍

<test case 2> -f 1 -f 2 -f 3 -f 4 -f 5 -f 6
{ '--foo': [ '1', '2', '3', '4', '5', '6' ] }

Multiple identical arguments to satisfy a list option

Giving multiple identical arguments to something like [<item>...] returns only one instance of the argument. python docopt does the right thing. Example:

usage = """
Usage:
    echo [<item>...]
"""
{docopt} = require '../docopt'
console.log docopt(usage, version: '2.0')

Now, coffee bug.coffee a a a returns
{ '<item>': [ 'a' ] }
whereas it really ought to return
{ '<item>': [ 'a', 'a', 'a' ] }

The problem is with this line in the Argument class:
left = (l for l in left when l.toString() isnt args[0].toString())
which will take out every instance matching args[0] when it really ought to remove only the first one, like in the python implementation.

I changed it as follows to make it work

-        left = (l for l in left when l.toString() isnt args[0].toString())
+        idx = left.indexOf args[0]
+        left = left.slice(0, idx).concat(left.slice(idx + 1))

but I don't know coffeescript so maybe there's a better way of doing it.