clio 0.0.1

data/admin/config/reap.yaml

@@ -0,0 +1,30 @@
+---
+
+syntax: {}
+
+autotools: ~
+
+testunit: {}
+
+basicstats: {}
+
+notes: {}
+
+rdoc:
+  template: jamis
+  inline: true
+
+ridoc: {}
+
+gem:
+  exclude:
+    - doc/rdoc
+    - doc/ri
+
+rubyforge:
+  unixname: clio
+  groupid: 6913
+#  publishmap:
+#    admin/web: .
+#    doc/rdoc: rdoc
+

data/admin/depot/commandline.rb

@@ -0,0 +1,219 @@
+require 'shellwords'
+require 'facets/kernel/object_class'
+
+module Clio
+  ### = Commandline
+  ###
+  ### What a strange thing is the Clio Commandline.
+  ### An entity unknown until put upon. 
+  class Commandline
+    instance_methods.each{ |m| private m if m !~ /^(__|instance_|object_|send$|inspect$)/ }
+  
+    ### Splits a raw command line into two smaller
+    ### ones. The first including only options
+    ### upto the first non-option argument. This
+    ### makes quick work of separating subcommands
+    ### from a main command.
+    # TODO: Rename this method.
+    def self.gerrymander(argv=ARGV)
+      if String===argv
+        argv = Shellwords.shellwords(argv)
+      end
+      sub = argv.find{ |x| x !~ /^[-]/ }
+      idx = argv.index(sub)
+      opts = argv[0...idx]
+      scmd = argv[idx..-1]
+      return new(opts), new(scmd)
+    end
+
+    ### Define an option attibute.
+    ### While commandline can be used without
+    ### pre-declartion of support options
+    ### doding so allows for creating option
+    ### aliases. Eg. --quiet and -q.
+    def self.attr(name, *aliases)
+      name = name.to_s
+      if name =~ /\?$/
+        name = name.chomp('?')
+        #attr_writer name
+        module_eval "def #{name}?; self[:#{name}] ; end"
+        aliases.each do |alt|
+          alt = alt.to_s.chomp('?')
+          alias_method("#{alt}?", "#{name}?")
+          #alias_method("#{alt}=", "#{name}=")
+        end
+      else
+        attr_reader(name)
+        aliases.each do |alt|
+          #alt = alt.to_s.chomp('?')  # TODO: raise error ?
+          alias_method("#{alt}" , "#{name}")
+          #alias_method("#{alt}=", "#{name}=")
+        end
+      end
+    end
+
+    ### Returns a list of all pre-defined options.
+    ### It does this by seaching class ancestry
+    ### for instance_methods until it reaches the
+    ### Commandline base class.
+    ### TODO: Rename #runmodes method.
+    ### TODO: Robust enough? Use an Inheritor instead?
+    def self.runmodes
+      index   = ancestors.index(::Clio::Commandline)
+      options = ancestors[0...index].inject([]) do |opts, ancestor|
+        opts | ancestor.instance_methods(false)
+      end
+      options.reject{ |o| o =~ /\=$/ }
+      options.collect{ |o| o.to_sym }
+    end
+
+  public
+
+    ### This method provides the centralized means of accessing
+    ### the options and arguments of the commandline.
+    def [](index)
+      case index
+      when Integer
+        @arguments[index] ||= (
+          args = @argv.select{ |e| e !~ /^-/ }
+          val = args[index]
+          @argv.delete(args[index])
+          val
+        )
+      else
+        index = index.to_s
+        name  = index.chomp('?')
+        key   = name.to_sym
+        return @options[key] if @options.key?(key)
+
+        @options[key] = if index =~ /\?$/
+          name.size == 1 ? option_letter_flag(name)  : option_flag(name)
+        else
+          name.size == 1 ? option_letter_value(name) : option_value(name)
+        end
+      end
+    end
+
+    ### Access to the underlying commandline "ARGV".
+    ### This will show what is yet to be processed.
+    def instance_delegate ; @argv ; end
+
+  private
+
+    ### New Commandline. Takse a single argument
+    ### which can be a "shell" string, or an array
+    ### of shell arguments, like ARGV. If none
+    ### is given it defaults to ARGV.
+    def initialize(argv=ARGV)
+      case argv
+      when String
+        @argv = Shellwords.shellwords(argv)
+      else
+        @argv = argv.dup
+      end
+      @arguments = []
+      @options   = {}
+
+      object_class.runmodes.each do |name|
+        self[name]
+      end
+    end
+
+    ###
+    #def initialize(argv=ARGV)
+    #  if Hash===argv
+    #    argv.each{ |k,v| send("#{k}=", v) }
+    #  else
+    #    self.class.runmodes.each do |name|
+    #      option(name)
+    #    end
+    #  end
+    #end
+
+    ### Routes to #[].
+    def method_missing(name, *args)
+      super unless args.empty?
+      case name.to_s
+      when /\=$/
+        super
+      else
+        self[name]
+      end
+    end
+
+    ### Helper method. This can be replaceb by
+    ### String#index when it supports blocks.
+    ### Err.. when will that be Matz?
+    def index(array, &block)
+      find = array.find(&block)
+      array.index(find)
+    end
+
+    ### Parse a flag option.
+    def option_flag(name)
+p name
+      o = "--#{name}"
+      i = index(@argv){ |e| e =~ /^#{o}[=]?/ }
+      return false unless i
+      raise ArgumentError if @argv[i] =~ /=/
+      @argv[i] = nil
+      return true
+    end
+
+    ### Parse a value option.
+    def option_value(name)
+      o = "--#{name}"
+      i = index(@argv){ |e| e =~ /^#{o}[=]?/ }
+      return false unless i
+
+      if @argv[i] =~ /=/
+        key, val = *@argv[i].split('=')
+        argv[i] = nil
+      else
+        case @argv[i+1]
+        when nil, /^-/
+          raise ArgumentError
+        else
+          key = @argv[i]
+          val = @argv[i+1]
+          @argv[i,2] = nil
+        end
+      end
+      return val
+    end
+
+    ### Parse a single letter flag option.
+    def option_letter_flag(letter)
+      o = letter
+      i = index(@argv){ |e| e =~ /[-]\w+(#{o})\w*$/ }
+      if i
+        @argv[i] = @argv[i].gsub(o,'')
+        true
+      end
+      false
+    end
+
+    ### Parse a single letter value option.
+    def option_letter_value(letter)
+      o = letter
+      i = index(@argv){ |e| e =~ /#{o}(\=|$)/ }
+      return nil unless i
+      if @argv[i] =~ /=/
+        rest, val = argv[i].split('=')
+        @argv[i] = rest
+      else
+        case @argv[i+1]
+        when nil, /^-/
+          raise ArgumentError
+        else
+          val = argv[i+1]
+          @argv[i]   = argv[i].gsub(o,'')
+          @argv[i+1] = nil
+        end
+      end
+      return val    
+    end
+
+  end
+end
+

data/admin/depot/multicommand.rb

@@ -0,0 +1,403 @@
+warn "MultiCommand is under construction!"
+exit 0
+
+# = Clio::MultiCommand
+#
+# Base class with metaclass DSL for creating
+# well defined, static command line interfaces.
+#
+# == Authors
+#
+# * Trans
+#
+# == Copying
+#
+# Copyright (c) 2005,2008 Thomas Sawyer
+# Lesser GNU Public License
+#
+# This module is free software. You may use, modify, and/or
+# redistribute this software under the same terms as Ruby.
+#
+# This program is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied
+# warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+# PURPOSE.
+
+begin
+  require 'annotatable'
+rescue LoadError => e
+  $stderr << "ERROR: Clio Multicommand depends on 'annotatable'."
+  exit 0
+end
+
+#require 'facets/argvector'
+require 'clio/errors'
+
+module Clio
+
+  # Here is an example of usage:
+  #
+  #   # General Options
+  #
+  #   # Build Subcommand
+  #
+  #   class MyMultiCommand < Clio::MultiCommand
+  #
+  #     cmd "save to file"
+  #
+  #     opt :file do
+  #       desc "very useful option"
+  #       type :path,
+  #       flag :f, 
+  #     end
+  #
+  #     def save(args, opts)
+  #
+  #     end
+  #
+  #     def fallback(opts)
+  #       # if no subcommand
+  #     end
+  #   end
+  #
+  #   MyMultiCommand.start
+  #
+  class MultiCommand
+
+    include Annotatable
+
+    annotation :cmd
+
+    annotation :opt
+
+    def self.method_added(name)
+      anns = self.class.annotations(name)
+      desc = anns[:cmd]
+        @options << Option.new(name, @_desc, @_opts)
+        @_opt = nil
+      end
+    end
+
+
+
+
+
+    # Include this in your dispatch command if you want
+    # all options to be traeted the same.
+
+    module UniversalOptions
+    end
+
+    #
+
+    def self.option_arity(arity_hash=nil)
+      if arity_hash
+        (@option_arity ||= {}).merge!(arity_hash)
+      end
+      @option_arity
+    end
+
+    #
+
+    def self.start(line=nil)
+      cargs = Argvector.new(line || ARGV, option_arity)
+      pre = cargs.preoptions
+
+      if instance_method(:call).arity == 0 #is_a?(SingleCommand)
+        args, opts = *cargs.parameters
+        new(args, opts).call
+      else
+        subc, args, opts = *cargs.subcommand
+        if self < UniversalOptions
+          new(pre, opts).call(subc, args, opts)
+        else
+          new(pre).call(subc, args, opts)
+        end
+      end
+    end
+  
+    # Command Arguments (for single commands).
+
+    attr :arguments
+
+    # Command options. For dispatch commands these are the pre-options.
+
+    attr :options
+
+    # For dispatchers, this is a convenience method for creating subcommands.
+
+    def self.subcommand(name, command_class, options=nil)
+      options ||= {}
+      if options[:no_merge]
+        file, line = __FILE__, __LINE__+1
+        code = %{
+          def #{name}(args, opts)
+            #{command_class}.new(args, opts).call
+          end
+        }
+      else
+        file, line = __FILE__, __LINE__+1
+        code = %{
+          def #{name}(args, opts)
+            opts.merge(options)
+            #{command_class}.new(args, opts).call
+          end
+        }
+      end
+      class_eval(code, file, line)
+    end
+
+    private
+
+    #
+
+    def initialize(*args)
+      @arguments = []
+      @options   = {}
+
+      opts, args = *args.partition{ |e| Hash===e }
+      #TEST("options should all be hashes"){ ! opts.all?{ |e| Hash===e }
+      initialize_arguments(*args)
+      initialize_options(*opts)
+    end
+
+    #
+
+    def initialize_arguments(*arguments)
+      @arguments.concat(arguments)
+    end
+
+    #
+
+    def initialize_options(*options)
+      options = options.inject{ |h,o| h.merge(o) }
+      begin
+        opt, val = nil, nil
+        options.each do |opt, val|
+          opt = opt.gsub('-','_')
+          send("#{opt}=", val)
+        end
+      rescue NoMethodError
+        option_missing(opt, val)
+      end
+      @options.update(options)
+    end
+
+    public
+
+    # For a single command (ie. a subcommand) override #call with arity=0.
+
+    def call(cmd=nil, *args)
+      opts = Hash==args.last ? args.pop : {}
+      #TEST("options should all be hashes"){ ! opts.all?{ |e| Hash===e }
+      #cmd = :default if cmd.nil?
+      if cmd.nil?
+        default
+      else
+        begin
+          # FIXME: rename call to [] ?
+          raise NameError if cmd == 'call'
+          raise NameError unless commands.include?(cmd.to_sym)
+          subcommand = method(cmd)
+          parameters = [args, opts]
+        rescue NameError
+          subcommand = method(:command_missing)
+          parameters = [cmd, args, opts]
+        end
+        if subcommand.arity < 0
+          subcommand.call(*parameters[0..subcommand.arity])
+        else
+          subcommand.call(*parameters[0,subcommand.arity])
+        end
+      end
+    end
+
+    # Display help message.
+    # The one provided is just a very limited dummy routine.
+
+#    def help
+#      puts "USAGE #{File.basename($0)} [options]"
+#      puts "\nOptions:"
+#      options = self.class.instance_methods(false)
+#      options = options - Command.instance_methods(true)
+#      options = options.select{ |m| m.to_s =~ /=$/ }
+#      options.each do |opt|
+#        puts "  --#{opt.to_s.chomp('=')}"
+#      end
+#    end
+
+    private
+
+    # Override default to provide non-subcommand functionality.
+
+    def default; end
+
+    # TODO: Add "if no setter method".
+    def commands
+      @_commands ||= (
+        cmds = self.class.instance_methods(true) - Command.instance_methods(true)
+        cmds.select{ |c| c !~ /\W/ }
+        cmds.collect{ |c| c.to_sym }
+      )     
+    end
+
+    #
+
+    def command_missing(cmd, args, opt)
+      raise NoCommandError.new(cmd, args << opt)
+    end
+
+    #
+
+    def option_missing(opt, arg=nil)
+      raise NoOptionError.new(opt)
+    end
+
+  end
+
+  # Temporary backward compatability.
+  MasterCommand = Command
+
+end
+
+
+module Console #:nodoc:
+  # For backward compatibility.
+  Command = CLI::Command
+end
+
+
+# SCRAP CODE FOR REFERENCE TO POSSIBLE ADD FUTURE FEATURES
+
+=begin
+
+  # We include a module here so you can define your own help
+  # command and call #super to utilize this one.
+
+  module Help
+
+    def help
+      opts = help_options
+      s = ""
+      s << "#{File.basename($0)}\n\n"
+      unless opts.empty?
+        s << "OPTIONS\n"
+        s << help_options
+        s << "\n"
+      end
+      s << "COMMANDS\n"
+      s << help_commands
+      puts s
+    end
+
+    private
+
+    def help_commands
+      help = self.class.help
+      bufs = help.keys.collect{ |a| a.to_s.size }.max + 3
+      lines = []
+      help.each { |cmd, str|
+        cmd = cmd.to_s
+        if cmd !~ /^_/
+          lines << "  " + cmd + (" " * (bufs - cmd.size)) + str
+        end
+      }
+      lines.join("\n")
+    end
+
+    def help_options
+      help = self.class.help
+      bufs = help.keys.collect{ |a| a.to_s.size }.max + 3
+      lines = []
+      help.each { |cmd, str|
+        cmd = cmd.to_s
+        if cmd =~ /^_/
+          lines << "  " + cmd.gsub(/_/,'-') + (" " * (bufs - cmd.size)) + str
+        end
+      }
+      lines.join("\n")
+    end
+
+    module ClassMethods
+
+      def help( str=nil )
+        return (@help ||= {}) unless str
+        @current_help = str
+      end
+
+      def method_added( meth )
+        if @current_help
+          @help ||= {}
+          @help[meth] = @current_help
+          @current_help = nil
+        end
+      end
+
+    end
+
+  end
+
+  include Help
+  extend Help::ClassMethods
+
+=end
+
+=begin
+
+   # Provides a very basic usage help string.
+    #
+    # TODO Add support for __options.
+    def usage
+      str = []
+      public_methods(false).sort.each do |meth|
+        meth = meth.to_s
+        case meth
+        when /^_/
+          opt = meth.sub(/^_+/, '')
+          meth = method(meth)
+          if meth.arity == 0
+            str << (opt.size > 1 ? "[--#{opt}]" : "[-#{opt}]")
+          elsif meth.arity == 1
+            str << (opt.size > 1 ? "[--#{opt} value]" : "[-#{opt} value]")
+          elsif meth.arity > 0
+            v = []; meth.arity.times{ |i| v << 'value' + (i + 1).to_s }
+            str << (opt.size > 1 ? "[--#{opt} #{v.join(' ')}]" : "[-#{opt} #{v.join(' ')}]")
+          else
+            str << (opt.size > 1 ? "[--#{opt} *values]" : "[-#{opt} *values]")
+          end
+        when /=$/
+          opt = meth.chomp('=')
+          str << (opt.size > 1 ? "[--#{opt} value]" : "[-#{opt} value]")
+        when /!$/
+          opt = meth.chomp('!')
+          str << (opt.size > 1 ? "[--#{opt}]" : "[-#{opt}]")
+        end
+      end
+      return str.join(" ")
+    end
+
+    #
+
+    def self.usage_class(usage)
+      c = Class.new(self)
+      argv = Shellwords.shellwords(usage)
+      argv.each_with_index do |name, i|
+        if name =~ /^-/
+          if argv[i+1] =~ /^[(.*?)]/
+            c.class_eval %{
+              attr_accessor :#{name}
+            }
+          else
+            c.class_eval %{
+              attr_reader :#{name}
+              def #{name}! ; @#{name} = true ; end
+            }
+          end
+        end
+      end
+      return c
+    end
+
+  end
+
+=end