micro-optparse 1.1.5 → 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d818c3f17d7145292be780c6a915949bffb67ff9
+  data.tar.gz: c95aeea5d5eb0985b17abe704f26419b0ba6283e
+SHA512:
+  metadata.gz: ab7a238179cc66385bc1c3e02ff7da394f67d5cfda3e12d1c9b82cee9232bb06528d645d7dbe930cee6ef42509c036eac88650ad868cc79461652aeea34ee801
+  data.tar.gz: 0145bd617acdefce3a925999c96c736cae33dbb260a8c5f9e6c70579d8f5ee986ba4da9922b29294032224e2e1896753d4b85f83dfaccb9c00efc60724fba575

data/CHANGES.md

@@ -0,0 +1,20 @@
+Version History
+===============
+
+Version 1.2.0 (2013-12-29)
+--------------------------
+
+* Fixed bug which raised an error in ruby 2.0, when all chars for the short
+  accessor had already been used
+
+* Added argument setting `:optional => true`, so argument will only appear in
+  the parsed option if given by the user, thus it will not be filled using
+  the default value
+
+* Added argument setting `:no_short => true`, to prevent the creation of an
+  short accessor for the argument
+
+* Added possibility to define default settings when creating the Parser,
+  for example to prevent creation of short accessors for ALL arguments easily
+
+* Added some more tests and improved readability

data/README.md

@@ -17,7 +17,7 @@ So µ-optparse is for you if you are looking for
 What is µ-optparse?
 -------------------
 
-µ-optparse is a small wrapper around [optparse](http://www.ruby-doc.org/stdlib/libdoc/optparse/rdoc/classes/OptionParser.html), weighing **less than 75 lines of code**.
+µ-optparse is a small wrapper around [optparse](http://www.ruby-doc.org/stdlib/libdoc/optparse/rdoc/classes/OptionParser.html), weighing **less than 80 lines of code**.
 optparse (or OptionParser) on the other hand is a command line parser, which ships with ruby.
 After you defined available options, it automatically creates a help page and is able to parse ARGV accordingly.
 However, optparse requires you to repeat yourself quite often, which leads to many lines of code, just to configure the available options.
@@ -27,18 +27,21 @@ In addition, µ-optparse extends optparse by some **powerful validations**,
 Talk in code!
 -------------
 
-    require 'rubygems' # necessary for ruby v1.8.*
-    require 'micro-optparse'
-    options = Parser.new do |p|
-       p.banner = "This is a fancy script, for usage see below"
-       p.version = "fancy script 0.0 alpha"
-       p.option :severity, "set severity", :default => 4, :value_in_set => [4,5,6,7,8]
-       p.option :verbose, "enable verbose output"
-       p.option :mutation, "set mutation", :default => "MightyMutation", :value_matches => /Mutation/
-       p.option :plus_selection, "use plus-selection if set", :default => true
-       p.option :selection, "selection used", :default => "BestSelection", :short => "l"
-       p.option :chance, "set mutation chance", :default => 0.8, :value_satisfies => lambda {|x| x >= 0.0 && x <= 1.0}
-    end.process!
+```ruby
+require 'rubygems' # necessary for ruby v1.8.*
+require 'micro-optparse'
+
+options = Parser.new do |p|
+   p.banner = "This is a fancy script, for usage see below"
+   p.version = "fancy script 0.0 alpha"
+   p.option :severity, "set severity", :default => 4, :value_in_set => [4,5,6,7,8]
+   p.option :verbose, "enable verbose output"
+   p.option :mutation, "set mutation", :default => "MightyMutation", :value_matches => /Mutation/
+   p.option :plus_selection, "use plus-selection if set", :default => true
+   p.option :selection, "selection used", :default => "BestSelection", :short => "l"
+   p.option :chance, "set mutation chance", :default => 0.8, :value_satisfies => lambda {|x| x >= 0.0 && x <= 1.0}
+end.process!
+```
 
 What this piece of code does is the following:
 
@@ -65,6 +68,24 @@ The automatically generated help message looks like this:
         -h, --help                       Show this message
         -V, --version                    Print version
 
+To show some example calls and results, I will use a simplified version of the Parser above:
+
+```ruby
+require 'rubygems' # necessary for ruby v1.8.*
+require 'micro-optparse'
+
+options = Parser.new do |p|
+   p.option :severity, "set severity", :default => 4, :value_in_set => [4,5,6,7,8]
+   p.option :mutation, "set mutation", :default => "MightyMutation", :value_matches => /Mutation/
+   p.option :plus_selection, "use plus-selection if set", :default => true, :optional => true
+end.process!
+```
+
+* `ruby myprogram.rb --help` will yield a help message formatted like the one above
+* `ruby myprogram.rb` will fill the variable `options` with the hash `{:severity => 4, :mutation => "MightyMutation"}` due to the given default values (`:plus_selection` does not appear in the result, due to the `:optional => true` setting, but can still be filled by the user)
+* `ruby myprogram.rb -s 2 --mutation WeakMutation -p true` will fill the variable `options` with the hash `{:severity => 2, :mutation => "WeakMutation", :plus_selection => true}`, since the given values overwrite default values
+
+
 It doesn't stop at the command line!
 ------------------------------------
 
@@ -72,13 +93,15 @@ It doesn't stop at the command line!
 You can even process several arrays with the same parser (see example below).
 In addition, you don't need to specify all options at once, i.e. you can pass the parser around and add more options until you call the `process!`-method.
 
-    require 'rubygems' # necessary for ruby v1.8.*
-    require 'micro-optparse'
-    
-    parser = Parser.new
-    parser.option :eat_snickers, "How many?", :default => 0
-    options1 = parser.process!(["--eat-snickers", "2"])
-    options2 = parser.process!(["--eat-snickers", "1"])
+```ruby
+require 'rubygems' # necessary for ruby v1.8.*
+require 'micro-optparse'
+
+parser = Parser.new
+parser.option :eat_snickers, "How many?", :default => 0
+options1 = parser.process!(["--eat-snickers", "2"])
+options2 = parser.process!(["--eat-snickers", "1"])
+```
 
 Where do I get &micro;-optparse?
 --------------------------
@@ -90,4 +113,107 @@ If you want to contribute, you can fork this repository, make your changes and s
 However, improvements must be one of the following:
 
 * use fewer lines of code, without sacrificing readablity or functionality
-* enhance readablity or functionality, without increasing the lines of code
+* enhance readablity or functionality, without increasing the lines of code
+
+Frequently Asked Questions
+==========================
+
+All my argument values are either true or false - what's wrong?
+---------------------------------------------------------------
+You must define default values, if the option should accept an argument. Every option without a default value (or with `true` or `false` as default) is treated as a switch: true if given and false / default otherwise.
+
+Is it possible to define mandatory / required arguments, which must be provided?
+--------------------------------------------------------------------------------
+No it's not. Every option that has no default argument is a switch and if an option has a default argument, well there is a default to fall back to. However, what you can do is using &micro;-optparse to parse all options and switches (which are then removed from the ARGV array) and use everything that remains in ARGV as the mandatory arguments. Of course you have to raise an error yourself if no argument is left.
+
+Consider the following example to implement mandatory arguments yourself:
+
+```ruby
+require 'rubygems' # necessary for ruby v1.8.*
+require 'micro-optparse'
+
+options = Parser.new do |p|
+  p.option :meal, "Choose Meal", :default => "CucumberSalad"
+end.parse!
+
+raise ArgumentError, "No files given!" unless ARGV.size > 0
+file = ARGV.shift
+```
+
+If this short file is saved as `script.rb`, a call could look like the following: `ruby script.rb --meal=BrainSandwich file1.txt file2.txt`.
+
+Are long arguments with spaces and other special characters allowed?
+--------------------------------------------------------------------
+Yes, just define an option which takes a `String` as an argument, i.e. pass a string as the default value for that option. Now everything between quotes will be parsed as the value for that argument, e.g. `ruby testscript.rb --selection 'I want the best selection you have!!! And if possible, add Donuts.'` Note that double quotes may cause trouble, for example I get an error if I use an exclamation mark in double quotes, but no error in single quotes.
+
+Is it possible to define arguments which accept lists / arrays / multiple files / ... ?
+---------------------------------------------------------------------------------------
+Yes, just define an option which takes an `Array` as an argument, i.e. pass an array as the default value for that option. The input will be split by comma. If the arguments contain spaces, wrap the whole thing in single quotes or double quotes.
+
+For example if you want to accept multiple file names with whitespaces in them:
+
+```ruby
+require 'rubygems' # necessary for ruby v1.8.*
+require 'micro-optparse'
+
+options = Parser.new do |p|
+  p.option :filenames, "Files which will be processed", :default => []
+end.process!
+
+p options[:filenames]
+```
+
+`ruby testscript.rb --filenames 'todo.txt,my great adventures.txt'` yields `["todo.txt", "my great adventures.txt"]`.
+
+Is it possible define an option without a default value?
+--------------------------------------------------------
+
+Yes and No. The literal answer to this question is "No", since a default value must be given for all arguments, except switches which default to `false`. However, what you are probably trying to achieve is to define an option which does only show up in the resulting hash, if the argument was given by the user. *This is actually possible!* Just add `:optional => true` to the line where you define your option and you are ready to go! The default value is still used for type checking.
+
+```ruby
+require 'rubygems' # necessary for ruby v1.8.*
+require 'micro-optparse'
+
+options = Parser.new do |p|
+  p.option :file, "File to process (optional)", :default => "String", :optional => true
+end.process!
+
+puts options
+```
+
+Example usage of this parser:
+
+* `ruby myprogram.rb` will yield `{}`
+* `ruby myprogram.rb --file testfile.txt` will yield `{:file => "testfile.txt"}`
+
+Can I disable the short accessors?
+----------------------------------
+
+Yes you can. To disable them globally, i.e. for all arguments of the parser, just create the Parser with the default setting `:no_short => true`. To disable the short accessor of just a few arguments, add `:no_short => true` as a setting to these arguments.
+
+For example to disable short accessors for all arguments:
+
+```ruby
+require 'rubygems' # necessary for ruby v1.8.*
+require 'micro-optparse'
+
+options = Parser.new(:no_short => true) do |p|
+  p.option :foo, "Foo"
+end.process!
+
+puts options
+```
+
+To disable short accessor of just a few arguments:
+
+```ruby
+require 'rubygems' # necessary for ruby v1.8.*
+require 'micro-optparse'
+
+options = Parser.new do |p|
+  p.option :foo, "Foo without short", :no_short => true
+  p.option :bar, "Bar with short"
+end.process!
+
+puts options
+```

data/Rakefile

@@ -1,6 +1,8 @@
 require 'bundler'
 require 'rspec/core/rake_task'
 
+include Rake::DSL
+
 Bundler::GemHelper.install_tasks
 
 RSpec::Core::RakeTask.new(:spec)

data/lib/micro-optparse/parser.rb

@@ -2,15 +2,17 @@ require 'optparse'
 
 class Parser
   attr_accessor :banner, :version
-  def initialize
+  def initialize(default_settings = {})
     @options = []
     @used_short = []
-    @default_values = nil
+    @default_values = {}
+    @default_settings = default_settings
     yield self if block_given?
   end
 
   def option(name, desc, settings = {})
-    @options << [name, desc, settings]
+    settings = @default_settings.clone.merge(settings)
+    @options << {:name => name, :description => desc, :settings => settings}
   end
 
   def short_from(name)
@@ -18,45 +20,50 @@ class Parser
       next if @used_short.include?(c) || c == "_"
       return c # returns from short_from method
     end
+    return name.to_s.chars.first
   end
 
-  def validate(options) # remove this method if you want fewer lines of code and don't need validations
-    options.each_pair do |key, value|
-      opt = @options.find_all{ |o| o[0] == key }.first
+  def validate(result) # remove this method if you want fewer lines of code and don't need validations
+    result.each_pair do |key, value|
+      o = @options.find_all{ |option| option[:name] == key }.first
       key = "--" << key.to_s.gsub("_", "-")
-      unless opt[2][:value_in_set].nil? || opt[2][:value_in_set].include?(value)
-        puts "Parameter for #{key} must be in [" << opt[2][:value_in_set].join(", ") << "]" ; exit(1)
+      unless o[:settings][:value_in_set].nil? || o[:settings][:value_in_set].include?(value)
+        puts "Parameter for #{key} must be in [" << o[:settings][:value_in_set].join(", ") << "]" ; exit(1)
       end
-      unless opt[2][:value_matches].nil? || opt[2][:value_matches] =~ value
-        puts "Parameter for #{key} must match /" << opt[2][:value_matches].source << "/" ; exit(1)
+      unless o[:settings][:value_matches].nil? || o[:settings][:value_matches] =~ value
+        puts "Parameter for #{key} must match /" << o[:settings][:value_matches].source << "/" ; exit(1)
       end
-      unless opt[2][:value_satisfies].nil? || opt[2][:value_satisfies].call(value)
+      unless o[:settings][:value_satisfies].nil? || o[:settings][:value_satisfies].call(value)
         puts "Parameter for #{key} must satisfy given conditions (see description)" ; exit(1)
       end
     end
   end
 
   def process!(arguments = ARGV)
-    @result = (@default_values || {}).clone # reset or new
+    @result = @default_values.clone # reset or new
     @optionparser ||= OptionParser.new do |p| # prepare only once
       @options.each do |o|
-        @used_short << short = o[2][:short] || short_from(o[0])
-        @result[o[0]] = o[2][:default] || false # set default
-        klass = o[2][:default].class == Fixnum ? Integer : o[2][:default].class
+        @used_short << short = o[:settings][:no_short] ? nil : o[:settings][:short] || short_from(o[:name])
+        @result[o[:name]] = o[:settings][:default] || false unless o[:settings][:optional] # set default
+        name = o[:name].to_s.gsub("_", "-")
+        klass = o[:settings][:default].class == Fixnum ? Integer : o[:settings][:default].class
 
+        args = [o[:description]]
+        args << "-" + short if short
         if [TrueClass, FalseClass, NilClass].include?(klass) # boolean switch
-          p.on("-" << short, "--[no-]" << o[0].to_s.gsub("_", "-"), o[1]) {|x| @result[o[0]] = x}
-        else # argument with parameter
-          p.on("-" << short, "--" << o[0].to_s.gsub("_", "-") << " " << o[2][:default].to_s, klass, o[1]) {|x| @result[o[0]] = x}
+          args << "--[no-]" + name
+        else # argument with parameter, add class for typecheck
+          args << "--" + name + " " + o[:settings][:default].to_s << klass
         end
+        p.on(*args) {|x| @result[o[:name]] = x}
       end
 
       p.banner = @banner unless @banner.nil?
       p.on_tail("-h", "--help", "Show this message") {puts p ; exit}
       short = @used_short.include?("v") ? "-V" : "-v"
       p.on_tail(short, "--version", "Print version") {puts @version ; exit} unless @version.nil?
-      @default_values = @result.clone # save default values to reset @result in subsequent calls
     end
+    @default_values = @result.clone # save default values to reset @result in subsequent calls
 
     begin
       @optionparser.parse!(arguments)
@@ -67,4 +74,4 @@ class Parser
     validate(@result) if self.respond_to?("validate")
     @result
   end
-end
+end

data/lib/micro-optparse/version.rb

@@ -1,5 +1,5 @@
 module Micro
   module Optparse
-    VERSION = "1.1.5"
+    VERSION = "1.2.0"
   end
 end

data/micro-optparse.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Florian Pilz"]
   s.email       = ["fpilz87@googlemail.com"]
   s.homepage    = "http://florianpilz.github.com/micro-optparse/"
-  s.summary     = %q{An option parser which is 70 lines short.}
-  s.description = %q{This option parser is 70 lines short and is based on OptionParser. It has strong validations and a short, clear and easy to use syntax. Feel free to copy all 70 lines (45 lines without validations / empty lines) into your script rather installing the gem.}
+  s.summary     = %q{An lightweight option parser, which is 80 lines short.}
+  s.description = %q{This is an lightweight option parser, which is less than 80 lines short. It has strong validations and a short, clear and easy to use syntax. Feel free to copy all 80 lines (55 lines without validations / empty lines) into your script rather installing the gem.}
   
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/spec/parser_spec.rb

@@ -27,6 +27,15 @@ describe Parser do
       result[:selection].should == "BestSelection"
       result[:chance].should == 0.8
     end
+
+    it "should not return a default value if the argument is declared optional" do
+      parser = Parser.new do |p|
+        p.option :optarg, "optional argument", :optional => true
+      end
+      result = parser.process!()
+      result.has_key?(:optarg).should == false
+      result[:optarg].should == nil
+    end
   end
 
   describe "setting of custom values" do
@@ -89,6 +98,52 @@ describe Parser do
       parser.class.should == Parser
     end
   end
+
+  describe "parsing of lists" do
+    it "should parse list of arguments separated by comma when given an array as default" do
+      parser = Parser.new do |p|
+        p.option :listarg, "List Argument", :default => []
+      end
+
+      input = ['--listarg', 'foo,bar,baz']
+      parser.process!(input)[:listarg].should == ['foo', 'bar', 'baz']
+    end
+
+    it "should allow multiple argument lists" do
+      parser = Parser.new do |p|
+        p.option :first_listarg, "List Argument", :default => []
+        p.option :second_listarg, "List Argument", :default => []
+      end
+
+      input = ['-f', 'foo,bar,baz', '-s', 'blah,blah,blah']
+      result = parser.process!(input)
+      result[:first_listarg].should == ['foo', 'bar', 'baz']
+      result[:second_listarg].should == ['blah', 'blah', 'blah']
+    end
+  end
+
+  describe "default settings" do
+    it "should set default settings on all options" do
+      parser = Parser.new(:optional => true) do |p|
+        p.option :foo, "foo argument"
+        p.option :bar, "bar argument"
+      end
+
+      result = parser.process!([])
+      result.length.should == 0 # all optional
+    end
+
+    it "should allow to overwrite default settings" do
+      parser = Parser.new(:default => "Bar") do |p|
+        p.option :foo, "foo argument", :default => "Foo"
+        p.option :bar, "bar argument"
+      end
+
+      result = parser.process!([])
+      result[:foo].should == "Foo"
+      result[:bar].should == "Bar"
+    end
+  end
   
   describe "help message" do
     it "should show help message when called with --help or -h" do
@@ -195,4 +250,27 @@ describe Parser do
       result.should include("-e, --eat-me")
     end
   end
+
+  describe "assigns short for every param" do
+    it "should use every short only once" do
+      result  = `ruby spec/programs/short.rb --help`
+      result.scan(/\s-a/).length.should == 1
+      result.scan(/\s-b/).length.should == 1
+      result.scan(/\s-c/).length.should == 1
+    end
+
+    it "should use first char as short if all have been used" do
+      result  = `ruby spec/programs/short.rb --help`
+      result.should include("-a, --acb")
+      result.should include("-b, --bac")
+      result.should include("-c, --cba")
+    end
+
+    it "should be possible to prevent creation of short arguments" do
+      result  = `ruby spec/programs/noshort.rb --help`
+      result.should_not include("-f, --foo")
+      result.should include("--foo")
+      result.should include("-b, --bar")
+    end
+  end
 end

data/spec/programs/noshort.rb

@@ -0,0 +1,11 @@
+require "rubygems"
+require "micro-optparse"
+
+options = Parser.new do |p|
+  p.option :foo, "Option 1", :default => "String", :no_short => true
+  p.option :bar, "Option 2", :default => "String"
+end.process!
+
+options.each_pair do |key, value|
+  puts ":#{key} => #{value}"
+end

data/spec/programs/short.rb

@@ -0,0 +1,16 @@
+require "rubygems"
+require "micro-optparse"
+
+options = Parser.new do |p|
+  p.option :abc, "Option 1", :default => "String"
+  p.option :bca, "Option 2", :default => "String"
+  p.option :cab, "Option 3", :default => "String"
+  # all shorts used up, futher shorts overwrite previous ones
+  p.option :bac, "Option 4", :default => "String"
+  p.option :acb, "Option 5", :default => "String"
+  p.option :cba, "Option 6", :default => "String"
+end.process!
+
+options.each_pair do |key, value|
+  puts ":#{key} => #{value}"
+end

metadata

@@ -1,48 +1,41 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: micro-optparse
-version: !ruby/object:Gem::Version 
-  hash: 25
-  prerelease: 
-  segments: 
-  - 1
-  - 1
-  - 5
-  version: 1.1.5
+version: !ruby/object:Gem::Version
+  version: 1.2.0
 platform: ruby
-authors: 
+authors:
 - Florian Pilz
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-06-20 00:00:00 +02:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2013-12-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id001
-description: This option parser is 70 lines short and is based on OptionParser. It has strong validations and a short, clear and easy to use syntax. Feel free to copy all 70 lines (45 lines without validations / empty lines) into your script rather installing the gem.
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This is an lightweight option parser, which is less than 80 lines short.
+  It has strong validations and a short, clear and easy to use syntax. Feel free to
+  copy all 80 lines (55 lines without validations / empty lines) into your script
+  rather installing the gem.
+email:
 - fpilz87@googlemail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
+- CHANGES.md
 - Gemfile
 - MIT-LICENSE
 - README.md
@@ -54,43 +47,37 @@ files:
 - spec/parser_spec.rb
 - spec/programs/eating.rb
 - spec/programs/empty.rb
+- spec/programs/noshort.rb
+- spec/programs/short.rb
 - spec/programs/version.rb
-has_rdoc: true
 homepage: http://florianpilz.github.com/micro-optparse/
-licenses: 
+licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.4.2
+rubygems_version: 2.0.14
 signing_key: 
-specification_version: 3
-summary: An option parser which is 70 lines short.
-test_files: 
+specification_version: 4
+summary: An lightweight option parser, which is 80 lines short.
+test_files:
 - spec/parser_spec.rb
 - spec/programs/eating.rb
 - spec/programs/empty.rb
+- spec/programs/noshort.rb
+- spec/programs/short.rb
 - spec/programs/version.rb