clip 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+=== 0.0.1 / 2008-04-03
+
+* Initial release for y'all to throw rotten veggies at
+

data/README.txt

@@ -0,0 +1,94 @@
+= clip
+
+== DESCRIPTION:
+
+Yeah yeah yeah. Why in heaven's name do we need yet another
+command-line parser? Well, OptionParser is all well and good, but
+doesn't grease the skids as much as I'd like. So I wrote this little
+library... driven completely by specs.
+
+Cheers!
+
+== FEATURES
+
+You like command-line parsing, but you hate all of the bloat. Why
+should you have to create a Hash, then create a parser, then fill
+that Hash out then throw the parser away (unless you want to print
+out a usage message) and deal with a Hash? Why, for Pete's sake, should
+the parser and the parsed values be handled by two different objects?
+
+Well, now they don't...
+
+== SYNOPSIS:
+
+And it goes a little something like this...
+
+  require "rubygems"
+  require "clip"
+
+  parser = Clip do |p|
+    p.optional 's', 'server', :desc => 'The server name', :default => 'localhost'
+    p.optional 'p', 'port', :desc => 'The port', :default => 8080
+    p.required 'f', 'files', :multi => true, :desc => 'Files to send'
+    p.flag     'v', 'verbose', :desc => 'Make it chatty'
+  end
+
+  if parser.valid?
+    if parser.verbose?
+      puts parser.host
+      puts parser.port
+      puts 'files:'
+      parser.files.each do |f|
+        puts "\t#{f}"
+      end
+    end
+  else
+    # print error message(s) and usage
+    $stderr.puts parser.to_s
+  end
+
+The names of the options and flags that you declare in the block are accessible
+as methods on the returned object, reducing the amount of objects you have to
+deal with when you're parsing command-line parameters.
+
+Simply invoking the <tt>to_s</tt> method on a parser instance will dump both the
+correct usage and any errors encountered during parsing. No need for you to manage
+the state of what's required and what isn't by yourself. Also, '--help' and '-h'
+will automatically trigger Clip to dump out usage and exit.
+
+Sometimes you have additional arguments you need to process that don't require
+a named option or flag. Whatever remains on the command line that doesn't fit
+either a flag or an option/value pair will be made available via the
+<tt>remainder</tt> method of the returned object.
+
+== PROBLEMS/DEFICIENCIES:
+
+OK, some of your favorite <tt>OptionParser</tt> features are simply not here.
+You know that cool thing you can do where you tell <tt>OptionParser</tt> the
+class of the kind of object you would like to get for a particular argument?
+Do you like that one? Well, too bad. We don't have that one. Deal with it.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Alex Vollmer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/bin/sample_parser

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+require File.join(File.dirname(__FILE__), "../lib/clip")
+
+##
+# This is a very simple example of how to use Clip
+p = Clip do |c|
+  c.optional 's', 'server', :desc => 'The server name', :default => 'localhost'
+  c.optional 'p', 'port', :desc => 'The port', :default => 8080
+  c.optional 'f', 'files', :desc => 'Files to upload', :multi => true
+  c.flag 'v', 'verbose', :desc => 'Make it verbose, man'
+end
+  
+printf("%10s %-20s\n", "attribute", "value")
+[:server, :port, :verbose?].each do |att|
+  printf("%10s %-20s\n", att, p.send(att))
+end
+printf("%10s %-20s\n", "files", p.files.inspect)

data/lib/clip.rb

@@ -0,0 +1,324 @@
+#!/usr/bin/env ruby
+
+##
+# Parse arguments (defaults to <tt>ARGV</tt>) with the Clip::Parser
+# configured in the given block. This is the main method you
+# call to get the ball rolling.
+def Clip(args=ARGV)
+  parser = Clip::Parser.new
+  raise "Dontcha wanna configure your parser?" unless block_given?
+  yield parser
+  parser.parse(args)
+  parser
+end
+
+module Clip
+  VERSION = "0.0.1"
+
+  ##
+  # Indicates that the parser was incorrectly configured in the
+  # block yielded by the +parse+ method.
+  class IllegalConfiguration < Exception
+  end
+
+  class Parser
+    ##
+    # Returns any remaining command line arguments that were not parsed
+    # because they were neither flags or option/value pairs
+    attr_reader :remainder
+
+    ##
+    # Declare an optional parameter for your parser. This creates an accessor
+    # method matching the <tt>long</tt> parameter. The <tt>short</tt> parameter
+    # indicates the single-letter equivalent. Options that use the '-'
+    # character as a word separator are converted to method names using
+    # '_'. For example the name 'exclude-files' would create a method named
+    # <tt>exclude_files</tt>.
+    #
+    # When the <tt>:multi</tt> option is enabled, the associated accessor
+    # method will return an <tt>Array</tt> instead of a single scalar value.
+    # === options
+    # Valid options include:
+    # * <tt>desc</tt>: a helpful description (used for printing usage)
+    # * <tt>default</tt>: a default value to provide if one is not given
+    # * <tt>multi</tt>: indicates that mulitple values are okay for this param.
+    #
+    # Note that specifying the <tt>:multi</tt> option means that the parameter
+    # can be specified several times with different values, or that a single
+    # comma-separated value can be specified which will then be broken up into
+    # separate tokens.
+    def optional(short, long, options={})
+      short = short.to_sym
+      long = long.to_sym
+      check_args(short, long)
+
+      eval <<-EOF
+        def #{long}=(val)
+          @#{long} = val
+        end
+
+        def #{long}
+          @#{long}
+        end
+      EOF
+
+      self.options[long] = Option.new(short, long, options)
+      self.options[short] = self.options[long]
+      self.order << self.options[long]
+    end
+
+    alias_method :opt, :optional
+
+    ##
+    # Declare a required parameter for your parser. If this parameter
+    # is not provided in the parsed content, the parser instance
+    # will be invalid (i.e. where valid? returns <tt>false</tt>).
+    #
+    # This method takes the same options as the optional method.
+    def required(short, long, options={})
+      optional(short, long, options.merge({ :required => true }))
+    end
+
+    alias_method :req, :required
+
+    ##
+    # Declare a parameter as a simple boolean flag. This declaration
+    # will create a "question" method matching the given <tt>long</tt>.
+    # For example, declaring with the name of 'verbose' will create a
+    # method on your parser called <tt>verbose?</tt>.
+    # === options
+    # Valid options are:
+    # * <tt>desc</tt>: Descriptive text for the flag
+    def flag(short, long, options={})
+      short = short.to_sym
+      long = long.to_sym
+
+      check_args(short, long)
+
+      eval <<-EOF
+        def flag_#{long}
+          @#{long} = true
+        end
+
+        def #{long}?
+          return @#{long} || false
+        end
+      EOF
+
+      self.options[long] = Flag.new(short, long, options)
+      self.options[short] = self.options[long]
+      self.order << self.options[long]
+    end
+
+    def initialize # :nodoc:
+      @errors = {}
+      @valid = true
+    end
+
+    ##
+    # Parse the given <tt>args</tt> and set the corresponding instance
+    # fields to the given values. If any errors occurred during parsing
+    # you can get them from the <tt>Hash</tt> returned by the +errors+ method.
+    def parse(args)
+      @valid = true
+      args = args.split(/\s+/) unless args.kind_of?(Array)
+      consumed = []
+      if args.member?("--help")
+        puts help
+        exit 0
+      end
+      param, value = nil, nil
+    
+      args.each do |token|
+        case token
+        when /^-(-)?\w/
+          consumed << token
+          param = token.sub(/^-(-)?/, '').sub('-', '_').to_sym
+          value = nil
+        else
+          if param
+            consumed << token
+            value = token
+          end
+        end
+
+        option = options[param]
+        if option
+          if (value.nil? && option.kind_of?(Flag)) || value
+            option.process(self, value)
+          end
+        else
+          @errors[param] = "Unrecoginzed parameter"
+          @valid = false
+          next
+        end
+
+        unless value.nil?
+          param = nil
+          value = nil
+        end
+      end
+
+      @remainder = args - consumed
+
+      # Find required options that are missing arguments
+      options.each do |param, opt|
+        if opt.kind_of?(Option) and self.send(opt.long).nil?
+          if opt.required?
+            @valid = false
+            @errors[opt.long.to_sym] = "Missing required parameter: #{opt.long}"
+          elsif opt.has_default?
+            opt.process(self, opt.default)
+          end
+        end
+      end
+    end
+
+    ##
+    # Indicates whether or not the parsing process succeeded. If this
+    # returns <tt>false</tt> you probably just want to print out a call
+    # to the to_s method.
+    def valid?
+      @valid
+    end
+
+    ##
+    # Returns a <tt>Hash</tt> of errors (by the long name) of any errors
+    # encountered during parsing. If you simply want to display error
+    # messages to the user, you can just print out a call to the
+    # to_s method.
+    def errors
+      @errors
+    end
+
+    ##
+    # Returns a formatted <tt>String</tt> indicating the usage of the parser
+    def help
+      out = ""
+      out << "Usage:\n"
+      order.each do |option|
+        out << "#{option.usage}\n"
+      end
+      out
+    end
+
+    ##
+    # Returns a formatted <tt>String</tt> of the +help+ method prefixed by
+    # any parsing errors. Either way you have _one_ method to call to
+    # let your users know what to do.
+    def to_s
+      out = ""
+      unless valid?
+        out << "Errors:\n"
+        errors.each do |field, msg|
+          out << "#{field}: #{msg}\n"
+        end
+      end
+      out << help
+    end
+
+    def options # :nodoc:
+      (@options ||= {})
+    end
+
+    def order # :nodoc:
+      (@order ||= [])
+    end
+
+    private 
+    def check_args(short, long)
+      short = short.to_sym
+      long = long.to_sym
+
+      if long == :help
+        raise IllegalConfiguration.new("You cannot override the built-in 'help' parameter")
+      end
+
+      if short == :h
+        raise IllegalConfiguration.new("You cannot override the built-in 'h' parameter")
+      end
+
+      if self.options.has_key?(long)
+        raise IllegalConfiguration.new("You have already defined a parameter/flag for #{long}")
+      end
+
+      if self.options.has_key?(short)
+        raise IllegalConfiguration.new("You already have a defined parameter/flag for the short key '#{short}")
+      end
+    end
+  end
+
+  class Option # :nodoc:
+    attr_accessor :long, :short, :description, :default, :required, :multi
+
+    def initialize(short, long, options)
+      @short = short
+      @long = long
+      @description = options[:desc]
+      @default = options[:default]
+      @required = options[:required]
+      @multi = options[:multi]
+    end
+
+    def process(parser, value)
+      if @multi
+        current = parser.send(@long) || []
+        current.concat(value.split(','))
+        parser.send("#{@long}=".to_sym, current)
+      else
+        parser.send("#{@long}=".to_sym, value)
+      end
+    end
+
+    def required?
+      @required == true
+    end
+
+    def has_default?
+      not @default.nil?
+    end
+
+    def multi?
+      @multi == true
+    end
+  
+    def usage
+      out = sprintf('-%-2s --%-10s %s',
+                    @short,
+                    @long.to_s.gsub('_', '-').to_sym,
+                    @description)
+      out << " (defaults to '#{@default}')" if @default
+      out << " REQUIRED" if @required
+      out
+    end
+  end
+
+  class Flag # :nodoc:
+    
+    attr_accessor :long, :short, :description
+
+    ##
+    # nodoc
+    def initialize(short, long, options)
+      @short = short
+      @long = long
+      @description = options[:desc]
+    end
+
+    def process(parser, value)
+      parser.send("flag_#{@long}".to_sym)
+    end
+
+    def required?
+      false
+    end
+
+    def has_default?
+      false
+    end
+  
+    def usage
+      sprintf('-%-2s --%-10s %s', @short, @long, @description)
+    end
+  end
+end

data/spec/clip_spec.rb

@@ -0,0 +1,269 @@
+require "#{File.dirname(__FILE__)}/../lib/clip"
+require "rubygems"
+require "spec"
+
+class HaveErrors
+
+  def matches?(target)
+    @target = target
+    not @target.errors.empty?
+  end
+
+  def failure_message
+    "expected #{@target} to have errors"
+  end
+
+  def negative_failure_message
+    "expected #{@target} to have no errors, but... #{@target.errors.inspect}"
+  end
+end
+
+def have_errors
+  HaveErrors.new
+end
+
+class HaveErrorsOn
+  def initialize(expected)
+    @expected = expected
+  end
+
+  def matches?(target)
+    @target = target
+    not @target.errors[@expected.to_sym].nil?
+  end
+
+  def failure_message
+    "expected error message for #{@expected} on #{@target}"
+  end
+
+  def negative_failure_message
+    "unexpected error message for #{@expected} on #{@target}"
+  end
+end
+
+def have_errors_on(expected)
+  HaveErrorsOn.new(expected)
+end
+
+describe Clip do
+
+  def parse(line)
+    Clip(line) do |p|
+      p.flag 'v', 'verbose', :desc => 'Provide verbose output'
+      p.optional 's', 'server', :desc => 'The hostname', :default => 'localhost'
+      p.optional 'p', 'port', :desc => 'The port number', :default => 8080
+      p.required 'f', 'files', :desc => 'Files to upload', :multi => true
+      p.optional 'e', 'exclude_from', :desc => 'Directories to exclude'
+    end
+  end
+
+  describe "When long command-line parameters are parsed" do  
+
+    it "should create accessor methods for declarations" do
+      parser = parse('')
+      parser.should respond_to(:server)
+      parser.should respond_to(:server=)
+      parser.should respond_to(:port)
+      parser.should respond_to(:port)
+      parser.should respond_to(:files)
+      parser.should respond_to(:files=)
+      parser.should respond_to(:verbose?)
+      parser.should respond_to(:flag_verbose)
+    end
+
+    it "should set fields for flags to 'true'" do
+      parser = parse('--verbose --files foo')
+      parser.should be_verbose
+      parser.should be_valid
+      parser.should_not have_errors
+    end
+  
+    it "should set fields for flags with the given values" do
+      parser = parse('--server localhost --port 8080 --files foo')
+      parser.server.should eql("localhost")
+      parser.port.should eql("8080")
+      parser.should be_valid
+      parser.should_not have_errors
+    end
+
+    it "should map flags with '-' to methods with '_'" do
+      parser = parse('--exclude-from /Users --files foo')
+      parser.exclude_from.should eql("/Users")
+      parser.should be_valid
+      parser.should_not have_errors
+    end
+
+    it "should be invalid for unknown flags" do
+      parser = parse('--non-existent')
+      parser.should_not be_valid
+      parser.should have_errors_on(:non_existent)
+    end
+  end
+
+  describe "When short (single-letter) command-line parse are parsed" do
+  
+    it "should set flags to true" do
+      parser = parse("-v --files foo")
+      parser.should be_verbose
+      parser.should_not have_errors
+      parser.should be_valid
+    end
+  
+    it "should set fields for short options" do
+      parser = parse("-s localhost -p 8080 --files foo")
+      parser.should_not have_errors
+      parser.should be_valid
+      parser.server.should eql("localhost")
+      parser.port.should eql("8080")
+      parser.should_not be_verbose
+    end
+  end
+
+  describe "When parameters are marked as required" do
+  
+    it "should be invalid when there are missing arguments" do
+      parser = parse('--server localhost')
+      parser.should_not be_valid
+      parser.should have_errors_on(:files)
+    end
+  end
+
+  describe "When parameters are marked with defaults" do
+  
+    it "should provide default parameter values when none are parsed" do
+      parser = parse('--files foo')
+      parser.should be_valid
+      parser.should_not have_errors
+      parser.server.should eql("localhost")
+      parser.port.should eql(8080)
+    end
+  end
+
+  describe "Multi-valued parameters" do
+
+    it "should handle multiple value for the same parameter" do
+      parser = parse("--files foo --files bar --files baz")
+      parser.should be_valid
+      parser.should_not have_errors
+      parser.files.should == %w[foo bar baz]
+    end
+
+    it "should handle comma-separated values as multiples" do
+      parser = parse("--files foo,bar,baz")
+      parser.should be_valid
+      parser.should_not have_errors
+      parser.files.should == %w[foo bar baz]
+    end
+  end
+
+  describe "Help output" do
+    it "should print out some sensible usage info for to_s" do
+      out = parse('--files foo').to_s.split("\n")
+      out[0].should match(/Usage/)
+      out[1].should match(/-v\s+--verbose\s+Provide verbose output/)
+      out[2].should match(/-s\s+--server\s+The hostname.*default.*localhost/)
+      out[3].should match(/-p\s+--port\s+The port number/)
+      out[4].should match(/-f\s+--files\s+Files to upload.*REQUIRED/)
+      out[5].should match(/-e\s+--exclude-from\s+Directories to exclude/)
+    end
+
+    it "should include error messages in to_s" do
+      parser = parse('')
+      out = parser.to_s.split("\n")
+      out[0].should match(/Error/)
+      out[1].should match(/missing required.*files/i)
+      out[2..-1].join("\n").strip.should == parser.help.strip
+    end
+  end
+
+  describe "Additional arguments" do
+    it "should be made available" do
+      parser = parse('--files foo alpha bravo')
+      parser.files.should == %w[foo]
+      parser.remainder.should == %w[alpha bravo]
+    end
+  end
+
+  describe "Declaring bad options and flags" do
+
+    def misconfig_parser
+      lambda do
+        Clip("foo") do |c|
+          yield c
+        end
+      end.should raise_error(Clip::IllegalConfiguration)
+    end
+
+    it "should reject :help as a flag name" do
+      misconfig_parser { |c| c.flag 'x', 'help' }
+    end
+
+    it "should reject :help as an optional name" do
+      misconfig_parser { |c| c.optional 'x', 'help' }
+    end
+
+    it "should reject 'h' as a short flag name" do
+      misconfig_parser { |c| c.flag 'h', 'foo' }
+    end
+
+    it "should reject 'h' as a short parameter name" do
+      misconfig_parser { |c| c.optional 'h', 'foo' }
+    end
+
+    it "should reject redefining an existing long name for two options" do
+      misconfig_parser do |c|
+        c.optional 'f', 'foo'
+        c.optional 'x', 'foo'
+      end
+    end
+
+    it "should reject redefining an existing long name for an option & flag" do
+      misconfig_parser do |c|
+        c.optional 'f', 'foo'
+        c.flag 'x', 'foo'
+      end
+    end
+
+    it "should reject redefining the same flag" do
+      misconfig_parser do |c|
+        c.flag 'f', 'foo'
+        c.flag 'x', 'foo'
+      end
+    end
+
+    it "should reject defining a flag with an option" do
+      misconfig_parser do |c|
+        c.flag 'f', 'foo'
+        c.optional 'x', 'foo'
+      end
+    end
+
+    it "should reject redefining an existing short name for options" do
+      misconfig_parser do |c|
+        c.optional 'f', 'foo'
+        c.optional 'f', 'files'
+      end
+    end
+
+    it "should reject redefining a short option with a flag" do
+      misconfig_parser do |c|
+        c.optional 'f', 'foo'
+        c.flag 'f', 'fail'
+      end
+    end
+
+    it "should reject redefining a short flag with a flag" do
+      misconfig_parser do |c|
+        c.flag 'f', 'fail'
+        c.flag 'f', 'foo'
+      end
+    end
+
+    it "should reject redefining a flag with an optional" do
+      misconfig_parser do |c|
+        c.flag 'f', 'fail'
+        c.optional 'f', 'foo'
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: clip
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Alex Vollmer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-04-10 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.5.1
+    version: 
+description: Command-line parsing made short and sweet
+email: 
+- alex.vollmer@gmail.com
+executables: 
+- sample_parser
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- README.txt
+files: 
+- History.txt
+- README.txt
+- bin/sample_parser
+- lib/clip.rb
+- spec/clip_spec.rb
+has_rdoc: true
+homepage: http://clip.rubyforge.org
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: clip
+rubygems_version: 1.1.0
+signing_key: 
+specification_version: 2
+summary: Command-line parsing made short and sweet
+test_files: []
+