CommandLine 0.6.0

data/lib/commandline.rb

@@ -0,0 +1,15 @@
+#  $Id$
+#  $Source$
+#
+#  Author: Jim Freeze
+#  Copyright (c) 2005
+#
+# =DESCRIPTION
+# Loader
+#
+# =Revision History
+#  Jim.Freeze 2005/06/17 Birthday
+#
+
+require 'commandline/utils'
+require 'commandline/application'

data/lib/commandline/application.rb

@@ -0,0 +1,320 @@
+#  $Id$
+#  $Source$
+#
+#  Author: Jim Freeze
+#  Copyright (c) 2005
+#
+# =DESCRIPTION
+# Framework for commandline applications
+#
+# =Revision History
+#  Jim.Freeze 06/02/2005 Birthday - kinda
+#
+
+require 'commandline/utils'
+require 'commandline/optionparser'
+
+module CommandLine
+class Application
+  class ApplicationError          < StandardError; end
+  class OptionError               < ApplicationError; end
+  class MissingMainError          < ApplicationError; end
+  class InvalidArgumentArityError < ApplicationError; end
+  class ArgumentError             < ApplicationError; end
+
+  param_accessor :version, :author, :copyright, :synopsis,
+                 :short_description, :long_description,
+                 :option_parser
+
+  #
+  # TODO: Consolidate these with OptionParser - put in command line
+  #
+  DEFAULT_CONSOLE_WIDTH = 70
+  MIN_CONSOLE_WIDTH     = 10
+  DEFAULT_BODY_INDENT   =  4
+
+  #def options
+  #  raise(OptionError,
+  #    "Options must be over-written with a valid (or empty) options list.")
+  #end
+
+  def initialize
+    # Ensure initializations have taken place
+    @arg_arity     ||= [0,0]
+    @options       ||= []
+    @arg_names     ||= []
+    @option_parser ||= CommandLine::OptionParser.new(@options)
+    _init_format
+
+    if ARGV.empty? && [0,0] != @arg_arity
+      puts usage
+      exit(0)
+    end
+
+    @option_data = @option_parser.parse 
+
+    validate_args(@option_data.args)
+    @arg_names.each_with_index { |name, idx|
+      instance_variable_set("@#{name}", @option_data.args[idx])
+    }
+  end
+
+  def _init_format
+    #
+    # Formatting defaults
+    #
+    console_width = ENV["COLUMNS"]
+    @columns = 
+      if console_width.nil?
+        DEFAULT_CONSOLE_WIDTH
+      elsif console_width < MIN_CONSOLE_WIDTH
+        console_width
+      else
+        console_width - DEFAULT_BODY_INDENT
+      end
+    @body_indent   = DEFAULT_BODY_INDENT
+    @tag_paragraph = false
+    @order         = :index  # | :alpha
+  end
+
+  def validate_args(od_args)
+    size = od_args.size
+    min, max = @arg_arity
+    max = 1.0/0.0 if -1 == max
+    raise(ArgumentError, 
+      "Missing expected arguments. Found #{size} but expected #{min}.\n"+
+      "#{usage}") if size < min
+    raise(ArgumentError, "Too many arguments. Found #{size} but "+
+      "expected #{max}.\n#{usage}") if size > max
+  end
+
+  def option(*args)
+    @options ||= []
+    new_list = []
+    args.each { |arg|
+      new_list << 
+      case arg
+        when :help    then _help
+        when :debug   then _debug
+        when :verbose then _verbose
+        when :version then _version
+        else arg
+      end
+    }
+    #p new_list
+    @options << CommandLine::Option.new(*new_list)
+  end
+
+  #
+  # Args tells the application how many arguments (not belonging
+  # any option) are expected to be seen on the command line
+  # The names of the args are used for describing the synopsis (or usage).
+  # If there is an indeterminant amount of arguments, they are not
+  # named, but returned in an array.
+  # Many forms are valid. Some examples follow:
+  #   args 0
+  #   synopsis: Usage: app
+
+  #   args :none
+  #   synopsis: Usage: app
+
+  #   args 1                #=> args is array
+  #   synopsis: Usage: app arg
+
+  #   args 2                #=> args is array
+  #   synopsis: Usage: app arg1 arg2
+
+  #   args 10               #=> args is array
+  #   synopsis: Usage: app arg1 ... arg10
+
+  #   args :file            #=> @file = <arg>
+  #   synopsis: Usage: app file
+
+  #   args :file1, :file2   #=> @file1 = <arg1>, @file2 = <arg2>
+  #   synopsis: Usage: app file1 file2
+
+  #   args [0,1]            #=> args is array
+  #   synopsis: Usage: app [arg [arg]]
+
+  #   args [2,3]            #=> args is array
+  #   synopsis: Usage: app arg[2,3]
+
+  #   args [0,-1]           #=> args is array
+  #   synopsis: Usage: app [arg [arg...]]
+  #
+  def args(*expected_args)
+    @arg_names = []
+    case expected_args.size
+    when 0 then @arg_arity = [0,0]
+    when 1
+      case expected_args[0]
+      when Fixnum 
+        v = expected_args[0]
+        @arg_arity = [v,v]
+      when Symbol
+        @arg_names = expected_args
+        @arg_arity = [1,1]
+      when Array
+        v = expected_args[0]
+        validate_arg_arity(v)
+        @arg_arity = v
+      else 
+        raise(InvalidArgumentArityError, 
+          "Args must be a Fixnum or Array: #{expected_args[0].inspect}.")
+      end
+    else
+      @arg_names = expected_args
+      size = expected_args.size
+      @arg_arity = [size, size]
+    end
+  end
+
+  def validate_arg_arity(arity)
+    min, max = *arity
+    raise(InvalidArgumentArityError, "Minimum argument arity '#{min}' must be "+
+      "greater than or equal to 0.") unless min >= 0
+    raise(InvalidArgumentArityError, "Maximum argument arity '#{max}' must be "+
+      "greater than or equal to -1.") if max < -1
+    raise(InvalidArgumentArityError, "Maximum argument arity '#{max}' must be "+
+      "greater than minimum arg_arity '#{min}'.") if max < min && max != -1
+  end
+
+  def usage
+    " Usage: #{name} #{synopsis}"
+  end
+
+  def man
+    require 'commandline/text/format'
+    f = Text::Format.new
+    f = Text::Format.new
+    f.columns = @columns
+    f.first_indent  = 4
+    f.body_indent   = @body_indent
+    f.tag_paragraph = false
+
+    s = []
+    s << ["NAME\n"]
+
+    nm = "#{short_description}".empty? ? name : "#{name} - #{short_description}"
+    s << f.format(nm)
+
+    sn = "#{synopsis}"
+    unless sn.empty?
+      s << "SYNOPSIS\n"
+      s << f.format(sn)
+    end
+
+    dc = "#{long_description}"
+    unless dc.empty?
+      s << "DESCRIPTION\n"
+      s << f.format(dc)
+    end
+
+    op = option_parser.to_s
+    unless op.empty?
+      s << option_parser.to_s
+    end
+
+    ar = "#{author}"
+    unless ar.empty?
+      s << "AUTHOR:  #{ar}"
+    end
+
+
+    ct = "#{copyright}"
+    unless ct.empty?
+      s << ct
+    end
+
+    s.join("\n")
+  end
+  alias :help :man
+
+  def pathname
+    @@appname
+  end
+
+  def name
+    File.basename(pathname)
+  end
+
+  def get_arg
+    CommandLine::OptionParser::GET_ARGS
+  end
+  alias :get_args :get_arg
+
+  def append_arg
+    CommandLine::OptionParser::GET_ARG_ARRAY
+  end
+
+  def self.run
+    @@app.new.main if ($0 == @@appname)
+    rescue => err
+      puts "ERROR: #{err}"
+      exit(-1)
+  end
+
+  def self.inherited(klass)
+    @@appname = caller[0][/.*:/][0..-2]
+    @@app = klass
+    at_exit { @@app.run }
+  end
+
+  def main
+    #raise(MissingMainError, "Method #main must be defined in class #{@@app}.")
+    @@app.class_eval %{ def main; end }
+  end
+
+  def _help
+     {
+       :names           => %w(--help -h),
+       :arg_arity       => [0,0],
+       :opt_description => "Displays help page.",
+       :arg_description => "",
+       :opt_found       => lambda { puts man; exit },
+       :opt_not_found   => false
+     }
+  end
+
+  def _verbose
+     {
+       :names           => %w(--verbose -v),
+       :arg_arity       => [0,0],
+       :opt_description => "Sets verbosity level. Subsequent "+
+                           "flags increase verbosity level",
+       :arg_description => "",
+       :opt_found       => lambda { @verbose ||= -1; @verbose += 1 },
+       :opt_not_found   => nil
+     }
+  end
+
+  def _version
+     {
+       :names           => %w(--version -V),
+       :arg_arity       => [0,0],
+       :opt_description => "Displays application version.",
+       :arg_description => "",
+       :opt_found       => lambda { 
+                             begin 
+                               version 
+                             rescue 
+                               puts "No version specified" 
+                             end; 
+                             exit 
+                           },
+       :opt_not_found   => nil
+     }
+  end
+
+  def _debug
+     {
+       :names           => %w(--debug -d),
+       :arg_arity       => [0,0],
+       :opt_description => "Sets debug to true.",
+       :arg_description => "",
+       :opt_found       => lambda { $DEBUG = true }
+     }
+  end
+end#class Application
+end#module CommandLine
+

data/lib/commandline/optionparser.rb

@@ -0,0 +1,16 @@
+#  $Id$
+#  $Source$
+#
+#  Author: Jim Freeze
+#  Copyright (c) 2005
+#
+# =DESCRIPTION
+# Loader
+#
+# =Revision History
+#  Jim.Freeze 2005/06/14 Birthday
+#
+
+require 'commandline/optionparser/option'
+require 'commandline/optionparser/optionparser'
+require 'commandline/optionparser/optiondata'

data/lib/commandline/optionparser/option.rb

@@ -0,0 +1,180 @@
+#  $Id$
+#  $Source$
+#
+#  Author: Jim Freeze
+#  Copyright (c) 2005 Jim Freeze
+#
+# =DESCRIPTION
+# A very flexible commandline parser
+#
+# =Revision History
+#  Jim.Freeze 04/01/2005 Birthday
+#
+
+module CommandLine
+
+class Option
+  class OptionError < StandardError; end
+  class InvalidOptionNameError < OptionError; end
+  class InvalidArgumentError < OptionError; end
+  class MissingOptionNameError < OptionError; end
+  class InvalidArgumentArityError < OptionError; end
+  class MissingPropertyError < OptionError; end
+  class InvalidPropertyError < OptionError; end
+  class InvalidConstructionError < OptionError; end
+
+  attr_accessor :posix
+
+  #
+  GENERAL_OPT_EQ_ARG_RE  = /^(-{1,2}[a-zA-Z]+[-_a-zA-Z0-9]*)=(.*)$/  # :nodoc:
+  GNU_OPT_EQ_ARG_RE      = /^(--[a-zA-Z]+[-_a-zA-Z0-9]*)=(.*)$/
+  #OPTION_RE              = /^-{1,2}([a-zA-Z]+\w*)(.*)/
+  #UNIX_OPT_EQ_ARG_RE     = /^(-[a-zA-Z])=(.*)$/
+  #UNIX_OPT_EQorSP_ARG_RE = /^(-[a-zA-Z])(=|\s+)(.*)$/
+
+  POSIX_OPTION_RE     = /^-[a-zA-Z]?$/
+  # need to change this to support - and --
+  NON_POSIX_OPTION_RE = /^(-|-{1,2}[a-zA-Z_]+[-_a-zA-Z0-9]*)/
+
+  PROPERTIES = [ :arg_arity, :opt_description, :arg_description,
+                 :opt_found, :opt_not_found, :posix
+               ]
+
+  FLAG_BASE_OPTS = {
+    :arg_arity       => [0,0],
+#    :opt_description => nil,
+    :arg_description => "",
+    :opt_found       => true,
+    :opt_not_found   => false
+  }
+
+  # You get these without asking for them
+  DEFAULT_OPTS = {
+    :arg_arity       => [1,1],
+    :opt_description => "",
+    :arg_description => "",
+    :opt_found       => true,
+    :opt_not_found   => false
+  }
+
+  #
+  # Option.new(:flag, :posix => true, :names => %w(--opt))
+  #
+  # TODO: Should we test and raise key is not one of :names, opt_description, ...
+  # This will prevent typos. Can users add properties to an Option that are their own?
+  def initialize(*all)
+    @posix = false
+
+    raise(MissingPropertyError,
+      "No properties specified for new #{self.class}.") if all.empty?
+
+    until Hash === all[0]
+      case (prop = all.shift)
+      when :flag then @flag = true
+      when :posix then @posix = true
+      else 
+        raise(InvalidPropertyError, "Unknown option setting '#{prop}'.")
+      end
+    end
+
+    type = @flag.nil? ? :default : :flag
+    merge_hash = 
+      case type
+      when :flag then FLAG_BASE_OPTS
+      when :default then DEFAULT_OPTS
+      else raise(InvalidConstructionError, 
+        "Invalid arguments to Option.new. Must be a property hash with "+
+        "keys [:names, :arg_arity, :opt_description, :arg_description, "+
+        ":opt_found, :opt_not_found] or "+
+        "an option type [:flag, :default].")
+      end
+
+    @properties = {}.merge(merge_hash)
+    all.each { |properties|
+      raise(InvalidPropertyError, 
+        "Don't understand argument of type '#{properties.class}' => "+
+            "#{properties.inspect} passed to #{self.class}.new. Looking "+
+            "for type Hash.") unless properties.kind_of?(Hash)
+
+      @properties.merge!(properties)
+    }
+    
+    @properties[:names] = [@properties[:names]] unless 
+      @properties[:names].kind_of?(Array)
+
+    arg_arity = @properties[:arg_arity]
+    @properties[:arg_arity] = [arg_arity, arg_arity] unless 
+      arg_arity.kind_of?(Array)
+
+    raise "Invalid value for arg_arity '#{arg_arity}'." unless 
+      arg_arity.kind_of?(Array) || arg_arity.kind_of?(Fixnum)
+
+    raise(InvalidArgumentArityError,
+      "Conflicting value given to new option: :flag "+
+      "and :arg_arity = #{@properties[:arg_arity].inspect}.") if 
+        :flag == type && [0,0] != @properties[:arg_arity]
+
+    names = @properties[:names]
+    raise(MissingOptionNameError, 
+      "Attempt to create an Option without :names defined.") if 
+      names.nil? || names.empty?
+
+    names.each { |name| check_option_name(name) }
+    validate_arity @properties[:arg_arity]
+
+    create_opt_description if :flag == type
+  end
+
+  def create_opt_description
+    return if @properties.has_key?(:opt_description)
+    word = @properties[:names].grep(/^--\w.+/)
+    if word.empty?
+      @properties[:opt_description] = ""
+    else
+      @properties[:opt_description] = "Sets #{word.first[2..-1]} to true."
+    end
+  end
+
+  def check_option_name(name)
+    raise(InvalidOptionNameError, 
+      "Option name '#{name}' contains invalid space.") if /\s+/.match(name)
+
+    if @posix
+      raise(InvalidOptionNameError, 
+        "Option name '#{name}' is invalid.") unless POSIX_OPTION_RE.match(name)
+    else
+      raise(InvalidOptionNameError, 
+        "Option name '#{name}' is invalid.") unless NON_POSIX_OPTION_RE.match(name)
+    end
+  end
+
+  def validate_arity(arity)
+  raise ":arg_arity is nil" if arity.nil?
+    min, max = *arity
+
+    raise(InvalidArgumentArityError, "Minimum argument arity '#{min}' must be "+
+      "greater than or equal to 0.") unless min >= 0
+    raise(InvalidArgumentArityError, "Maximum argument arity '#{max}' must be "+
+      "greater than or equal to -1.") if max < -1
+    raise(InvalidArgumentArityError, "Maximum argument arity '#{max}' must be "+
+      "greater than minimum arg_arity '#{min}'.") if max < min && max != -1
+    if @posix
+      raise(InvalidArgumentArityError, "Posix options only support :arg_arity "+
+        "of [0,0] or [1,1].") unless ([0,0] == arity) || ([1,1] == arity)
+    end
+  end
+
+  def method_missing(sym, *args)
+    raise "Unknown property '#{sym}' for option 
+      #{@properties[:names].inspect unless @properties[:names].nil?}." unless 
+        @properties.has_key?(sym) || PROPERTIES.include?(sym)
+    @properties[sym, *args]
+  end
+
+  def to_hash
+    Marshal.load(Marshal.dump(@properties))
+  end
+
+end#class Option
+
+end#module CommandLine