fuelcell 0.1.0

data/lib/fuelcell/help/usage_formatter.rb

@@ -0,0 +1,88 @@
+module Fuelcell
+  module Help
+    # Formats help text to be displayed on the command line. The formatter
+    # works with help text structured in a hash.
+    class UsageFormatter < BaseFormatter
+
+      def call(data)
+        usage = data[:usage] || {}
+        text  = format_cmd(usage)
+        opts  = format_opts(usage[:opts], text.size + 1)
+        text += ' ' + opts unless opts.empty?
+
+        "#{text}\n"
+      end
+
+      # Format the options so that they wrap at the max width of the terminal
+      # and that they align after the command path.
+      #
+      # @param opts [Hash]
+      # @param align [Int]
+      # @return [String]
+      def format_opts(opts, align_width)
+        text = ''
+        line_width = align_width
+        opts.each do |opt|
+          text, line_width = append_opts(text, opt, line_width, align_width)
+        end
+        text.strip
+      end
+
+      # Format the label and the path which make the up
+      # the first line of usage text.
+      #
+      # @param data [Hash]
+      # @return [Array] formatted text, size of text
+      def format_cmd(data)
+        "#{data[:label]} #{data[:path]}"
+      end
+
+      # Append a single opt text to the usage line. Ensure wrapping
+      # occurs correctly & wrapped opt aligns with the start of the
+      # first opt.
+      #
+      # The align width is the amount of padding necessary in order to align
+      # all the opt text from the left.
+      #
+      # @param text [String] text of all currently appended options
+      # @param opt  [String] text of the current option
+      # @param line_width [Int] width of the current line including padding
+      # @param align_width [Int] opts will align to this width after wrapping
+      def append_opts(text, opt, line_width, align_width)
+        str = opt_display(opt)
+        if (line_width + str.size) < max_width
+          return append_current_line(text, str, line_width)
+        end
+
+        append_nextline(text, str, align_width)
+      end
+
+      # Used to append to the usage line when its shorted then the terminal
+      # window
+      #
+      # @param text [String] the current usage line
+      # @param str [String] the string to be appended
+      # @param line_width [Int] width of current line
+      # @return [Array] append text & size
+      def append_current_line(text, str, line_width)
+        line_width += str.size + 1
+        text << str + ' '
+        [text, line_width]
+      end
+
+      # Used append a newline to the usage and wrap the text because it
+      # is long then the terminal width
+      #
+      def append_nextline(text, str, align_width)
+        text = text.strip + "\n"
+        text << (' ' * align_width) + str
+        [text, text.size]
+      end
+
+      def opt_display(data)
+        text = "#{short_opt(data)} #{long_opt(data)}".strip
+        "[#{text}]"
+      end
+    end
+  end
+end

data/lib/fuelcell/help.rb

@@ -0,0 +1,27 @@
+require 'fuelcell/help/builder'
+require 'fuelcell/help/base_formatter'
+require 'fuelcell/help/usage_formatter'
+require 'fuelcell/help/opts_formatter'
+require 'fuelcell/help/cmds_formatter'
+require 'fuelcell/help/desc_formatter'
+
+module Fuelcell
+  module Help
+    class << self
+      def generate(root, args = [], width = 80)
+        data = Builder.new.call(root, args)
+        text = UsageFormatter.new(width: width).call(data)
+
+        line = DescFormatter.new(width: width).call(data)
+        text << "\n" + line unless line.empty?
+
+        line = OptsFormatter.new(width: width).call(data)
+        text << "\n" + line unless line.empty?
+
+        line = CmdsFormatter.new(width: width).call(data)
+        text << "\n" + line unless line.empty?
+        text
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/arg_handler.rb

@@ -0,0 +1,31 @@
+module Fuelcell
+  module Parser
+    # Parse args based on command definitions & cast the value into the correct
+    # type. This will leave us with the args array (its values modified by the
+    # command definitions) and an args hash with its keys derived from the
+    # definition. Boths theses lists are needed to create the ArgResult which
+    # is returned
+    class ArgHandler < BaseHandler
+      SKIP = '__FUELCELL_SKIP_ARG__'
+      # @param cmd [Fuelcell::Command]
+      # @param args [Array] raw args from ARGV
+      # @return [Fuelcell::Action::ArgsResults]
+      def call(cmd, args)
+        list = {}
+        manager = cmd.args
+        manager.each_with_index do |arg, index|
+          value = args.fetch(index) {
+            fail "argument at #{index} is required" if arg.required?
+            arg.default? ? arg.default : SKIP
+          }
+          next if value == SKIP
+          args[index] = cast(arg.type, value)
+          # assign a pointer to the casted value
+          list[arg.name] = index
+        end
+
+        Fuelcell::Action::ArgResults.new(args, list)
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/base_handler.rb

@@ -0,0 +1,133 @@
+module Fuelcell
+  module Parser
+    # Parsing the command line involves a command object, raw args array and
+    # the final options hash. Handlers use the command object to determine
+    # specifications on options and args, they will add and remove raw args
+    # and add to the options hash. This class provides helper methods used
+    # to encapsulate the command tasks needed by every handler
+    class BaseHandler
+
+      # Anything that does not start with an "-" is considered an arg
+      # nil is not considered an arg or an opt, since all elements in
+      # ARGV are strings
+      #
+      # @param text [String]  represents an element from ARGV
+      # @return [Boolean]
+      def arg?(text)
+        return false if text.nil?
+        !text.to_s.start_with?('-')
+      end
+
+      # Search for an opt definition in the given command object
+      #
+      # @param cmd [Fuelcell::Command] command found on the cli
+      # @param name [String] name of the object
+      # @return [Fuelcell::OptDefinition]
+      def find_opt(cmd, name)
+        opt  = cmd.find_opt(name)
+        fail "option #{name} is not registered" unless opt
+        opt
+      end
+
+      # Allows handlers to match the first raw arg against a
+      # regex or someother condition and if it fails that arg
+      # will be put back into the raw args otherwise the handler
+      # will process it
+      #
+      # params arg [String]
+      # returns [Boolean, String]
+      def take_first_arg(args)
+        arg = args.shift
+        unless yield arg
+          args.unshift arg
+          return false
+        end
+        arg
+      end
+
+      # Assigns opt name and value into the opts hash. It provides a common
+      # place for validation checks and casting.
+      #
+      # @param opts [Hash]  holds processed opts
+      # @param opt  [Fuelcell::OptDefinition]
+      # @param value [String] value found in raw_args
+      # @param raw_arg [String] used for error msg, the actual opt string
+      # @return the casted value
+      def assign_opt_value(opts, opt, value, raw_arg)
+        fail "#{raw_arg} is a flag and can not accept values" if opt.flag?
+
+        opts[opt.name] = cast(opt.type, value)
+      end
+
+      def cast_numeric(value)
+        unless value =~ /[-+]?\d*\.\d+|\d+/
+          fail ArgumentError, "expecting a numeric type, '#{value}' is invalid"
+        end
+        value.index('.') ? value.to_f : value.to_i
+      end
+
+      def cast_bool(value)
+        case value.to_s.downcase
+        when 'true', 'yes', '1' then true
+        when 'false', 'no', '0' then false
+        else
+          fail ArgumentError, "expecting bool value like " +
+                              "(true,false,yes,no,1,0), #{value} is invalid"
+        end
+      end
+
+      # Collect all values in raw args upto the first option and put then
+      # into an array
+      #
+      # @params value [String] the first value of the array
+      # @params raw_args [Array] raw args used to collect remaining items
+      # @return [Array]
+      def cast_array(value)
+        value.to_s.split(',')
+      end
+
+      # A hash key value pair is assumed to be in the form key:value. Collect
+      # all args that are not opts and process them.
+      #
+      # @param value [String] the first key value pair
+      # @param raw_args [Array] raw args to collect remaining hash values
+      # @return [Hash]
+      def cast_hash(value)
+        list   = cast_array(value)
+        result = {}
+        list.each do |item|
+          key, value  = item.split(':', 2)
+          result[key] = value
+        end
+
+        result
+      end
+
+      # Delegate the cast based on type
+      #
+      # @param type [Symbol]
+      # @param value [String]
+      # @param raw_args [Array]
+      # @return casted value
+      def cast(type, value)
+        case type
+        when :numeric then cast_numeric(value)
+        when :bool    then cast_bool(value)
+        when :hash    then cast_hash(value)
+        when :array   then cast_array(value)
+        else
+          value.to_s
+        end
+      end
+
+      # A flag has a value of true when its found
+      #
+      # @param opts [Hash]  processed opts
+      # @param opt  [Fuelcell::OptDefinition]
+      # @return [Boolean]
+      def found_opt_flag(opts, opt)
+        opts[opt.name] = true
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/cmd_args_strategy.rb

@@ -0,0 +1,28 @@
+module Fuelcell
+  module Parser
+    class CmdArgsStrategy
+
+      # Extract arguments that form the command to be executed.
+      #
+      # This will collect all arguments up to the first option or the ignore
+      # symbol --. It separates and returns the command args as an array of
+      # strings that form a heirarchal route to the command. These command args
+      # are removed from the raw arg list
+      #
+      #
+      # @param [Array] raw args from ARGV
+      # @return <Array>
+      def call(args)
+        cmd_args = []
+        while item = args.shift
+          if item.start_with?('-')
+            args.unshift(item)
+            break
+          end
+          cmd_args << item
+        end
+        cmd_args
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/ignore_handler.rb

@@ -0,0 +1,25 @@
+module Fuelcell
+  module Parser
+    # Removes any args after the string '--' is found in the raw_args. It also
+    # removes the ignore string itself from the raw args.
+    #
+    # @param raw_args [Array] list of args usually from ARGV
+    # @return [Array]
+    class IgnoreHandler
+      def call(raw_args)
+        unless raw_args.is_a?(Array)
+          fail ArgumentError, 'raw args must be an array'
+        end
+
+        ignores = []
+        index   = raw_args.index('--')
+        return ignores unless index
+
+        ignores = raw_args.slice!(index, raw_args.size)
+        # remove the ignore symbol --
+        ignores.shift
+        ignores
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/opt_handler.rb

@@ -0,0 +1,58 @@
+module Fuelcell
+  module Parser
+    # Process options that are flags or use another arg as their value. This
+    # handles both short and long options. Flags are assigned a value of true
+    # while all other values are casted during value assignment
+    class OptHandler < BaseHandler
+      # @param cmd [Fuelcell::Command]
+      # @param args [Array] raw args from ARGV
+      # @param opts [Hash] stores the found opts
+      # @return [Boolean]
+      def call(cmd, args, opts)
+        arg = take_first_arg(args) do |text|
+          !(text =~ /^(--\w+(?:-\w+)*|-[a-zA-Z])$/).nil?
+        end
+        return false unless arg
+
+        opt = find_opt(cmd, arg)
+        return true if handled_flag?(opts, opt)
+
+        # We know we are not a flag, so we are expecting a value.
+        # We also know there are no other values available so for now
+        # this is considered a failure condition
+        fail_value_required(opt) if args.empty?
+
+        handle_value(opts, opt, arg, args)
+        true
+      end
+
+      private
+
+      def handle_value(opts, opt, arg, args)
+        value = args.shift
+        unless arg?(value)
+          if opt.default?
+            value = opt.default
+          else
+            fail_value_required(opt)
+          end
+        end
+
+        assign_opt_value(opts, opt, value, arg)
+      end
+
+      def handled_flag?(opts, opt)
+        return false unless opt.flag?
+        found_opt_flag(opts, opt)
+        true
+      end
+
+      def fail_value_required(opt)
+        return if opt.callable? || opt.cmd_path?
+
+        cli_opts = opt.cli_labels.join(' or ')
+        fail "value not found for #{cli_opts} when value is required"
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/opt_name_handler.rb

@@ -0,0 +1,89 @@
+module Fuelcell
+  module Parser
+    class OptNameHandler
+      # Parses the option defintiion name according to a set of rules that
+      # allows a short hand to be used to give the option name, its cli
+      # long & short names. The names are separated by |
+      #
+      # specify all 3: <opt name>|<cli long>|<cli short>
+      #                when manually specifying all three the opt name is
+      #                always first
+      #                ex) version-opt|version|v
+      #
+      # specify 2: <cli long>|<cli short>
+      #            <cli short>|<cli long>
+      #            <opt name>|<cli long>
+      #            when specifying 2 the opt name & cli long will be the same
+      #            if one of the given names is a cli short
+      #            ex) version|v
+      #            ex) v|version
+      #            ex) version-opt|version - only opt name and cli long are set
+      #
+      # specify 1: <cli-long>
+      #            <cli-short>
+      #            ex) v       - cli short and opt name will be the same, no
+      #                          cli longs will be set
+      #            ex) version - cli long and opt name will be the same, no
+      #                          cli short will be set
+      #
+      #
+      # @param name [String]
+      def call(text)
+        text = text.to_s
+        fail ArgumentError, 'option name can not be empty' if text.empty?
+
+        parts = text.split('|')
+        method_name = "manually_assign_#{parts.size}"
+        name, long, short = send(method_name, parts)
+
+        if !short.nil? && short.size > 1
+          fail ArgumentError, "option short name (#{short}) can only be 1 char"
+        end
+
+        [name, long, short]
+      end
+
+      private
+
+      def manually_assign_3(names)
+        if names[0].size == 1
+          fail ArgumentError,
+               'short name can not be first when setting all 3 names'
+        end
+
+        if names[1].size > 1
+          name, long, short = names[0..2]
+        else
+          name, short, long = names[0..2]
+        end
+        [name, long, short]
+      end
+
+      def manually_assign_2(names)
+        name, long = names[0..1]
+        short = nil
+        if names.last.size == 1
+          long, short = names[0..1]
+          name = long
+        elsif names.first.size == 1
+          short, long = names[0..1]
+          name = long
+        end
+        [name, long, short]
+      end
+
+      def manually_assign_1(names)
+        name = names.first
+        if name.size == 1
+          short = name
+          long  = nil
+        else
+          long  = name
+          short = nil
+        end
+
+        [name, long, short]
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/opt_value_equal_handler.rb

@@ -0,0 +1,26 @@
+module Fuelcell
+  module Parser
+    class OptValueEqualHandler < BaseHandler
+
+      # Handle options both long and short that express their value using an
+      # equal sign like --foo=bar or -f=bar
+      #
+      # @param cmd [Fuelcell::Command]
+      # @param args [Array] raw args from ARGV
+      # @param opts [Hash] stores the found opts
+      # @return [Boolean]
+      def call(cmd, args, opts)
+        return false unless take_first_arg(args) do |arg|
+          !!(arg =~ /^(--\w+(?:-\w+)*|-[a-zA-Z])=(.*)$/)
+        end
+
+        name  = $1
+        value = $2
+
+        opt = find_opt(cmd, name)
+        assign_opt_value(opts, opt, value, name)
+        true
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/parsing_strategy.rb

@@ -0,0 +1,80 @@
+require_relative 'ignore_handler'
+require_relative 'opt_value_equal_handler'
+require_relative 'short_opt_no_space_handler'
+require_relative 'opt_handler'
+require_relative 'arg_handler'
+
+module Fuelcell
+  module Parser
+    class ParsingStrategy < BaseHandler
+      attr_reader :ignore_handler, :opt_handlers, :arg_handler
+
+      # Arrange all the handlers in the correct order for this
+      # strategy.The order is as follows:
+      # 1. short clusters
+      # 2. opts using equals
+      # 3. short opts that have no space between them and their value
+      # 4. all other option conditions
+      # 5. check that all required options have been processed.
+      #
+      # The check for required options is designed to be handled last
+      def initialize
+        @ignore_handler = IgnoreHandler.new
+        @opt_handlers   = [
+          ShortOptNoSpaceHandler.new,
+          OptValueEqualHandler.new,
+          OptHandler.new
+        ]
+
+        @arg_handler = ArgHandler.new
+      end
+
+      # Run all handlers in order, in a continuous loop until all raw args
+      # are empty. Handlers implement the call method as a strategy pattern
+      # so they all have the same signature. During the loop and after all
+      # the handlers have run, we check the first arg, if it's not an opt
+      # it means it's a arg so we move it to the args array. This
+      # process continues until there are no other args. Required options
+      # are not inforced for the help command
+      #
+      # @param cmd [Fuelcell::Command]
+      # @param raw_args [Array] raw args from ARGV
+      # @param opts [Hash] stores processed options
+      # @return [Array] the process options and processed args
+      def call(cmd, raw_args, opts = Fuelcell::Action::OptResults.new)
+        ignores = ignore_handler.call(raw_args)
+        args = run_option_handlers(cmd, raw_args, opts)
+        args = arg_handler.call(cmd, args)
+        unless cmd.name == 'help'
+          cmd.missing_opts(opts.keys) do |missing|
+            fail "option [#{missing.first.cli_names}] is required"
+          end
+        end
+
+        format_return(cmd, opts, args, ignores)
+      end
+
+      private
+
+      def run_option_handlers(cmd, raw_args, opts)
+        args = []
+        until raw_args.empty?
+          opt_handlers.each do |handler|
+            break if handler.call(cmd, raw_args, opts)
+          end
+          args << raw_args.shift if arg?(raw_args.first)
+        end
+        args
+      end
+
+      def format_return(cmd, opts, args, ignores)
+        {
+          cmd: cmd,
+          opts: opts,
+          args: args,
+          ignores: ignores
+        }
+      end
+    end
+  end
+end

data/lib/fuelcell/parser/short_opt_no_space_handler.rb

@@ -0,0 +1,54 @@
+module Fuelcell
+  module Parser
+    # Handles short options that express their value without using a space like
+    # -uroot where the short opt is -u and value is root
+    class ShortOptNoSpaceHandler < BaseHandler
+      # @param cmd [Fuelcell::Command]
+      # @param args [Array] raw args from ARGV
+      # @param opts [Hash] stores the found opts
+      # @return [Boolean]
+      def call(cmd, args, opts)
+        arg = take_first_arg(args) do |text|
+          !(text =~ /^-([a-zA-Z]{2,})$/).nil?
+        end
+        return false unless arg
+
+        return true if handle_no_space_value(cmd, opts, args, arg)
+
+        arg[0] = '' # remove the dash
+        handle_cluster(cmd, opts, arg)
+
+        true
+      end
+
+      private
+
+      # we need to determine if this is a short opt with a value
+      # smushed into it or a cluster of opts
+      def handle_no_space_value(cmd, opts, args, arg)
+        name  = "-#{arg[1]}"
+        value = arg.slice(2, arg.size)
+        opt   = cmd.find_opt(name)
+
+        fail "#{name} is not a registered option" unless opt
+
+        unless opt.flag?
+          assign_opt_value(opts, opt, value, name)
+          return true
+        end
+        false
+      end
+
+      def handle_cluster(cmd, opts, arg)
+        cluster = arg.split('')
+        cluster.each do |short|
+          opt = cmd.find_opt("-#{short}")
+          unless opt.flag?
+            fail "-#{short} can not live in a cluster, it must be a flag"
+          end
+          found_opt_flag(opts, opt)
+        end
+      end
+    end
+  end
+end

data/lib/fuelcell/parser.rb

@@ -0,0 +1,4 @@
+require 'fuelcell/parser/base_handler'
+require 'fuelcell/parser/ignore_handler'
+require 'fuelcell/parser/parsing_strategy'
+require 'fuelcell/parser/cmd_args_strategy'