126 lines
3.3 KiB
Markdown
126 lines
3.3 KiB
Markdown
# Yawpa
|
|
|
|
Yet Another Way to Parse Arguments is an argument-parsing library for Ruby.
|
|
|
|
[](http://badge.fury.io/rb/yawpa)
|
|
|
|
## Features
|
|
|
|
- POSIX or non-POSIX mode (supports subcommands using POSIX mode)
|
|
- Options can require an arbitrary number of parameters
|
|
- Options can be defined with a range specifying the allowed number of parameters
|
|
|
|
## Example 1
|
|
|
|
```ruby
|
|
require "yawpa"
|
|
|
|
options = {
|
|
version: {},
|
|
verbose: {short: "v"},
|
|
get: {nargs: 1},
|
|
set: {nargs: 2},
|
|
}
|
|
opts, args = Yawpa.parse(ARGV, options)
|
|
opts.each_pair do |opt, val|
|
|
end
|
|
```
|
|
|
|
## Example 2
|
|
|
|
```ruby
|
|
require "yawpa"
|
|
|
|
options = {
|
|
version: {},
|
|
help: {short: "h"},
|
|
}
|
|
opts, args = Yawpa.parse(ARGV, options, posix_order: true)
|
|
if opts[:version]
|
|
puts "my app, version 1.2.3"
|
|
end
|
|
if args[0] == "subcommand"
|
|
subcommand_options = {
|
|
"server": {nargs: (1..2), short: "s"},
|
|
"dst": {nargs: 1, short: "d"},
|
|
}
|
|
opts, args = Yawpa.parse(args, subcommand_options)
|
|
end
|
|
```
|
|
|
|
## Using Yawpa.parse()
|
|
|
|
```ruby
|
|
opts, args = Yawpa.parse(params, options, flags = {})
|
|
```
|
|
|
|
Parse input parameters looking for options according to rules given in flags
|
|
|
|
- `params` is the list of program parameters to parse.
|
|
- `options` is a hash containing the long option names as keys, and hashes
|
|
containing special flags for the options as values (example below).
|
|
Possible values:
|
|
- `nil`: No special flags for this option (equivalent to `{}`)
|
|
- `:boolean`: The option is a toggleable boolean option (equivalent to
|
|
`{boolean: true}`)
|
|
- `Hash`: Possible option flags:
|
|
- `:short`: specify a short option letter to associate with the long option
|
|
- `:nargs`: specify an exact number or range of possible numbers of
|
|
arguments to the option
|
|
- `:boolean`: if true, specify that the option is a toggleable boolean
|
|
option and allow a prefix of "no" to turn it off.
|
|
- `flags` is optional. It supports the following keys:
|
|
- `:posix_order`: Stop processing parameters when a non-option is seen.
|
|
Set this to `true` if you want to implement subcommands.
|
|
|
|
An ArgumentParsingException will be raised if an unknown option is observed
|
|
or insufficient arguments are present for an option.
|
|
|
|
### Example `options`
|
|
|
|
```ruby
|
|
{
|
|
version: nil,
|
|
verbose: {short: 'v'},
|
|
server: {nargs: (1..2)},
|
|
username: {nargs: 1},
|
|
password: {nargs: 1},
|
|
color: :boolean,
|
|
}
|
|
```
|
|
|
|
The keys of the `options` hash can be either strings or symbols.
|
|
|
|
Possible option flags:
|
|
|
|
- `:short`: specify a short option letter to associate with the long option
|
|
- `:nargs`: specify an exact number or range of possible numbers of
|
|
arguments to the option
|
|
- `:boolean`: if true, specify that the option is a toggleable boolean
|
|
option and allow a prefix of "no" to turn it off.
|
|
|
|
### Return values
|
|
|
|
The returned `opts` value will be a hash with the observed options as
|
|
keys and any option arguments as values.
|
|
The returned `args` will be an array of the unprocessed parameters (if
|
|
`:posix_order` was passed in `flags`, this array might contain further
|
|
options that were not processed after observing a non-option parameters).
|
|
|
|
## Release Notes
|
|
|
|
### v1.2.0
|
|
|
|
- Always return non-frozen strings
|
|
|
|
### v1.1.0
|
|
|
|
- Add `:boolean` option flag.
|
|
- Support `nil` or `:boolean` as shortcut option configuration values.
|
|
- Update documentation to YARD.
|
|
- Update specs to RSpec 3.
|
|
|
|
### v1.0.0
|
|
|
|
- Initial Release
|