magni 0.1.1

data/README.rdoc

@@ -0,0 +1,76 @@
+= Magni
+
+Magni is a command line flag parser, nothing more, nothing less. It's
+useful for when you want to collect a bunch of flags from your script,
+then do something with them all.
+== 
+=== ARGUMENT TYPES
+
+Magni accepts four types of arguments, <tt>boolean</tt>, <tt>string</tt>,
+<tt>array</tt> and <tt>integer</tt>.
+  
+  boolean:   --foo          #=> true
+  integer:   --foo=4        #=> 4
+   string:   --foo=theory   #=> "theory"
+    array:   --foo=1,2,3    #=> [1, 2, 3]
+
+=== MAPPINGS
+
+Magni is the son of Thor[http://github.com/wycats/thor] and so he inherited 
+some of his father's traits; mapping being one of them.
+  
+  class Runner < Magni
+    map "--maxerr" => :integer
+    map "--name"   => :string
+    map "--help"   => :boolean
+  end
+
+There are a couple special keywords that work with mappings too, <tt>:first</tt>
+and <tt>:last</tt>. Each one will place the first or last, respectively,
+argument in an instance variable for you. This is useful when the last
+argument of your script is a file or command for example.
+
+  map :last => :file
+  
+  > script --hello world.rb
+  @file #=> "world.rb"
+
+=== BIN SCRIPT
+
+Tell Magni where to go after it does it's flag parsing magic. 
+<tt>delegate_to</tt> takes two arguments. The first is your Magni subclass
+and the second is the method you want to be called when Magni is done:
+
+  Magni.delegate_to(Runner, :method)
+  
+=== USING THE FLAGS
+  
+Flags and values are saved in <tt>@options</tt>. From the example above:
+
+  > script --maxerr=4 --name=Matte
+  @options #=> { :maxerr => 4, :name => "Matte" }
+  
+== License
+  
+  (The MIT License)
+  
+  Copyright (c) 2010 FIXME full name
+  
+  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/lib/magni.rb

@@ -0,0 +1,141 @@
+class MagniAttributeError < Exception; end
+
+class Magni
+  class << self
+    attr_accessor :mappings
+    attr_accessor :keywords
+    
+    # Maps a flag to a argument type. Flags are then put into the
+    # <tt>options</tt> instance variable. You can map two types:
+    #
+    # Literal Double Dash Flags:
+    #
+    #     map "--maxerrors" => :integer
+    #
+    # These can be one of four types: <tt>:integer</tt>, <tt>:string</tt>, 
+    # <tt>:array</tt> and <tt>:boolean</tt>.
+    #
+    #     :integer #=> --count=2
+    #     :string  #=> --word=bird
+    #     :array   #=> --ravens=huginn,munnin
+    #     :boolean #=> --all
+    #
+    #
+    # Special Keywords are used to pull out a non-flag argument. This is
+    # useful when the first or last argument needs to be the target of
+    # your script; a file for example.
+    #
+    # Special keywords map to an instance variable on the instance your 
+    # class. The following example will pull out the last argument from
+    # the list and put it in the <tt>@file</tt> instance variable.
+    # Currently there are only two keyword mappings, <tt>:first</tt> and
+    # <tt>last</tt>:
+    #
+    #     map :first => :foo
+    #     map :last  => :bar
+    # 
+    #
+    # Parameters
+    #     mapping: Hash[ Flag/Keyword => Type/iVar ]
+    #
+    def map(mapping={})
+      @mappings ||= {}
+      @keywords ||= {}
+      
+      mapping.each do |flag, type|
+        if is_map_keyword?(flag)
+          @keywords[flag] = type
+        else
+          @mappings[flag.gsub(/[-]+/, "")] = type
+        end
+      end
+    end
+
+    # Tells Magni where to send the processed flags and arguments.
+    #
+    #    # runner.rb
+    #    class Runner < Magni
+    #      map "--help" => :boolean
+    #
+    #      def start
+    #        ...
+    #      end
+    #    end
+    #
+    #    # bin_script.rb
+    #    Magni.delegate_to(Runner, :start)
+    #
+    # Parameters
+    #
+    #    klass:  Your "runner" class
+    #    method: The method you want executed after flags are processed
+    #
+    def delegate_to(klass, method)
+      klass.new(ARGV.dup).send(method)
+    end
+    
+  private
+    
+    def is_map_keyword?(flag)
+      [:first, :last].include?(flag)
+    end
+  end
+  
+  attr_accessor :options
+  
+  def initialize(options=[])
+    self.class.mappings ||= {}
+    @options            ||= {}
+    
+    options = extract_keywords(options)
+    options.each do |opt|
+      flag, *values = opt.gsub(/[-]+/, "").split(/[=,]/)
+      process(flag, values)
+    end
+  end
+  
+  # Pulls the keyworded flags out of the ARGV array and puts them
+  # in the mapped instance variables.
+  #
+  def extract_keywords(opts=[])
+    self.class.keywords.each do |keyword, ivar|
+      Magni.class_eval { attr_accessor ivar }
+      instance_variable_set("@#{ ivar }", opts.delete(opts.send(keyword)))
+    end
+    opts
+  end
+  
+  # Pulls the type of argument +flag+ is set to in +mappings+
+  # then sets the +options+ key to value "coerced" to the
+  # matching argument type.
+  #
+  def process(flag, values)
+    type = self.class.mappings[flag]
+    unless type.nil?
+      @options[flag.to_sym] = send("to_#{ type }", values)
+    end
+  end
+  
+private
+  
+  def to_boolean(values=[])
+    raise MagniAttributeError, "Expected boolean." unless values.empty?
+    true
+  end
+  
+  def to_integer(values=[])
+    raise MagniAttributeError, "Expected integer." unless values[0] =~ /\d/
+    values.pop.to_i
+  end
+
+  def to_array(values=[])
+    raise MagniAttributeError, "Expected array." if values.empty?
+    values.map { |value| (value.to_i if value =~ /\d/) || value }
+  end
+
+  def to_string(values=[])
+    raise MagniAttributeError, "Expected string." if values.size > 1
+    values.pop.to_s
+  end
+
+end

data/spec/magni_spec.rb

@@ -0,0 +1,107 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe Magni do
+  
+  before :each do
+    @test = Test.new
+  end
+  
+  describe "mappings" do
+    it "should map to :boolean" do
+      Test.mappings['boolean'].should == :boolean
+    end
+    
+    it "should map to :integer" do
+      Test.mappings['integer'].should == :integer
+    end
+    
+    it "should map to :string" do
+      Test.mappings['string'].should == :string
+    end
+    
+    it "should map to :array" do
+      Test.mappings['array'].should == :array
+    end
+  end
+  
+  describe "booleans" do
+    it "should be processes into a boolean" do
+      @test.process("boolean", [])
+      @test.options[:boolean].should == true
+    end
+    
+    it "should raise an error when passed a value" do
+      lambda { Test.new(["--boolean=wrong"]) }.should raise_error
+    end
+  end
+  
+  describe "integers" do
+    it "should be processes into a fixnum" do
+      @test.process("integer", ["2"])
+      @test.options[:integer].should == 2
+    end
+    
+    it "should raise an error when passed a string" do
+      lambda { Test.new(["--integer=abc"]) }.should raise_error
+    end
+  end
+  
+  describe "strings" do
+    it "should be processes into a string" do
+      @test.process("string", ["hello"])
+      @test.options[:string].should == "hello"
+    end
+    
+    it "should raise an error when passed an array" do
+      lambda { Test.new(["--string=a,b,c"]) }.should raise_error
+    end
+  end
+  
+  describe "arrays" do
+    it "should be processes into an array" do
+      @test.process("array", ["a", "b", "c"])
+      @test.options[:array].should == ["a", "b", "c"]
+    end
+    
+    it "should raise an error when no values are received" do
+      lambda { Test.new(["--array"]) }.should raise_error
+    end
+  end
+  
+  describe "keywords" do
+    it "should map the last argument to an instance variable" do
+      LastKeywordTest.keywords[:last].should == :file
+    end
+    
+    it "should populate the instance variable with the :last flag value" do
+      test = LastKeywordTest.new(["example.js"])
+      test.file.should == "example.js"
+    end
+  end
+  
+  it "should accept multiple arguments" do
+    test = Test.new(["--integer=9", "--string=wing", "--array=1,2,3,4"])
+    test.options[:integer].should == 9
+    test.options[:string].should == "wing"
+    test.options[:array].should == [1, 2, 3, 4]
+  end
+  
+  it "should silently ignore non-flag command line arguments" do
+    lambda { Test.new(["omgdontfail", "whatthe"]) }.should_not raise_error
+  end
+  
+  it "should not set non-flag arguments in options" do
+    test = Test.new(["omgdontfail"])
+    test.options.should be_empty
+  end
+  
+  it "should delegate to the class given" do
+    class Controller; def invoke; end; end
+    controller = Controller.new
+    Controller.stub!(:new).and_return(controller)
+    
+    controller.should_receive(:invoke)
+    Magni.delegate_to(Controller, :invoke)
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+require File.dirname(__FILE__) + '/../lib/magni'
+
+class Test < Magni
+  map "--boolean" => :boolean
+  map "--array"   => :array
+  map "--integer" => :integer
+  map "--string"  => :string
+end
+
+class LastKeywordTest < Magni
+  map :last => :file
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: magni
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Matte Noble
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-23 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Simple command line flag parser.
+email: me@mattenoble.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- lib/magni.rb
+has_rdoc: true
+homepage: http://github.com/mnoble/magni
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Simple command line flag parser.
+test_files: 
+- spec/spec_helper.rb
+- spec/magni_spec.rb