mamertes 2.4.1

data/lib/mamertes/option.rb

@@ -0,0 +1,236 @@
+# encoding: utf-8
+#
+# This file is part of the mamertes gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Mamertes
+  # List of valid option types.
+  #
+  # Values are the default values for that type.
+  #
+  # For any unknown type, the default value is `false`, it means that any unknown type is managed as a Boolean value with no argument.
+  OPTION_TYPES = {String => "", Integer => 0, Float => 0.0, Array => []}
+  OPTION_TYPES.default = false
+
+  # This class represents an option for a command.
+  #
+  # @attribute name
+  #   @return [String] The name of this option.
+  # @attribute short
+  #   @return [String] The short form (i.e.: `-h`) for this option.
+  # @attribute long
+  #   @return [String] The long form (i.e.: `--help`) for this option.
+  # @attribute type
+  #   @return [Class] The type of this option.
+  # @attribute required
+  #   @return [Boolean] If this option is required.
+  # @attribute default
+  #   @return [Object] The default value of this option.
+  # @attribute meta
+  #   @return [String] The META argument for this option, used only when showing the help.
+  # @attribute help
+  #   @return [String] An help message for this option.
+  # @attribute value
+  #   @return [Object] The current value of this option.
+  # @attribute action
+  #   @return [Proc] The action associated to this option.
+  # @attribute validator
+  #   @return [Array|Regexp] or A constraint for valid values. Can be an Array of valid values or a Regexp.
+  # @attribute parent
+  #   @return [Command] The parent of this option.
+  class Option
+    attr_accessor :name
+    attr_accessor :short
+    attr_accessor :long
+    attr_accessor :type
+    attr_accessor :required
+    attr_accessor :default
+    attr_accessor :meta
+    attr_accessor :help
+    attr_accessor :value
+    attr_accessor :action
+    attr_accessor :validator
+    attr_accessor :parent
+
+    # Creates a new option.
+    #
+    # @param name [String] The name of this option. Must be unique.
+    # @param forms [Array] An array of short and long forms for this option. Missing forms will be inferred by the name.
+    # @param options [Hash] The settings for this option.
+    # @param action [Proc] The action of this option.
+    def initialize(name, forms = [], options = {}, &action)
+      @name = name.ensure_string
+      @provided = false
+      setup_forms(forms)
+      setup_options(options)
+      setup_action(action)
+    end
+
+    # Sets the short form of this option.
+    #
+    # @param value [String] The short form of this option.
+    def short=(value)
+      value = @name[0, 1] if !value.present?
+
+      # Clean value
+      final_value = value.to_s.match(/^-{0,2}([a-z0-9])(.*)$/i)[1]
+
+      @short = final_value if final_value.present?
+    end
+
+    # Sets the long form of this option.
+    #
+    # @param value [String] The short form of this option.
+    def long=(value)
+      value = @name if !value.present?
+
+      # Clean value
+      final_value = value.to_s.match(/^-{0,2}(.+)$/)[1]
+
+      @long = final_value if final_value.present?
+    end
+
+    # Sets the long form of this option. Can be a Object, an Array or a Regexp.
+    #
+    # @param value [String] The validator of this option.
+    def validator=(value)
+      value = nil if value.blank? || (value.is_a?(Regexp) && value.source.blank?)
+      value = value.ensure_array(nil, true, true, true, :ensure_string) if !value.nil? && !value.is_a?(Regexp)
+      @validator = value
+    end
+
+    # Returns the short form with a dash prepended.
+    #
+    # @return [String] The short form with a dash prepended.
+    def complete_short
+      "-#{@short}"
+    end
+
+    # Returns the long form with two dashes prepended.
+    #
+    # @return [String] The short form with two dashes prepended.
+    def complete_long
+      "--#{@long}"
+    end
+
+    # Returns a label for this option, combining short and long forms.
+    #
+    # @return [String] A label for this option.
+    def label
+      [complete_short, complete_long].compact.join("/")
+    end
+
+    # Returns the meta argument for this option.
+    #
+    # @return [String|NilClass] Returns the current meta argument for this option (the default value is the option name uppercased) or `nil`, if this option doesn't require a meta argument.
+    def meta
+      requires_argument? ? (@meta.present? ? @meta : @name.upcase) : nil
+    end
+
+    # Get the current default value for this option.
+    #
+    # @return [Object] The default value for this option.
+    def default
+      @default || ::Mamertes::OPTION_TYPES[@type]
+    end
+
+    # Check if the current option has a default value.
+    #
+    # @return [Boolean] If the current option has a default value.
+    def has_default?
+      !@default.nil?
+    end
+
+    # Sets the value of this option and also make sure that it is validated.
+    #
+    # @param value [Object] The new value of this option.
+    # @param raise_error [Boolean] If raise an ArgumentError in case of validation errors.
+    # @return [Boolean] `true` if operation succeeded, `false` otherwise.
+    def set(value, raise_error = true)
+      vs = @validator.present? ? (@validator.is_a?(Array) ? :array : :regexp) : false # Check we have a validator
+      rv = vs ? @validator.send(vs == :array ? "include?" : "match", value) : true
+
+      if rv then
+        @value = value
+        @provided = true
+      elsif raise_error then # Validation failed
+        handle_set_failure(vs)
+      else
+        false
+      end
+    end
+
+    # Executes the action associated to this option.
+    def execute_action
+      if @action.present? then
+        @provided = true
+        @action.call(parent, self)
+      end
+    end
+
+    # Checks if this option requires an argument.
+    #
+    # @return [Boolean] `true` if this option requires an argument, `false` otherwise.
+    def requires_argument?
+      [String, Integer, Float, Array].include?(@type) && @action.blank?
+    end
+
+    # If this option was provided.
+    #
+    # @return [Boolean] `true` if this option was provided, `false` otherwise.
+    def provided?
+      @provided
+    end
+
+    # Check if this command has a help.
+    #
+    # @return [Boolean] `true` if this command has a help, `false` otherwise.
+    def has_help?
+      @help.present?
+    end
+
+    # Get the current value for this option.
+    #
+    # @return [Object] The current value of this option.
+    def value
+      provided? ? @value : default
+    end
+
+    private
+      # Setups the forms of the this option.
+      #
+      # @param forms [Array] An array of short and long forms for this option. Missing forms will be inferred by the name.
+      def setup_forms(forms)
+        self.short = forms.length > 0 ? forms[0] : @name[0, 1]
+        self.long = forms.length == 2 ? forms[1] : @name
+      end
+
+      # Setups the settings of the this option.
+      #
+      # @param options [Hash] The settings for this option.
+      def setup_options(options)
+        (options.is_a?(::Hash) ? options : {}).each_pair do |option, value|
+          send("#{option}=", value) if respond_to?("#{option}=")
+        end
+      end
+
+      # Setups the action of the this option.
+      #
+      # @param action [Proc] The action of this option.
+      def setup_action(action)
+        @action = action if action.present? && action.respond_to?(:call) && action.try(:arity) == 2
+      end
+
+      # Handle failure in setting an option.
+      #
+      # @param vs [Symbol] The type of validator.
+      def handle_set_failure(vs)
+        if vs == :array then
+          raise ::Mamertes::Error.new(self, :validation_failed, @parent.i18n.invalid_value(label, ::Mamertes::Parser.smart_join(@validator)))
+        else
+          raise ::Mamertes::Error.new(self, :validation_failed, @parent.i18n.invalid_for_regexp(label, @validator.inspect))
+        end
+      end
+  end
+end

data/lib/mamertes/parser.rb

@@ -0,0 +1,317 @@
+# encoding: utf-8
+#
+# This file is part of the mamertes gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Mamertes
+  # Methods for the {Parser Parser} class.
+  module ParserMethods
+    # General methods.
+    module General
+      extend ActiveSupport::Concern
+
+      # Class methods
+      module ClassMethods
+        # Joins an array using multiple separators.
+        #
+        # @param array [Array] The array to join.
+        # @param separator [String] The separator to use for all but last join.
+        # @param last_separator [String] The separator to use for the last join.
+        # @param quote [String] If not nil, elements are quoted with that element.
+        # @return [String] The joined array.
+        def smart_join(array, separator = ", ", last_separator = " and ", quote = "\"")
+          separator = separator.ensure_string
+          last_separator = last_separator.ensure_string
+          array = array.ensure_array {|a| quote.present? ? "#{quote}#{a}#{quote}" : a.ensure_string }
+          array.length < 2 ? (array[0] || "") : (array[0, array.length - 1].join(separator) + last_separator + array[-1])
+        end
+
+        # Finds a command which corresponds to an argument.
+        #
+        # @param arg [String] The string to match.
+        # @param command [Command] The command to search subcommand in.
+        # @param args [String] The complete list of arguments passed.
+        # @param separator [String] The separator for joined syntax commands.
+        # @return [Hash|NilClass] An hash with `name` and `args` keys if a valid subcommand is found, `nil` otherwise.
+        def find_command(arg, command, args, separator = ":")
+          args = args.ensure_array.dup
+
+          if command.commands.present? then
+            arg, args = adjust_command(arg, args, separator)
+
+            matching = match_subcommands(arg, command)
+            if matching.length == 1 # Found a command
+              {name: matching[0], args: args}
+            elsif matching.length > 1 # Ambiguous match
+              raise ::Mamertes::Error.new(command, :ambiguous_command, command.i18n.ambigous_command(arg, ::Mamertes::Parser.smart_join(matching)))
+            end
+          else
+            nil
+          end
+        end
+
+        # Parses a command/application.
+        #
+        # @param command [Command] The command or application to parse.
+        # @param args [Array] The arguments to parse.
+        # @return [Hash|NilClass] An hash with `name` (of a subcommand to execute) and `args` keys if a valid subcommand is found, `nil` otherwise.
+        def parse(command, args)
+          ::Mamertes::Parser.new.parse(command, args)
+        end
+
+        private
+          # Adjusts a command so that it only specify a single command.
+          #
+          # @param arg [String] The string to match.
+          # @param args [String] The complete list of arguments passed.
+          # @param separator [String] The separator for joined syntax commands.
+          # @return [Array] Adjust command and arguments.
+          def adjust_command(arg, args, separator)
+            if arg.index(separator) then
+              tokens = arg.split(separator, 2)
+              arg = tokens[0]
+              args.insert(0, tokens[1])
+            end
+
+            [arg, args]
+          end
+
+          # Matches a string against a command's subcommands.
+          #
+          # @param arg [String] The string to match.
+          # @param command [Command] The command to search subcommand in.
+          # @return [Array] The matching subcommands.
+          def match_subcommands(arg, command)
+            command.commands.keys.select {|c| c =~ /^(#{Regexp.quote(arg)})/ }.compact
+          end
+      end
+    end
+  end
+
+  # The parser for the command line.
+  class Parser
+    include ::Mamertes::ParserMethods::General
+
+    # Parses a command/application.
+    #
+    # @param command [Command] The command or application to parse.
+    # @param args [Array] The arguments to parse.
+    # @return [Hash|NilClass] An hash with `name` (of a subcommand to execute) and `args` keys if a valid subcommand is found, `nil` otherwise.
+    def parse(command, args)
+      args = args.ensure_array.dup
+      forms, parser = create_parser(command)
+      perform_parsing(parser, command, args, forms)
+    end
+
+    private
+      # Creates a new option parser.
+      #
+      # @param command [Command] The command or application to parse.
+      # @return [OptionParser] The new parser
+      def create_parser(command)
+        forms = {}
+        parser = OptionParser.new do |opts|
+          # Add every option
+          command.options.each_pair do |_, option|
+            check_unique(command, forms, option)
+            setup_option(command, opts, option)
+          end
+        end
+
+        [forms, parser]
+      end
+
+      # Perform the parsing
+      #
+      # @param parser [OptionParser] The option parser.
+      # @param command [Command] The command or application to parse.
+      # @param args [Array] The arguments to parse.
+      # @param forms [Hash] The current forms.
+      def perform_parsing(parser, command, args, forms)
+        rv = nil
+
+        begin
+          rv = execute_parsing(parser, command, args)
+        rescue OptionParser::NeedlessArgument, OptionParser::MissingArgument, OptionParser::InvalidOption => oe
+          type = oe.class.to_s.gsub("OptionParser::", "").underscore.to_sym
+          opt = oe.args.first
+          raise ::Mamertes::Error.new(forms[opt], type, command.i18n.send(type, opt))
+        rescue => e
+          raise e
+        end
+
+        rv
+      end
+
+      # Executes the parsing.
+      #
+      # @param parser [OptionParser] The option parser.
+      # @param command [Command] The command or application to parse.
+      # @param args [Array] The arguments to parse.
+      # @return [Command|nil] A command to execute or `nil` if no valid command was found.
+      def execute_parsing(parser, command, args)
+        rv = nil
+
+        if command.options.present? then
+          rv = parse_options(parser, command, args)
+          check_required_options(command)
+        elsif args.present? then
+          rv = find_command_to_execute(command, args)
+        end
+
+        rv
+      end
+
+      # Setups an option for a command.
+      #
+      # @param command [Command] The command or application to parse.
+      # @param opts [Object] The current set options.
+      # @param option [Option] The option to set.
+      def setup_option(command, opts, option)
+        case option.type.to_s
+          when "String" then parse_string(command, opts, option)
+          when "Integer" then parse_number(command, opts, option, :is_integer?, :to_integer, command.i18n.invalid_integer(option.label))
+          when "Float" then parse_number(command, opts, option, :is_float?, :to_float, command.i18n.invalid_float(option.label))
+          when "Array" then parse_array(command, opts, option)
+          else option.action.present? ? parse_action(opts, option) : parse_boolean(opts, option)
+        end
+      end
+
+      # Checks if a option is unique.
+      #
+      # @param command [Command] The command or application to parse.
+      # @param forms [Hash] The current forms.
+      # @param option [Option] The option to set.
+      def check_unique(command, forms, option)
+        if forms[option.complete_short] || forms[option.complete_long] then
+          raise ::Mamertes::Error.new(command, :ambiguous_form, command.i18n.conflicting_options(option.label, forms[option.complete_short].label))
+        else
+          forms[option.complete_short] = option.dup
+          forms[option.complete_long] = option.dup
+        end
+      end
+
+      # Parses an action option. A block must be provided to deal with the value.
+      #
+      # @param command [Command] The command or application to parse.
+      # @param opts [Object] The current set options.
+      # @param option [Option] The option to set.
+      def parse_option(command, opts, option)
+        opts.on("#{option.complete_short} #{option.meta || command.i18n.help_arg}", "#{option.complete_long} #{option.meta || command.i18n.help_arg}") do |value|
+          yield(value)
+        end
+      end
+
+      # Parses an action option.
+      #
+      # @param opts [Object] The current set options.
+      # @param option [Option] The option to set.
+      def parse_action(opts, option)
+        opts.on("-#{option.short}", "--#{option.long}") do |_|
+          option.execute_action
+        end
+      end
+
+      # Parses a string option.
+      #
+      # @param command [Command] The command or application to parse.
+      # @param opts [Object] The current set options.
+      # @param option [Option] The option to set.
+      def parse_string(command, opts, option)
+        parse_option(command, opts, option) { |value| option.set(value) }
+      end
+
+      # Parses a number option.
+      #
+      # @param command [Command] The command or application to parse.
+      # @param opts [Object] The current set options.
+      # @param option [Option] The option to set.
+      # @param check_method [Symbol] The method to execute to check option validity. Must return a boolean.
+      # @param convert_method [Symbol] The method to execute to convert option.
+      # @param invalid_message [String] The string to send in case of invalid arguments.
+      def parse_number(command, opts, option, check_method, convert_method, invalid_message)
+        parse_option(command, opts, option) do |value|
+          raise ::Mamertes::Error.new(option, :invalid_argument, invalid_message) if !value.send(check_method)
+          option.set(value.send(convert_method))
+        end
+      end
+
+      # Parses an array option.
+      #
+      # @param command [Command] The command or application to parse.
+      # @param opts [Object] The current set options.
+      # @param option [Option] The option to set.
+      def parse_array(command, opts, option)
+        opts.on("#{option.complete_short} #{option.meta || command.i18n.help_arg}", "#{option.complete_long} #{option.meta || command.i18n.help_arg}", Array) do |value|
+          option.set(value.ensure_array)
+        end
+      end
+
+      # Parses an action option.
+      #
+      # @param opts [Object] The current set options.
+      # @param option [Option] The option to set.
+      def parse_boolean(opts, option)
+        opts.on("-#{option.short}", "--#{option.long}") do |value|
+          option.set(value.to_boolean)
+        end
+      end
+
+      # Parses options of a command.
+      #
+      # @param parser [OptionParser] The option parser.
+      # @param command [Command] The command or application to parse.
+      # @param args [Array] The arguments to parse.
+      # @return [Command|nil] A command to execute or `nil` if no command was found.
+      def parse_options(parser, command, args)
+        rv = nil
+
+        # Parse options
+        parser.order!(args) do |arg|
+          fc = ::Mamertes::Parser.find_command(arg, command, args)
+
+          if fc.present? then
+            rv = fc
+            parser.terminate
+          else
+            command.argument(arg)
+          end
+        end
+
+        rv
+      end
+
+      # Checks if all options of a command are present.
+      #
+      # @param command [Command] The command or application to parse.
+      def check_required_options(command)
+        # Check if any required option is missing.
+        command.options.each_pair  do |name, option|
+          raise ::Mamertes::Error.new(option, :missing_option, command.i18n.missing_option(option.label)) if option.required && !option.provided?
+        end
+      end
+
+      # Finds a command to execute
+      #
+      # @param command [Command] The command or application to parse.
+      # @param args [Array] The arguments to parse.
+      # @return [Command|nil] A command to execute or `nil` if no command was found.
+      def find_command_to_execute(command, args)
+        rv = nil
+
+        # Try to find a command into the first argument
+        fc = ::Mamertes::Parser.find_command(args[0], command, args[1, args.length - 1])
+
+        if fc.present? then
+          rv = fc
+        else
+          args.each do |arg|
+            command.argument(arg)
+          end
+        end
+
+        rv
+      end
+  end
+end