From 4e18e729c360e59a3f61ec74868ed8b1532e09c2 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Wed, 25 Jun 2014 14:52:39 -0400 Subject: [PATCH] switch to YARD for documentation --- Gemfile.lock | 4 +++ README.md | 76 ++++++++++++++++++++++++++++----------------------- Rakefile.rb | 9 +++--- lib/yawpa.rb | 63 ++++++++++++++++++++++++------------------ yawpa.gemspec | 2 ++ 5 files changed, 88 insertions(+), 66 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 2d23d41..b7ef491 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -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! diff --git a/README.md b/README.md index b3fddfb..1dc1655 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/Rakefile.rb b/Rakefile.rb index a5d8832..8b48382 100644 --- a/Rakefile.rb +++ b/Rakefile.rb @@ -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 diff --git a/lib/yawpa.rb b/lib/yawpa.rb index 64c41a0..4e35ca9 100644 --- a/lib/yawpa.rb +++ b/lib/yawpa.rb @@ -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 diff --git a/yawpa.gemspec b/yawpa.gemspec index b1a6aef..fbbe0f2 100644 --- a/yawpa.gemspec +++ b/yawpa.gemspec @@ -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