jls-clamp 0.3.1

data/lib/clamp/command.rb

@@ -0,0 +1,142 @@
+require 'clamp/errors'
+require 'clamp/help'
+require 'clamp/option/declaration'
+require 'clamp/option/parsing'
+require 'clamp/parameter/declaration'
+require 'clamp/parameter/parsing'
+require 'clamp/subcommand/declaration'
+require 'clamp/subcommand/parsing'
+
+module Clamp
+
+  # {Command} models a shell command.  Each command invocation is a new object.
+  # Command options and parameters are represented as attributes
+  # (see {Command::Declaration}).
+  #
+  # The main entry-point is {#run}, which uses {#parse} to populate attributes based
+  # on an array of command-line arguments, then calls {#execute} (which you provide)
+  # to make it go.
+  #
+  class Command
+
+    # Create a command execution.
+    #
+    # @param [String] invocation_path the path used to invoke the command
+    # @param [Hash] context additional data the command may need
+    #
+    def initialize(invocation_path, context = {})
+      @invocation_path = invocation_path
+      @context = context
+    end
+
+    # @return [String] the path used to invoke this command
+    #
+    attr_reader :invocation_path
+
+    # @return [Array<String>] unconsumed command-line arguments
+    #
+    def remaining_arguments
+      @remaining_arguments
+    end
+
+    # Parse command-line arguments.
+    #
+    # @param [Array<String>] arguments command-line arguments
+    # @return [Array<String>] unconsumed arguments
+    #
+    def parse(arguments)
+      @remaining_arguments = arguments.dup
+      parse_environment
+      parse_options
+      parse_parameters
+      parse_subcommand
+      handle_remaining_arguments
+    end
+
+    # Run the command, with the specified arguments.
+    #
+    # This calls {#parse} to process the command-line arguments,
+    # then delegates to {#execute}.
+    #
+    # @param [Array<String>] arguments command-line arguments
+    #
+    def run(arguments)
+      parse(arguments)
+      execute
+    end
+
+    # Execute the command (assuming that all options/parameters have been set).
+    #
+    # This method is designed to be overridden in sub-classes.
+    #
+    def execute
+      if @subcommand
+        @subcommand.execute
+      else
+        raise "you need to define #execute"
+      end
+    end
+
+    # @return [String] usage documentation for this command
+    #
+    def help
+      self.class.help(invocation_path)
+    end
+
+    include Clamp::Option::Parsing
+    include Clamp::Parameter::Parsing
+    include Clamp::Subcommand::Parsing
+
+    protected
+
+    attr_accessor :context
+
+    def handle_remaining_arguments
+      unless remaining_arguments.empty?
+        signal_usage_error "too many arguments"
+      end
+    end
+
+    private
+
+    def signal_usage_error(message)
+      e = UsageError.new(message, self)
+      e.set_backtrace(caller)
+      raise e
+    end
+
+    def request_help
+      raise HelpWanted, self
+    end
+
+    class << self
+
+      include Clamp::Option::Declaration
+      include Clamp::Parameter::Declaration
+      include Clamp::Subcommand::Declaration
+      include Help
+
+      # Create an instance of this command class, and run it.
+      #
+      # @param [String] invocation_path the path used to invoke the command
+      # @param [Array<String>] arguments command-line arguments
+      # @param [Hash] context additional data the command may need
+      #
+      def run(invocation_path = File.basename($0), arguments = ARGV, context = {})
+        begin
+          new(invocation_path, context).run(arguments)
+        rescue Clamp::UsageError => e
+          $stderr.puts "ERROR: #{e.message}"
+          $stderr.puts ""
+          $stderr.puts "See: '#{e.command.invocation_path} --help'"
+          exit(1)
+        rescue Clamp::HelpWanted => e
+          puts e.command.help
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/clamp/errors.rb

@@ -0,0 +1,26 @@
+module Clamp
+  
+  class Error < StandardError
+
+    def initialize(message, command)
+      super(message)
+      @command = command
+    end
+
+    attr_reader :command
+
+  end
+
+  # raise to signal incorrect command usage
+  class UsageError < Error; end
+
+  # raise to request usage help
+  class HelpWanted < Error
+
+    def initialize(command)
+      super("I need help", command)
+    end
+
+  end
+
+end

data/lib/clamp/help.rb

@@ -0,0 +1,100 @@
+require 'stringio'
+
+module Clamp
+
+  module Help
+
+    def usage(usage)
+      @declared_usage_descriptions ||= []
+      @declared_usage_descriptions << usage
+    end
+
+    attr_reader :declared_usage_descriptions
+
+    def description=(description)
+      @description = description.dup
+      if @description =~ /^\A\n*( +)/
+        indent = $1
+        @description.gsub!(/^#{indent}/, '')
+      end
+      @description.strip!
+    end
+
+    attr_reader :description
+
+    def derived_usage_description
+      parts = ["[OPTIONS]"]
+      parts += parameters.map { |a| a.name }
+      if has_subcommands?
+        parts << "SUBCOMMAND"
+        parts << "[ARGS] ..."
+      end
+      parts.join(" ")
+    end
+
+    def usage_descriptions
+      declared_usage_descriptions || [derived_usage_description]
+    end
+
+    def help(invocation_path)
+      help = Builder.new
+      help.add_usage(invocation_path, usage_descriptions)
+      help.add_description(description)
+      if has_parameters?
+        help.add_list("Parameters", parameters)
+      end
+      if has_subcommands?
+        help.add_list("Subcommands", recognised_subcommands)
+      end
+      help.add_list("Options", recognised_options)
+      help.string
+    end
+
+    class Builder
+
+      def initialize
+        @out = StringIO.new
+      end
+
+      def string
+        @out.string
+      end
+
+      def add_usage(invocation_path, usage_descriptions)
+        puts "Usage:"
+        usage_descriptions.each do |usage|
+          puts "    #{invocation_path} #{usage}".rstrip
+        end
+      end
+
+      def add_description(description)
+        if description
+          puts ""
+          puts description.gsub(/^/, "  ")
+        end
+      end
+
+      DETAIL_FORMAT = "    %-29s %s"
+
+      def add_list(heading, items)
+        puts "\n#{heading}:"
+        items.each do |item|
+          label, description = item.help
+          description.each_line do |line|
+            puts DETAIL_FORMAT % [label, line]
+            label = ''
+          end
+        end
+      end
+
+      private
+
+      def puts(*args)
+        @out.puts(*args)
+      end
+
+    end
+
+  end
+
+end

data/lib/clamp/option/declaration.rb

@@ -0,0 +1,57 @@
+require 'clamp/attribute_declaration'
+require 'clamp/option'
+
+module Clamp
+  class Option
+
+    module Declaration
+
+      include Clamp::AttributeDeclaration
+
+      def option(switches, type, description, opts = {}, &block)
+        option = Clamp::Option.new(switches, type, description, opts)
+        declared_options << option
+        define_accessors_for(option, &block)
+      end
+
+      def find_option(switch)
+        recognised_options.find { |o| o.handles?(switch) }
+      end
+
+      def declared_options
+        @declared_options ||= []
+      end
+
+      def recognised_options
+        declare_implicit_options
+        effective_options
+      end
+
+      private
+
+      def declare_implicit_options
+        return nil if defined?(@implicit_options_declared)
+        unless effective_options.find { |o| o.handles?("--help") }
+          help_switches = ["--help"]
+          help_switches.unshift("-h") unless effective_options.find { |o| o.handles?("-h") }
+          option help_switches, :flag, "print help" do
+            request_help
+          end
+        end
+        @implicit_options_declared = true
+      end
+
+      def effective_options
+        ancestors.inject([]) do |options, ancestor|
+          if ancestor.kind_of?(Clamp::Option::Declaration)
+            options + ancestor.declared_options
+          else
+            options
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/clamp/option/parsing.rb

@@ -0,0 +1,59 @@
+module Clamp
+  class Option
+
+    module Parsing
+
+      protected
+
+      def parse_options
+        while remaining_arguments.first =~ /^-/
+
+          switch = remaining_arguments.shift
+          break if switch == "--"
+
+          case switch
+          when /^(-\w)(.+)$/ # combined short options
+            switch = $1
+            remaining_arguments.unshift("-#{$2}")
+          when /^(--[^=]+)=(.*)/
+            switch = $1
+            remaining_arguments.unshift($2)
+          end
+            
+          option = find_option(switch)
+          value = option.extract_value(switch, remaining_arguments)
+
+          begin
+            send("#{option.attribute_name}=", value)
+          rescue ArgumentError => e
+            signal_usage_error "option '#{switch}': #{e.message}"
+          end
+
+        end
+      end
+
+      def parse_environment
+        self.class.recognised_options.each do |option|
+          next if option.env_var.nil?
+          next unless ENV.has_key?(option.env_var)
+          value = ENV[option.env_var]
+          if option.flag?
+            # Set true if the env var is "1" false otherwise.
+            send("#{option.attribute_name}=", value == "1")
+          else
+            send("#{option.attribute_name}=", value)
+          end
+        end
+      end
+
+      private
+
+      def find_option(switch)
+        self.class.find_option(switch) || 
+        signal_usage_error("Unrecognised option '#{switch}'")
+      end
+
+    end
+
+  end
+end

data/lib/clamp/option.rb

@@ -0,0 +1,80 @@
+require 'clamp/attribute'
+
+module Clamp
+
+  class Option < Attribute
+
+    def initialize(switches, type, description, options = {})
+      @switches = Array(switches)
+      @type = type
+      @description = description
+      if options.has_key?(:attribute_name)
+        @attribute_name = options[:attribute_name].to_s 
+      end
+      if options.has_key?(:default)
+        @default_value = options[:default]
+      end
+      if options.has_key?(:env)
+        @env_var = options[:env]
+      end
+    end
+
+    attr_reader :switches, :type
+
+    def attribute_name
+      @attribute_name ||= long_switch.sub(/^--(\[no-\])?/, '').tr('-', '_')
+    end
+    
+    def long_switch
+      switches.find { |switch| switch =~ /^--/ }
+    end
+
+    def handles?(switch)
+      recognised_switches.member?(switch)
+    end
+
+    def flag?
+      @type == :flag
+    end
+    
+    def flag_value(switch)
+      !(switch =~ /^--no-(.*)/ && switches.member?("--\[no-\]#{$1}"))
+    end
+
+    def read_method
+      if flag?
+        super + "?"
+      else
+        super
+      end
+    end
+    
+    def extract_value(switch, arguments)
+      if flag?
+        flag_value(switch)
+      else
+        arguments.shift
+      end
+    end
+    
+    def help_lhs
+      lhs = switches.join(", ")
+      lhs += " " + type unless flag?
+      lhs
+    end
+
+    private
+
+    def recognised_switches
+      switches.map do |switch|
+        if switch =~ /^--\[no-\](.*)/
+          ["--#{$1}", "--no-#{$1}"]
+        else
+          switch
+        end
+      end.flatten
+    end
+    
+  end
+
+end

data/lib/clamp/parameter/declaration.rb

@@ -0,0 +1,28 @@
+require 'clamp/attribute_declaration'
+require 'clamp/parameter'
+
+module Clamp
+  class Parameter
+
+    module Declaration
+
+      include Clamp::AttributeDeclaration
+
+      def parameters
+        @parameters ||= []
+      end
+
+      def has_parameters?
+        !parameters.empty?
+      end
+
+      def parameter(name, description, options = {}, &block)
+        parameter = Parameter.new(name, description, options)
+        parameters << parameter
+        define_accessors_for(parameter, &block)
+      end
+
+    end
+
+  end
+end

data/lib/clamp/parameter/parsing.rb

@@ -0,0 +1,24 @@
+module Clamp
+  class Parameter
+
+    module Parsing
+
+      protected
+
+      def parse_parameters
+
+        self.class.parameters.each do |parameter|
+          begin
+            value = parameter.consume(remaining_arguments)
+            send("#{parameter.attribute_name}=", value) unless value.nil?
+          rescue ArgumentError => e
+            signal_usage_error "parameter '#{parameter.name}': #{e.message}"
+          end
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/clamp/parameter.rb

@@ -0,0 +1,80 @@
+require 'clamp/attribute'
+
+module Clamp
+
+  class Parameter < Attribute
+
+    def initialize(name, description, options = {})
+      @name = name
+      @description = description
+      infer_attribute_name_and_multiplicity
+      if options.has_key?(:attribute_name)
+        @attribute_name = options[:attribute_name].to_s
+      end
+      if options.has_key?(:default)
+        @default_value = options[:default]
+      end
+    end
+
+    attr_reader :name, :attribute_name
+
+    def help_lhs
+      name
+    end
+
+    def consume(arguments)
+      if required? && arguments.empty?
+        raise ArgumentError, "no value provided"
+      end
+      if multivalued?
+        if arguments.length > 0
+          arguments.shift(arguments.length)
+        end
+      else
+        arguments.shift
+      end
+    end
+
+    def default_value
+      if defined?(@default_value)
+        @default_value
+      elsif multivalued?
+        []
+      end
+    end
+
+    private
+
+    NAME_PATTERN = "([A-Za-z0-9_-]+)"
+
+    def infer_attribute_name_and_multiplicity
+      case @name
+      when /^\[#{NAME_PATTERN}\]$/
+        @attribute_name = $1
+      when /^\[#{NAME_PATTERN}\] ...$/
+        @attribute_name = "#{$1}_list"
+        @multivalued = true
+      when /^#{NAME_PATTERN} ...$/
+        @attribute_name = "#{$1}_list"
+        @multivalued = true
+        @required = true
+      when /^#{NAME_PATTERN}$/
+        @attribute_name = @name
+        @required = true
+      else
+        raise "invalid parameter name: '#{name}'"
+      end
+      @attribute_name = @attribute_name.downcase.tr('-', '_')
+    end
+
+    def multivalued?
+      @multivalued
+    end
+
+    def required?
+      @required
+    end
+
+  end
+
+end

data/lib/clamp/subcommand/declaration.rb

@@ -0,0 +1,44 @@
+require 'clamp/subcommand'
+
+module Clamp
+  class Subcommand
+
+    module Declaration
+
+      def recognised_subcommands
+        @recognised_subcommands ||= []
+      end
+
+      def subcommand(name, description, subcommand_class = self, &block)
+        if block
+          # generate a anonymous sub-class
+          subcommand_class = Class.new(subcommand_class, &block)
+        end
+        recognised_subcommands << Subcommand.new(name, description, subcommand_class)
+      end
+
+      def has_subcommands?
+        !recognised_subcommands.empty?
+      end
+
+      def find_subcommand(name)
+        recognised_subcommands.find { |sc| sc.is_called?(name) }
+      end
+
+      attr_writer :default_subcommand
+
+      def default_subcommand(*args, &block)
+        if args.empty?
+          @default_subcommand ||= nil
+        else
+          $stderr.puts "WARNING: Clamp default_subcommand syntax has changed; check the README."
+          $stderr.puts "  (from #{caller.first})"
+          subcommand(*args, &block)
+          self.default_subcommand = args.first
+        end
+      end
+
+    end
+
+  end
+end

data/lib/clamp/subcommand/parsing.rb

@@ -0,0 +1,41 @@
+module Clamp
+  class Subcommand
+
+    module Parsing
+
+      protected
+
+      def parse_subcommand
+        return false unless self.class.has_subcommands?
+        subcommand_name = parse_subcommand_name
+        @subcommand = instatiate_subcommand(subcommand_name)
+        @subcommand.parse(remaining_arguments)
+        remaining_arguments.clear
+      end
+
+      private
+
+      def parse_subcommand_name
+        remaining_arguments.shift || self.class.default_subcommand || request_help
+      end
+
+      def find_subcommand(name)
+        self.class.find_subcommand(name) ||
+        signal_usage_error("No such sub-command '#{name}'")
+      end
+
+      def instatiate_subcommand(name)
+        subcommand_class = find_subcommand(name).subcommand_class
+        subcommand = subcommand_class.new("#{invocation_path} #{name}", context)
+        self.class.recognised_options.each do |option|
+          if instance_variable_defined?(option.ivar_name)
+            subcommand.instance_variable_set(option.ivar_name, instance_variable_get(option.ivar_name))
+          end
+        end
+        subcommand
+      end
+
+    end
+
+  end
+end

data/lib/clamp/subcommand.rb

@@ -0,0 +1,23 @@
+module Clamp
+
+  class Subcommand < Struct.new(:name, :description, :subcommand_class)
+
+    def initialize(names, description, subcommand_class)
+      @names = Array(names)
+      @description = description
+      @subcommand_class = subcommand_class
+    end
+
+    attr_reader :names, :description, :subcommand_class
+
+    def is_called?(name)
+      names.member?(name)
+    end
+
+    def help
+      [names.join(", "), description]
+    end
+
+  end
+
+end