facets 1.8.54 → 2.0.0

data/lib/more/facets/command.rb

@@ -0,0 +1,262 @@
+# TITLE:
+#
+#   Command
+#
+# COPYRIGHT:
+#
+#   Copyright (c) 2005 Thomas Sawyer
+#
+# LICENSE:
+#
+#   Ruby 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.
+#
+# AUTHORS:
+#   - Thomas Sawyer
+#   - Tyler Rick
+#
+# TODOs:
+#   - Add help/documentation features.
+#   - Problem wiht exit -1 when testing. See IMPORTANT!!! remark below.
+
+require 'shellwords'
+require 'facets/command_options'
+#require 'facets/annotations' # for help ?
+
+module Console
+
+  # Base command class.
+  #
+  #   class MyCommand < Command
+  #
+  #     class JumpOptions < Command::Options
+  #       attr_accessor :height
+  #     end
+  #
+  #     help :jump, "this is the jump command"
+  #
+  #     opts :jump, JumpOptions
+  #
+  #     def jump
+  #       puts "jump #{options.height} feet!"
+  #     end
+  #   end
+  #
+  # A little more conveniently:
+  #
+  #   class MyCommand < Command
+  #
+  #     help :jump, "this is the jump command"
+  #
+  #     opts :jump do
+  #       attr_accessor :height
+  #     end
+  #
+  #     def jump
+  #       puts "jump #{options.height} feet!"
+  #     end
+  #   end
+  #
+
+  class Command
+
+    # Command Syntax DSL
+
+    module Syntax
+
+      # Starts the command execution.
+      def execute( *args )
+        cmd = new()
+        #cmd.instance_variable_set("@global_options",global_options)
+        cmd.execute( *args )
+      end
+      alias_method :start, :execute
+
+      # Change the option mode.
+      def global_option( *names )
+        names.each{ |name| global_options << name.to_sym }
+      end
+      alias_method :global_options, :global_option
+
+      # Options.
+
+      def options(name, klass=nil, &block)
+        raise ArgumentError if klass && block
+        if block
+          command_options[name.to_sym] = Class.new(CommandOptions, &block)
+        else
+          command_options[name.to_sym] = klass
+        end
+      end
+      alias_method :opts, :options
+      alias_method :opt, :options
+
+      #
+
+      def command_options
+        @_command_options ||= {}
+      end
+
+      #
+
+      def global_options
+        @_global_options ||= []
+      end
+    end
+
+    extend Syntax
+
+    #def initialize #(global_options=nil)
+    #  #@global_options = global_options || []
+    #end
+
+    #
+
+    def execute(line)
+      argv = line
+
+      g_opts = CommandOptions.new(self)
+      g_keys = self.class.global_options
+
+      # Deal with global options.
+      if g_keys && ! g_keys.empty?
+        argv = g_opts.parse(argv, :only => g_keys)
+      end
+
+      # Sole main command or has subcommands?
+      if respond_to?(:main)
+        argv = g_opts.parse(argv, :pass => true)
+        cmd = :main
+      else
+        argv = g_opts.parse(argv, :stop => true)
+        cmd = argv.find{ |s| s !~ /^-/ }
+              argv.delete_at(argv.index(cmd)) if cmd
+        cmd = :default unless cmd
+        cmd = cmd.to_sym
+      end
+
+      keys = self.class.command_options
+
+      if keys.key?(cmd)
+        opts = keys[cmd].new
+        argv = opts.parse(argv)
+      end
+
+      argv = g_opts.parse_missing(argv)
+
+      call(cmd, argv, opts)
+    end
+
+    #
+
+    def call(subcmd, argv, opts)
+      @options = opts  # should we use this it fill in instance vars?
+
+      # This is a little tricky. The method has to be defined by a subclass.
+      if self.respond_to?(subcmd) and not Console::Command.public_instance_methods.include?(subcmd.to_s)
+        puts "# call: #{subcmd}(*#{argv.inspect})" if $debug
+        __send__(subcmd, *argv)
+      else
+        begin
+          puts "# call: method_missing(#{subcmd.inspect}, #{argv.inspect})" if $debug
+          method_missing(subcmd.to_sym, *argv)
+        rescue NoMethodError => e
+          #if self.private_methods.include?( "no_command_error" )
+          #  no_command_error( *args )
+          #else
+            $stderr << "Unrecognized subcommand -- #{subcmd}\n"
+            exit -1
+          #end
+        end
+      end
+    end
+
+    #def global_options
+    #  self.class.global_options
+    #end
+
+    def option_missing(opt, arg=nil)
+      raise InvalidOptionError.new(opt)
+    end
+
+  end
+
+=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
+
+end

data/lib/more/facets/command_options.rb

@@ -0,0 +1,328 @@
+# TITLE:
+#
+#   Command Options
+#
+# COPYRIGHT:
+#
+#   Copyright (c) 2005 7rans, Tyler Rick
+#
+#   Ruby 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.
+#
+# AUTHORS:
+#
+#   - 7rans
+#   - Tyler Rick
+#
+# TODOs:
+#
+#   - Add help/documentation features.
+
+require 'shellwords'
+#require 'facets/arguments'
+
+# = Console::CommandOptions
+#
+# CommandOptions provides the basis for Command to Object Mapping (COM).
+# It is an commandline options parser that uses method definitions
+# as means of interprting command arguments.
+#
+# == Synopsis
+#
+# Let's make an executable called 'mycmd'.
+#
+#   #!/usr/bin/env ruby
+#
+#   require 'facets/command_options'
+#
+#   class MyOptions < CommandOptions
+#     attr_accessor :file
+#
+#     def v!
+#       @verbose = true
+#     end
+#   end
+#
+#   opts = MyOptions.parse("-v --file hello.rb")
+#
+#   opts.verbose  #=> true
+#   opts.file     #=> "hello.rb"
+#
+#--
+# == Global Options
+#
+# You can define <i>global options</i> which are options that will be
+# processed no matter where they occur in the command line. In the above
+# examples only the options occuring before the subcommand are processed
+# globally. Anything occuring after the subcommand belonds strictly to
+# the subcommand. For instance, if we had added the following to the above
+# example:
+#
+#   global_option :_v
+#
+# Then -v could appear anywhere in the command line, even on the end,
+# and still work as expected.
+#
+#   % mycmd jump -h 3 -v
+#++
+#
+# == Missing Options
+#
+# You can use #option_missing to catch any options that are not explicility
+# defined.
+#
+# The method signature should look like:
+#
+#   option_missing(option_name, args)
+#
+# Example:
+#   def option_missing(option_name, args)
+#     p args if $debug
+#     case option_name
+#       when 'p'
+#         @a = args[0].to_i
+#         @b = args[1].to_i
+#         2
+#       else
+#         raise InvalidOptionError(option_name, args)
+#     end
+#   end
+#
+# Its return value should be the effective "arity" of that options -- that is,
+# how many arguments it consumed ("-p a b", for example, would consume 2 args:
+# "a" and "b"). An arity of 1 is assumed if nil or false is returned.
+
+#module Console
+
+  class CommandOptions
+
+    def self.parse(*line_and_options)
+      o = new
+      o.parse(*line_and_options)
+      o
+    end
+
+    def initialize(delegate=nil)
+      @__self__ = delegate || self
+    end
+
+    # Parse line for options in the context self.
+    #
+    # Options:
+    #
+    #   :pass => true || false
+    #
+    # Setting this to true prevents the parse_missing routine from running.
+    #
+    #   :only => [ global options, ... ]
+    #
+    # When processing global options, we only want to parse selected options.
+    # This also set +pass+ to true.
+    #
+    #   :stop => true || false
+    #
+    # If we are parsing options for the *main* command and we are allowing
+    # subcommands, then we want to stop as soon as we get to the first non-option,
+    # because that non-option will be the name of our subcommand and all options that
+    # follow should be parsed later when we handle the subcommand.
+    # This also set +pass+ to true.
+
+    def parse(*line_and_options)
+      __self__ = @__self__
+
+      if Hash === line_and_options.last
+        options = line_and_options.pop
+        line    = line_and_options.first
+      else
+        options = {}
+        line    = line_and_options.first
+      end
+
+      case line
+      when String
+        argv = Shellwords.shellwords(line)
+      when Array
+        argv = line.dup
+      else
+        argv = ARGV.dup
+      end
+
+      only = options[:only]                      # only parse these options
+      stop = options[:stop]                      # stop at first non-option
+      pass = options[:pass] || only || stop      # don't run options_missing
+
+      if $debug
+        puts(only ? "\nGlobal parsing..." : "\nParsing...")
+      end
+
+      puts "# line: #{argv.inspect}" if $debug
+
+      # Split single letter option groupings into separate options.
+      # ie. -xyz => -x -y -z
+      argv = argv.collect { |arg|
+        if md = /^-(\w{2,})/.match( arg )
+          md[1].split(//).collect { |c| "-#{c}" }
+        else
+          arg
+        end
+      }.flatten
+
+      index = 0
+
+      until index >= argv.size
+        arg = argv.at(index)
+        break if arg == '--'  # POSIX compliance
+        if arg[0,1] == '-'
+          puts "# option: #{arg}" if $debug
+          #opt  = Option.new(arg)
+          #name = opt.methodize
+          name = arg.sub(/^-{1,2}/,'')
+          skip = only && only.include?(name)
+          if __self__.respond_to?(name+'=')
+            puts "# method: #{name}=" if $debug
+            __self__.send(name+'=', *argv.slice(index+1, 1)) unless skip
+            argv.delete_at(index) # Get rid of the *name* of the option
+            argv.delete_at(index) # Get rid of the *value* of the option
+          elsif __self__.respond_to?(name+'!')
+            puts "# method: #{name}!" if $debug
+            __self__.send(name+'!') unless skip
+            argv.delete_at(index) # Get rid of the *name* of the option
+          else
+             index += 1
+          end
+        else
+          index += 1
+          break if stop
+        end
+      end
+      # parse missing ?
+      argv = parse_missing(argv) unless pass
+      # return the remaining argv
+      puts "# return: #{argv.inspect}" if $debug
+      return argv
+    end
+
+    #
+
+    def parse_missing(argv)
+      argv.each_with_index do |a,i|
+        if a =~ /^-/
+          kept = @__self__.option_missing(a, *argv[i+1,1])
+          argv.delete_at(i) if kept  # delete if value kept
+          argv.delete_at(i)          # delete option
+        end
+      end
+      return argv
+    end
+
+    #
+
+    def option_missing(opt, arg=nil)
+      raise InvalidOptionError.new(opt)
+      #  #$stderr << "Unknown option '#{arg}'.\n"
+      #  #exit -1
+    end
+
+    #
+
+    def to_h
+      #writers = public_methods.sellect{ |m| m =~ /=$/ }
+      instance_variables.inject({}) do |h, v|
+        h[v[1,-1]] = instance_variable_get(v); h
+      end
+    end
+
+    # Provides a basic usage help string.
+
+    def usage
+      str = []
+      public_methods(false).each do |meth|
+        meth = meth.to_s
+        case meth
+        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
+
+#     # Single Option
+#
+#     class Option < String
+#
+#       def initialize(option)
+#         @flag = option
+#         @long = (/^--/ =~ option)
+#         super(option.sub(/^-{1,2}/,''))
+#       end
+#
+#       def long?
+#         @long
+#       end
+#
+#       def short?
+#         !@long
+#       end
+#
+#       #def demethodize
+#       #  sub('__','--').sub('_','-')
+#       #end
+#
+#       def methodize
+#         @flag.sub(/^-{1,2}/,'')
+#       end
+#
+#     end
+
+  end
+
+  # For CommandOptions, but defined external to it, so
+  # that it is easy to access from user defined commands.
+  # (This lookup issue should be fixed in Ruby 1.9+, and then
+  # the class can be moved back into Command namespace.)
+
+  class InvalidOptionError < StandardError
+    def initialize(option_name)
+      @option_name = option_name
+    end
+    def message
+      "Unknown option '#{@option_name}'."
+    end
+  end
+
+#end
+
+