josh/yawpa
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

switch to YARD for documentation

Browse Source
This commit is contained in:
Josh Holtrop 2014-06-25 14:52:39 -04:00
parent 2099aaa6e0
commit 4e18e729c3
5 changed files with 88 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Gemfile.lock
View File

@ -11,6 +11,7 @@ GEM
rake (10.3.2)
rdoc (4.1.1)
json (~> 1.4)
redcarpet (3.1.2)
rspec (3.0.0)
rspec-core (~> 3.0.0)
rspec-expectations (~> 3.0.0)
@ -23,6 +24,7 @@ GEM
rspec-mocks (3.0.2)
rspec-support (~> 3.0.0)
rspec-support (3.0.2)
yard (0.8.7.4)
PLATFORMS
ruby
@ -30,5 +32,7 @@ PLATFORMS
DEPENDENCIES
rake
rdoc
redcarpet
rspec
yard
yawpa!

76
README.md
View File

@ -10,41 +10,47 @@ Yet Another Way to Parse Arguments is an argument-parsing library for Ruby.
## Example 1
require 'yawpa'
```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
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
require 'yawpa'
```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
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()
opts, args = Yawpa.parse(params, options, flags = {})
```ruby
opts, args = Yawpa.parse(params, options, flags = {})
```
Parse input parameters looking for options according to rules given in flags
@ -60,13 +66,15 @@ or insufficient arguments are present for an option.
### Example `options`
{
version: {},
verbose: {short: 'v'},
server: {nargs: (1..2)},
username: {nargs: 1},
password: {nargs: 1},
}
```ruby
{
version: {},
verbose: {short: "v"},
server: {nargs: (1..2)},
username: {nargs: 1},
password: {nargs: 1},
}
```
The keys of the `options` hash can be either strings or symbols.

9
Rakefile.rb
View File

@ -6,14 +6,13 @@ rescue Bundler::BundlerError => e
end
require "bundler/gem_tasks"
require 'rspec/core/rake_task'
require "rdoc/task"
require "yard"
RSpec::Core::RakeTask.new('spec')
task :default => :spec
Rake::RDocTask.new(:rdoc) do |rdoc|
rdoc.rdoc_dir = 'rdoc'
rdoc.title = 'Yet Another Way to Parse Arguments'
rdoc.rdoc_files.include('lib/**/*.rb')
YARD::Rake::YardocTask.new do |yard|
yard.options = ["--title", "Yet Another Way to Parse Arguments"]
yard.files = ["lib/**/*.rb"]
end

63
lib/yawpa.rb
View File

@ -7,32 +7,24 @@ require "yawpa/version"
# it just provides a simple functional interface for parsing options,
# supporting subcommands and arbitrary numbers of arguments for each option.
#
# == Features
#
# 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
# - Options can be defined with a range specifying the allowed number of
# parameters
module Yawpa
# Exception class raised when an unknown option is observed
# Exception class raised when an unknown option is observed.
class ArgumentParsingException < Exception; end
module_function
# :call-seq:
# Parse input parameters looking for options according to rules given in
# flags.
# Syntax:
# opts, args = 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).
# - +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+
# Example +options+:
#
# {
# version: {},
@ -42,7 +34,7 @@ module Yawpa
# password: {nargs: 1},
# }
#
# The keys of the +options+ hash can be either strings or symbols.
# The keys of the +options+ Hash can be either strings or symbols.
#
# Options that have no special flags should have an empty hash as the value.
#
@ -51,14 +43,28 @@ module Yawpa
# - +:nargs+: specify an exact number or range of possible numbers of
# arguments to the option
#
# == Return values
# @param params [Array]
# List of program parameters to parse.
# @param options [Hash]
# Hash containing the long option names as keys, and hashes containing
# special flags for the options as values (example above).
# @param flags [Hash]
# Optional flags dictating how {.parse} should do its job.
# @option flags [Boolean] :posix_order
# Stop processing parameters when a non-option argument is seen.
# Set this to +true+ if you want to implement subcommands.
#
# 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).
def parse(params, options, flags = {})
# @return [Array]
# Two-element array containing +opts+ and +args+ return values.
# +opts+::
# The returned +opts+ value will be a Hash with the observed
# options as keys and any option arguments as values.
# +args+::
# 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).
def self.parse(params, options, flags = {})
options = _massage_options(options)
opts = {}
args = []
@ -116,7 +122,7 @@ module Yawpa
end
# Internal helper method to gather arguments for an option
def _gather(nargs, start_idx, params, initial, param_key, result) # :nodoc:
def self._gather(nargs, start_idx, params, initial, param_key, result)
n_gathered = 0
if initial and initial != ''
result << initial
@ -137,9 +143,10 @@ module Yawpa
end
num_indices_used
end
private_class_method :_gather
# Internal helper method to format the options in a consistent format
def _massage_options(options) # :nodoc:
def self._massage_options(options)
{}.tap do |newopts|
options.each_pair do |k, v|
newkey = k.to_s
@ -151,12 +158,14 @@ module Yawpa
end
end
end
private_class_method :_massage_options
# Internal helper method to find an option configuration by short name
def _find_opt_config_by_short_name(options, short_name) # :nodoc:
def self._find_opt_config_by_short_name(options, short_name)
options.each_pair do |k, v|
return v if v[:short] == short_name
end
nil
end
private_class_method :_find_opt_config_by_short_name
end

2
yawpa.gemspec
View File

@ -18,4 +18,6 @@ Gem::Specification.new do |gem|
gem.add_development_dependency "rspec"
gem.add_development_dependency "rake"
gem.add_development_dependency "rdoc"
gem.add_development_dependency "yard"
gem.add_development_dependency "redcarpet"
end