optimist_README.md

optimist

optimist is a simple option parser for golang which is inspired by minimist, Getopt::Casual.

Usage

The below code returns optimist.Args that is the result of parsing arguments and structuring them.

import (
    "github.com/civitaspo/optimist"
    "os"
    "github.com/k0kubun/pp"
 )

o := optimist.ParseArgv(os.Args[1:])
pp.Print(o)

./optimist_sample test --op abc --op dfg -ab -c 4 -d3 -efge hoge fuga --no-test -hihi -- hogo --go
optimist.Args{
    "__RAW__": []string{
      "test",
      "--op",
      "abc",
      "--op",
      "dfg",
      "-ab",
      "-c",
      "4",
      "-d3,
      "-efge",
      "hoge",
      "fuga",
      "--no-test",
      "-hihi",
      "--",
      "hogo",
      "--go",
    }
    "_":  []string{
      "test",
      "hoge",
    },
    "--": []string{
      "hogo",
      "--go",
    },
    "^":  []map[string][]interface{
    },
    "--op": []string{
      "abc",
      "dfg"
    },
    "-a": []bool{true},
    "-b": []bool{true},
    "-c": []string{
      "4",
    },
    "-e": []bool{true},
    "-f": []bool{true},
    "-g": []bool{true},
    "-e": []string{
      "hoge",
    },
    "--test": []bool{false},
    "-h": []bool{true, true},
    "-i": []bool{true, true},
}

Rules

__RAW__

In __RAW__, all arguments before being parsed are stored.

-o --option

Words starting with one or two dashes (with exception of -, -- by themselves) are interpreted as short (one-letter) or long options, respectively. optimist.Args has keys which is the same as the option, and the values are the options' arguments.

• Options which have no argument are interpreted as boolean value.
  • Long options which have negative form of prefix like --no- are interpreted as false.
• Short options can be stacked meaning that -abc is equivalent to -a -b -c.
• Long options can have arguments specified after space or equal = sign: --input=ARG is equivalent to --input ARG.
• Short options can have arguments specified after optional space like -f FILE.
  • The case of having arguments without space like -fFILE is explained below.

Note: About Ambiguity

writing --input ARG (as opposed to --input=ARG) is ambiguous, meaning it is not possible to tell whether ARG is option's argument or a non-option argument. Basically, this will be interpreted as an option with argument. Otherwise it will be interpreted as an option and separate non-option argument only if there is a definition for that option is provided or the option has negative form of prefix.

There is the same ambiguity with the -f FILE and -fFILE notation. In the latter case it is not possible to tell whether it is a number of stacked short options, or an option with an argument. So, these notations will be interpreted as an option without an argument anytime.

--

A double dash --, when not part of an option, is often used as a convention to separate options and non-option arguments, in order to handle cases when, e.g., file names could be mistaken for options. In order to support this convention, unparsed arguments after -- are stored in the -- key of optimist.Args.

_

In _, all non-option arguments are stored.

^

optimist.Args has a function to remove arguments. In ^, all removed arguments are stored.

Installation

To install optimist according to your $GOPATH:

go get github.com/civitaspo/optimist

Build

To build, use go get and make

go get -d github.com/civitaspo/optimist
$ cd $GOPATH/src/github.com/civitaspo/optimist
$ make

Contribution

1. Fork (https://github.com/civitaspo/optimist/fork)
2. Create a feature branch
3. Commit your changes
4. Rebase your local changes against the master branch
5. Run test suite with the go test ./... command and confirm that it passes
6. Run gofmt -s
7. Create new Pull Request

Copyright

See LICENSE.txt