clint 0.1.0

data/lib/clint.rb

@@ -0,0 +1,166 @@
+class Clint
+
+  def initialize(options={})
+    reset
+    @strict = !options[:strict].nil?
+  end
+
+  def usage
+    if block_given?
+      @usage = Proc.new
+    else
+      @usage.call if @usage.respond_to? :call
+    end
+  end
+
+  def help
+    if block_given?
+      @help = Proc.new
+    else
+      usage
+      @help.call if @help.respond_to? :call
+    end
+  end
+
+  # Reset the list of valid options and aliases.
+  def reset
+    @options, @aliases = {}, {}
+  end
+
+  # Add new valid options and aliases with either classes to be constructed
+  # or default values (from which classes are inferred).  This returns
+  # @options and thus works as an attr_reader with no arguments.
+  def options(options={})
+    options.each do |option, default|
+      option = option.to_sym
+      if Symbol == default.class
+        @aliases[option] = default
+      else
+        if Class == default.class
+          if default.respond_to? :new
+            begin
+              @options[option] = default.new
+            rescue ArgumentError
+              @options[option] = default.new(nil)
+            end
+          else
+            begin
+              @options[option] = default()
+            rescue ArgumentError
+              @options[option] = default(nil)
+            end
+          end
+        else
+          @options[option] = default
+        end
+      end
+    end
+    @options
+  end
+
+  attr_reader :aliases
+
+  # Parse arguments, saving options in @options and leaving everything else
+  # in @args.
+  def parse(args=nil)
+    args = @args if args.nil?
+    i = 0
+    while args.length > i do
+
+      # Skip anything not structured like an option.
+      case args[i]
+      when /^-([^-=\s])$/
+      when /^-([^-=\s])\s*(.+)$/
+      when /^--([^=\s]+)$/
+      when /^--([^=\s]+)(?:=|\s+)(.+)?$/
+      else
+        i += 1
+        next
+      end
+      option, value = $1.to_sym, $2
+
+      # Follow aliases through to a real option.
+      option = @aliases[option] while @aliases[option]
+
+      # Skip unknown options unless we're in strict mode.
+      if @options[option].nil?
+        if @strict
+          usage
+          exit 1
+        end
+        i += 1
+        next
+      end
+
+      # Handle boolean options.
+      if [TrueClass, FalseClass].include? @options[option].class
+        unless value.nil?
+          usage
+          exit 1
+        end
+        args.delete_at i
+        @options[option] = !@options[option]
+
+      # Handle options with values.  The call to new below may raise
+      # NoMethodError but this is allowed to surface so it's noticed
+      # during development.
+      else
+        args.delete_at i
+        value = args.delete_at(i) if value.nil?
+        if value.nil?
+          usage
+          exit 1
+        end
+        @options[option] = @options[option].class.new(value)
+
+      end
+    end
+    @args = args
+  end
+
+  # Treat the first non-option argument as a subcommand in the given class.
+  # If a suitable class method is found, it is called with all remaining
+  # arguments, including @options if we can get away with it.  Otherwise,
+  # an instance is constructed with the next non-option argument and the
+  # subcommand is sent to the instance with the remaining non-option
+  # arguments.
+  def subcommand(klass)
+    if 1 > @args.length
+      usage
+      exit 1
+    end
+    subcommand = @args.shift.to_sym
+    if klass.singleton_methods(false).include? subcommand.to_s
+      arity = klass.method(subcommand).arity
+      if @args.length != arity && -@args.length - 1 != arity
+        usage
+        exit 1
+      end
+      begin
+        klass.send subcommand, *(@args + [@options])
+      rescue ArgumentError
+        klass.send subcommand, *@args
+      end
+      exit 0
+    end
+    if 1 > @args.length
+      usage
+      exit 1
+    end
+    instance = klass.new(@args.shift)
+    if instance.public_methods(false).include? subcommand.to_s
+      arity = instance.method(subcommand).arity
+      if @args.length != arity && -@args.length - 1 != arity
+        usage
+        exit 1
+      end
+      begin
+        instance.send subcommand, *(@args + [@options])
+      rescue ArgumentError
+        instance.send subcommand, *@args
+      end
+      exit 0
+    end
+  end
+
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification 
+name: clint
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Richard Crowley
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-22 00:00:00 +00:00
+default_executable: 
+dependencies: []
+
+description: |
+  clint(7) -- Ruby command line argument parser
+  =============================================
+  
+  ## SYNOPSIS
+  
+  	require 'clint'
+  	c = Clint.new
+  	c.usage do
+  	  $stderr.puts "Usage: #{File.basename(__FILE__)} [-h|--help]"
+  	end
+  	c.help do
+  	  $stderr.puts "  -h, --help\tshow this help message"
+  	end
+  	c.options :help => false, :h => :help
+  	c.parse ARGV
+  	if c.options[:help]
+  	  c.help
+  	  exit 1
+  	end
+  	c.subcommand Klass
+  
+  ## DESCRIPTION
+  
+  Clint is an alternative Ruby command line argument parser that's very good for programs using the subcommand pattern familiar from `git`(1), `svn`(1), `apt-get`(8), and many others.  In addition, it separates option declarations from usage and help messages becuase the author feels like that's a better idea.
+  
+  Clint options are declared by passing hash arguments to `Clint#options`.  The hash keys should be `Symbol`s.  If the value is also a `Symbol`, an alias is defined from the key to the value.  If the value is a `Class`, Clint attempts to find a default value for that class.  Otherwise, the value is treated as the default and the value's class will be used to construct type-accurate values from command line arguments.
+  
+  `Clint#options` may be called repeatedly to declare extra options and aliases.  `Clint#reset` can be used at any time to clear all declared options and aliases.
+  
+  `Clint#parse` may likewise be called repeatedly.  At the end of each invocation, it stores the remaining non-option arguments, meaning that arguments (for example, `ARGV`) must only be passed as a parameter to the first invocation.
+  
+  `Clint#subcommand` may be called after `Clint#parse` to automatically handle the subcommand pattern as follows.  The first non-option argument is taken to be the subcommand, which must exist as a singleton or instance method of the class object passed to `Clint#subcommand`.  If a suitable class method is found, it is called with all remaining arguments, including a hash of the parsed options if we can get away with it.  Otherwise, an instance is constructed with the next non-option argument and the instance method is called with all remaining arguments, again including a hash of the parsed options if we can get away with it.
+  
+  Due to limitations in the Ruby 1.8 grammar, all methods that could act as subcommands must not declare default argument values except `options={}` if desired.
+  
+  ## AUTHOR
+  
+  Richard Crowley <r@rcrowley.org>
+  
+  ## SEE ALSO
+  
+  The standard Ruby `OptionParser` class <http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/classes/OptionParser.html>.
+
+email: r@rcrowley.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/clint.rb
+- man/clint.7.gz
+has_rdoc: true
+homepage: http://github.com/rcrowley/clint.git
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: command line argument parser
+test_files: []
+