bovem 2.4.1 → 3.0.0

data/lib/bovem/console.rb

@@ -29,9 +29,9 @@ module Bovem
           style = style.ensure_string.strip.parameterize
 
           if style.present? then
-            ::Bovem::Console.replace_term_code(Bovem::TERM_EFFECTS, style, 0) ||
-              ::Bovem::Console.replace_term_code(Bovem::TERM_COLORS, style, 30) ||
-              ::Bovem::Console.replace_term_code(Bovem::TERM_COLORS, style.gsub(/^bg_/, ""), 40) ||
+            Bovem::Console.replace_term_code(Bovem::TERM_EFFECTS, style, 0) ||
+              Bovem::Console.replace_term_code(Bovem::TERM_COLORS, style, 30) ||
+              Bovem::Console.replace_term_code(Bovem::TERM_COLORS, style.gsub(/^bg_/, ""), 40) ||
               ""
           else
             ""
@@ -80,10 +80,10 @@ module Bovem
           message.ensure_string.gsub(/((\{mark=([a-z\-_\s,]+)\})|(\{\/mark\}))/mi) do
             if $1 == "{/mark}" then # If it is a tag, pop from the latest opened.
               stack.pop
-              plain || stack.blank? ? "" : ::Bovem::Console.parse_styles(stack.last)
+              plain || stack.blank? ? "" : Bovem::Console.parse_styles(stack.last)
             else
               styles = $3.ensure_string
-              replacement = plain ? "" : ::Bovem::Console.parse_styles(styles)
+              replacement = plain ? "" : Bovem::Console.parse_styles(styles)
 
               if replacement.length > 0 then
                 stack << "reset" if stack.blank?
@@ -104,7 +104,7 @@ module Bovem
       # @param plain [Boolean] If ignore (cleanify) color markers into the message.
       # @return [String] The replaced message.
       def replace_markers(message, plain = false)
-        ::Bovem::Console.replace_markers(message, plain)
+        Bovem::Console.replace_markers(message, plain)
       end
     end
 
@@ -281,7 +281,7 @@ module Bovem
       #
       # @see #format
       def write_banner_aligned(message, suffix = "\n", indent = true, wrap = false, plain = false, print = true)
-        write((" " * (::Bovem::Console.min_banner_length + 3)) + message.ensure_string, suffix, indent, wrap, plain, print)
+        write((" " * (Bovem::Console.min_banner_length + 3)) + message.ensure_string, suffix, indent, wrap, plain, print)
       end
 
       # Writes a status to the output. Valid values are `:ok`, `:pass`, `:fail`, `:warn`.
@@ -604,7 +604,7 @@ module Bovem
     #
     # @return [Console] A new instance.
     def self.instance
-      @instance ||= ::Bovem::Console.new
+      @instance ||= Bovem::Console.new
     end
 
     # Initializes a new Console.

data/lib/bovem/errors.rb

@@ -14,5 +14,32 @@ module Bovem
     # This exception is raised if a {Logger Logger} is invalid.
     class InvalidLogger < ::ArgumentError
     end
+
+    # This exception is raised when something goes wrong.
+    #
+    # @attribute [r] target
+    #   @return [Object] The target of this error.
+    # @attribute [r] reason
+    #   @return [Symbol] The reason of failure.
+    # @attribute [r] message
+    #   @return [String] A human readable message.
+    class Error < ArgumentError
+      attr_reader :target
+      attr_reader :reason
+      attr_reader :message
+
+      # Initializes a new error
+      #
+      # @param target [Object] The target of this error.
+      # @param reason [Symbol] The reason of failure.
+      # @param message [String] A human readable message.
+      def initialize(target, reason, message)
+        super(message)
+
+        @target = target
+        @reason = reason
+        @message = message
+      end
+    end
   end
 end

data/lib/bovem/localizer.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+#
+# This file is part of the bovem 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 Bovem
+  # This class is used to localize strings inside classes methods.
+  class Localizer < ::Lazier::Localizer
+    # Initialize a new localizer.
+    #
+    # @param locale [String|Symbol] The locale to use for localization.
+    def initialize(locale)
+      super("bovem.application", ::File.absolute_path(::Pathname.new(::File.dirname(__FILE__)).to_s + "/../../locales/"), locale)
+    end
+
+    # Localize a message in a specified locale.
+    #
+    # @param locale [String|Symbol] The locale to use for localization.
+    # @param message [String|Symbol] The message to localize.
+    # @param args [Array] Optional arguments to localize the message.
+    # @return [String|R18n::Untranslated] The localized message.
+    def self.localize_on_locale(locale, message, *args)
+      new(locale).i18n.send(message, *args)
+    end
+  end
+end

data/lib/bovem/logger.rb

@@ -10,12 +10,6 @@ module Bovem
   # @attribute [r] device
   #   @return [IO|String] The file or device to log messages to.
   class Logger < ::Logger
-    # @attribute start_time
-    #   @return [Time] The start time of first line. This allows to show a `T+0.1234` information into the log.
-    class << self
-      attr_accessor :start_time
-    end
-
     attr_reader :device
 
     # Creates a new logger.
@@ -78,14 +72,14 @@ module Bovem
           else :white
         end
 
-        header = ::Bovem::Console.replace_markers("{mark=bright-#{color}}[%s T+%0.5f] %s:{/mark}" %[datetime.strftime("%Y/%b/%d %H:%M:%S"), [datetime.to_f - start_time.to_f, 0].max, severity.rjust(5)])
+        header = Bovem::Console.replace_markers("{mark=bright-#{color}}[%s T+%0.5f] %s:{/mark}" %[datetime.strftime("%Y/%b/%d %H:%M:%S"), [datetime.to_f - start_time.to_f, 0].max, severity.rjust(5)])
         "%s %s\n" % [header, msg]
       }
     end
 
     # The log time of the first logger. This allows to show a `T+0.1234` information into the log.
     # @return [Time] The log time of the first logger.
-    def start_time
+    def self.start_time
       @start_time ||= ::Time.now
     end
   end

data/lib/bovem/option.rb

@@ -0,0 +1,250 @@
+# encoding: utf-8
+#
+# This file is part of the bovem 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 Bovem
+  # 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, a Regexp or a Proc which takes one argument and returns a boolean.
+    #
+    # @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) if !value.nil? && !value.is_a?(Regexp) && !value.is_a?(Proc)
+      @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 || Bovem::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 = get_validator_method(@validator)
+      rv = vs ? @validator.send(vs, value) : true
+
+      if rv then
+        @value = value
+        @provided = true
+      else # Validation failed
+        @value = nil
+        @provided = false
+        handle_set_failure(vs) if raise_error
+        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 == "include?" then
+          raise Bovem::Errors::Error.new(self, :validation_failed, @parent.i18n.invalid_value(label, Bovem::Parser.smart_join(@validator)))
+        else
+          raise Bovem::Errors::Error.new(self, :validation_failed, @parent.i18n.invalid_for_regexp(label, @validator.is_a?(::Proc) ? "[FUNCTION]" : @validator.inspect))
+        end
+      end
+
+      # Gets the method required to verify a validator.
+      #
+      # @param validator [Object] The type of the validator.
+      # @return [String] A method to call to verify the validator.
+      def get_validator_method(validator)
+        case validator.class.to_s
+          when "Array" then "include?"
+          when "Regexp" then "match"
+          when "Proc" then "call"
+          else false
+        end
+      end
+  end
+end

data/lib/bovem/parser.rb

@@ -0,0 +1,317 @@
+# encoding: utf-8
+#
+# This file is part of the bovem 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 Bovem
+  # 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 Bovem::Errors::Error.new(command, :ambiguous_command, command.i18n.ambigous_command(arg, Bovem::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)
+          Bovem::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 Bovem::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 Bovem::Errors::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 Bovem::Errors::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 Bovem::Errors::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 = Bovem::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 Bovem::Errors::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 = Bovem::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