fuelcell 0.1.0

data/lib/fuelcell/action/opt_results.rb

@@ -0,0 +1,68 @@
+module Fuelcell
+  module Action
+    class OptResults < ::Hash
+
+      def initialize(hash = {})
+        super()
+        hash.each do |key, value|
+          self[normalize(key)] = value
+        end
+      end
+
+      def [](key)
+        super(normalize(key))
+      end
+
+      def []=(key, value)
+        super(normalize(key), value)
+      end
+
+      def delete(key)
+        super(normalize(key))
+      end
+
+      def fetch(key, *args)
+        super(normalize(key), *args)
+      end
+
+      def key?(key)
+        super(normalize(key))
+      end
+
+      def values_at(*indices)
+        indices.map { |key| self[normalize(key)] }
+      end
+
+      def merge(hash)
+        dup.merge!(hash)
+      end
+
+      def merge!(hash)
+        hash.each do |key, value|
+          self[normalize(key)] = value
+        end
+        self
+      end
+
+      def to_hash
+        Hash.new(default).merge!(self)
+      end
+
+      def respond_to?(method_name, include_private = false)
+        return key?(method_name.to_s.chomp('?')) || super
+      end
+
+      protected
+
+      def normalize(key)
+        key.is_a?(Symbol) ? key.to_s : key
+      end
+
+      def method_missing(method_name, *args, &_block)
+        name = method_name.to_s
+        return self.key?(name.chomp('?')) if name[-1] == '?'
+        return self[name]
+      end
+    end
+  end
+end

data/lib/fuelcell/action/opts_manager.rb

@@ -0,0 +1,80 @@
+module Fuelcell
+  module Action
+    # Used by the Command to manage adding option from its dsl. It is also
+    # used during option parsing to find options, add global options, or check
+    # if any required options have been missed
+    class OptsManager
+      attr_reader :options
+
+      def initialize
+        @options = {}
+      end
+
+      def each
+        options.each {|_, option| yield option }
+      end
+
+      # Check to determine if any of the options are callable, meaning do
+      # they point to another command or have a lambda to be executed
+      #
+      # @return [Hash]
+      def callable
+        list = options.select { |_, opt| opt.callable? || opt.cmd_path? }
+        _, value = list.first
+        value
+      end
+
+      def required_opts
+        options.select { |_, opt| opt.required? }
+      end
+
+      def globals
+        options.select { |_, opt| opt.global? }
+      end
+
+      def missing_opts(names)
+        missing = required_opts.keys - names
+        return [] if missing.empty?
+
+        list = options.select { |(key, _)| missing.include?(key) }.values
+        yield list if block_given?
+        list
+      end
+
+      def add(option, config = {})
+        option = create(option, config) if option.is_a?(String)
+        if options.key?(option.name)
+          fail "can not add option: duplicate exists with name #{option.name}"
+        end
+        options[option.name] = option
+      end
+      alias_method :opt, :add
+
+      def remove(name)
+        # looks like an option definition so lets use it's name
+        if name.respond_to?(:name) && options.key?(name.name)
+          return options.delete(name.name)
+        end
+
+        opt = find(name)
+        return false unless opt
+
+        options.delete(opt.name)
+      end
+
+      def find(name)
+        target = false
+        options.each do |(_, option)|
+          target = option if option.name?(name)
+        end
+        target
+      end
+      alias_method :find_opt, :find
+      alias_method :[], :find
+
+      def create(name, config = {})
+        OptDefinition.new(name, config)
+      end
+    end
+  end
+end

data/lib/fuelcell/action/root.rb

@@ -0,0 +1,76 @@
+module Fuelcell
+  module Action
+    # Top most command in the command hierarchy. The root command holds all
+    # other commands that would appear on the command line, it holds the
+    # name of the script that uses it.
+    class Root < Command
+      attr_reader :help
+
+      def initialize(name = nil)
+        name = script_name if name.nil?
+        super(name)
+        install_help
+      end
+
+      # Find any command in the root command.
+      #
+      # Using the cmd_args, which form a command hierarchy, we search for the
+      # deepest sub command first. If that it not found we assume that command
+      # arg is really a regular arg and we put it back. We do this until we
+      # reach the top command
+      #
+      # == Parameters:
+      # cmd_args <Array>::  A hierarchal list of commands to be searched
+      # remaining_args <Array>:: All remaining raw args from ARGV
+      #
+      # == Returns:
+      # <Fuelcell::Command> command object
+      def locate(cmd_args, raw_args = [])
+        return self if cmd_args.empty?
+
+        target = NotFound.new(cmd_args)
+
+        loop do
+          terms = cmd_args.dup
+          break if cmd_args.empty?
+
+          target = search(terms)
+          break unless target.is_a?(NotFound)
+
+          raw_args.unshift(cmd_args.pop)
+        end
+
+        # this must be an arg for the root command's action and not a command
+        return self if callable? && target.is_a?(NotFound)
+
+        target
+      end
+
+      def ensure_command_hierarchy(cmd_args)
+        create_tree(self, cmd_args)
+      end
+
+      private
+
+      def script_name
+        File.basename($PROGRAM_NAME, File.extname($PROGRAM_NAME))
+      end
+
+      def install_help
+        helper = callable_helper
+        command 'help' do
+          usage '[COMMAND]', 'describes subcommands or a specific command'
+          run helper
+        end
+      end
+
+      def callable_helper
+        root = self
+        lambda do |_opts, args, shell|
+          text = Fuelcell::Help.generate(root, args, shell.terminal_width)
+          shell.puts text
+        end
+      end
+    end
+  end
+end

data/lib/fuelcell/action/subcommands.rb

@@ -0,0 +1,81 @@
+module Fuelcell
+  module Action
+    module Subcommands
+      extend Forwardable
+      delegate [:empty?, :[], :each] => :subcommands
+
+      def add(cmds)
+        cmds = [cmds] unless cmds.is_a?(Array)
+        cmds.each { |cmd|  subcommands[cmd.name] = cmd }
+      end
+      alias_method :<<, :add
+
+      def [](name)
+        list = name.split(' ')
+        deep_find(self, list)
+      end
+
+      def exist?(name)
+        list   = name.split(' ')
+        result = deep_find(self, list)
+        result.is_a?(NotFound) ? false : true
+      end
+
+      # Finds a subcommand by name.
+      #
+      # @param names [Array] hierarchical order of commands
+      # @return [Fuelcell::Command] of nil when not found
+      def search(names)
+        deep_find(self, names)
+      end
+
+      # Collect global options from the option manager of every
+      # command in the Hierarchy
+      #
+      # @return [Hash]
+      def global_options
+        collect_global_options(self, {})
+      end
+
+      protected
+
+      def subcommands
+        @subcommands ||= {}
+      end
+
+      def deep_find(cmd, names)
+        return cmd if names.empty?
+
+        name = names.shift
+        unless cmd.subcommands.key?(name)
+          names.unshift name
+          return NotFound.new(names)
+        end
+        deep_find(cmd.subcommands[name], names)
+      end
+
+      def create_tree(current_cmd, tree)
+        while search_key = tree.shift
+          unless current_cmd.exist?(search_key)
+            current_cmd.command(search_key) {}
+          end
+          child = current_cmd[search_key]
+          create_tree(child, tree)
+        end
+        child
+      end
+
+      def collect_global_options(cmd, list)
+        globals = cmd.opts.globals
+        list.merge!(globals)
+
+        return list if cmd.empty?
+
+        cmd.each do |_, subcommand|
+          collect_global_options(subcommand, list)
+        end
+        list
+      end
+    end
+  end
+end

data/lib/fuelcell/action.rb

@@ -0,0 +1,11 @@
+require 'fuelcell/action/callable'
+require 'fuelcell/action/opt_definition'
+require 'fuelcell/action/arg_definition'
+require 'fuelcell/action/arg_results'
+require 'fuelcell/action/opt_results'
+require 'fuelcell/action/opts_manager'
+require 'fuelcell/action/args_manager'
+require 'fuelcell/action/subcommands'
+require 'fuelcell/action/command'
+require 'fuelcell/action/not_found'
+require 'fuelcell/action/root'

data/lib/fuelcell/cli.rb

@@ -0,0 +1,89 @@
+require 'fuelcell/shell'
+require 'fuelcell/help'
+require 'fuelcell/action'
+require 'fuelcell/parser'
+module Fuelcell
+  class Cli
+    attr_reader :root, :shell, :cmd_args_extractor, :parser
+
+    # Initializes with a root command object
+    #
+    # When nothing is given we default to the script name otherwise you choose
+    # the name of the root command or the command itself
+    #
+    def initialize(config = {})
+      @exit   = config.fetch(:exit)  { true }
+      @exit   = @exit == false ? false : true
+      @root   = config.fetch(:root)  { Action::Root.new }
+      @shell  = config.fetch(:shell) { Shell.new }
+      @parser = config.fetch(:parser) {
+        Parser::ParsingStrategy.new
+      }
+
+      @cmd_args_extractor = config.fetch(:cmd_args_extractor) {
+        Parser::CmdArgsStrategy.new
+      }
+    end
+
+    # Delegates all parsing responsiblities to a series of handlers, returning
+    # a structured hash needed to execute a command. The command being executed
+    # is determined by the CmdArgsStrategy unless you override it, it extracts
+    # all args upto the first option or ignore. The RootCommand is used to find
+    # the command using the extracted args, it accounts for sub commands. The
+    # parser Parser::ParsingStategy handles processing opts, args and ignored
+    # args
+    #
+    # @param raw_args [Array] cli args usually from ARGV
+    # @return [Hash] structured context for executing a command
+    def parse(raw_args)
+      cmd_args = cmd_args_extractor.call(raw_args)
+      cmd      = root.locate(cmd_args, raw_args)
+      root.add_global_options(cmd)
+      begin
+        parser.call(cmd, raw_args)
+      rescue Exception => e
+        shell.error e.message
+        shell.failure_exit
+      end
+    end
+
+    # Executes the callable object in a command. All command callable object
+    # expect to be called the the options hash, arg hash and shell object.
+    #
+    # @param context [Hash]
+    # @return [Integer]
+    def execute(context)
+      cmd       = context[:cmd]
+      opts      = context[:opts] || {}
+      args      = context[:args] || []
+      cli_shell = context[:shell] || shell
+
+      cmd = handle_callable_option(root, cmd)
+
+      cmd.call(opts, args, cli_shell)
+
+    end
+
+    def handle_callable_option(root, cmd)
+      opt_manager = cmd.opts
+      opt = opt_manager.callable
+      return cmd unless opt
+      return root.locate(opt.cmd_ath) if opt.cmd_path?
+      opt
+    end
+
+    def exit?
+      @exit
+    end
+
+    # Allows the system to by pass the exit call which is helpful in testing
+    # and when trying to manually control the system
+    #
+    # @param code [Int] integer from 0 .. 255 representing the exit code
+    # @return [Int] when exit is false
+    def handle_exit(code)
+      shell.exit code if exit?
+      code
+    end
+  end
+end

data/lib/fuelcell/help/base_formatter.rb

@@ -0,0 +1,24 @@
+module Fuelcell
+  module Help
+    # Hold common functionality and information needed by all formatters
+    class BaseFormatter
+      DEFAULT_WIDTH   = 80
+      DEFAULT_PADDING = 4
+      attr_reader :width, :padding, :max_width
+
+      def initialize(config = {})
+        @width     = config[:width] || DEFAULT_WIDTH
+        @padding   = config[:padding] || DEFAULT_PADDING
+        @max_width = width - padding
+      end
+
+      def short_opt(data, no_opt = '')
+        data[:short].nil? ? no_opt : "-#{data[:short]}"
+      end
+
+      def long_opt(data, no_opt = '')
+        data[:long].nil? ? no_opt : "--#{data[:long]}=#{data[:long].upcase}"
+      end
+    end
+  end
+end

data/lib/fuelcell/help/builder.rb

@@ -0,0 +1,71 @@
+module Fuelcell
+  module Help
+    class Builder
+
+      def call(root, args, help = {})
+        cmd  = args.empty? ? root : root.locate(args.raw)
+        path = args.join(' ').strip
+        build_usage(root.name, path, cmd, help)
+        build_options(cmd.opts, help)
+        build_commands(cmd, path, help)
+        build_desc(cmd, help)
+        help
+      end
+
+      # @param script_name [String] name of script you asked help from
+      # @param path [String] path of command you need help for
+      # @param cmd [Fuelcell::Action::Command] command you need help with
+      # @param data [Hash] stores the structure of the help content
+      # @return [Hash]
+      def build_usage(script_name, path, cmd, data = {})
+        usage = {}
+        usage[:label] = 'Usage:'
+        usage[:path]  = "#{script_name} #{path}".strip
+        usage[:text]  = cmd.usage.nil? ? '' : cmd.usage
+        usage[:args]  = []
+        usage[:opts]  = []
+
+        cmd.opts.required_opts.each do |(_, opt)|
+          usage[:opts] << common_opt_data(opt)
+        end
+
+        data[:usage] = usage
+        data
+      end
+
+      def build_options(opt_manager, data = {})
+        options = []
+        opt_manager.each do |opt|
+          next if opt.required?
+          options << common_opt_data(opt).merge!(banner: opt.banner)
+        end
+
+        data[:options] = options
+        data
+      end
+
+      def build_commands(cmd, path, data = {})
+        data[:commands] = []
+        cmd.each do |_, command|
+          data[:commands] << {
+            name: command.name,
+            path: path,
+            desc: command.desc || ''
+          }
+        end
+        data
+      end
+
+      def build_desc(cmd, data = {})
+        data[:desc] = cmd.desc
+        data
+      end
+
+      protected
+
+      def common_opt_data(opt)
+        { short: opt.short, long: opt.long, type: opt.type }
+      end
+    end
+  end
+end

data/lib/fuelcell/help/cmds_formatter.rb

@@ -0,0 +1,57 @@
+module Fuelcell
+  module Help
+    class CmdsFormatter < BaseFormatter
+      attr_reader :indent, :desc_space
+      def initialize(config = {})
+        super
+        @indent     = (config[:indent] || 2).to_i
+        @desc_space = (config[:banner_space] || 2).to_i
+      end
+
+      def call(data)
+        return '' if empty?(data)
+        str    = "Commands:\n"
+        widest = widest_cmd(data[:commands])
+        data[:commands].each do |cmd|
+          str << line(cmd[:name], widest, cmd[:desc])
+        end
+        str
+      end
+
+      def line(cmd, widest_cmd, desc)
+        max          = indent + desc_space + widest_cmd
+        desc         = wrap(desc || '', max)
+        pad          = create_padding(widest_cmd, cmd)
+        indent_str   = ' ' * indent
+        column_space = ' ' * desc_space
+        "#{indent_str}#{cmd}#{pad}#{column_space}# #{desc}\n"
+      end
+
+      def create_padding(widest, cmd)
+        ' ' * (widest - cmd.size)
+      end
+
+      def empty?(data)
+        !data.key?(:commands) || data[:commands].empty?
+      end
+
+      def wrap(text, widest_text)
+        return text if (widest_text + text.size) < max_width
+
+        pad = ' ' * widest_text
+        pattern = /(.{1,#{max_width - widest_text}})(\s+|$)/
+        text = text.gsub(pattern, "\\1\n#{pad}# ")
+        text.gsub(/# $/, '').strip
+      end
+
+      def widest_cmd(commands)
+        max = 0
+        commands.each do |data|
+          size = data[:name].size
+          max  = size if size > max
+        end
+        max
+      end
+    end
+  end
+end

data/lib/fuelcell/help/desc_formatter.rb

@@ -0,0 +1,21 @@
+module Fuelcell
+  module Help
+    class DescFormatter < BaseFormatter
+
+      def call(data)
+        return '' if empty?(data)
+        wrap(data[:long_desc] || data[:desc]) + "\n"
+      end
+
+      def wrap(text)
+        pattern = /(.{1,#{max_width}})(\s+|$)/
+        text.gsub(pattern, "\\1\n").strip
+      end
+
+      def empty?(data)
+        (!data.key?(:desc) || data[:desc].to_s.empty?) &&
+          (!data.key?(:long_desc) || data[:long_desc].to_s.empty?)
+      end
+    end
+  end
+end

data/lib/fuelcell/help/opts_formatter.rb

@@ -0,0 +1,62 @@
+module Fuelcell
+  module Help
+    class OptsFormatter < BaseFormatter
+      attr_reader :indent, :banner_space
+      def initialize(config = {})
+        super
+        @indent       = (config[:indent] || 2).to_i
+        @banner_space = (config[:banner_space] || 2).to_i
+      end
+
+      def call(data)
+        return '' if empty?(data)
+
+        str    = "Options:\n"
+        widest = widest_opt(data[:options])
+        data[:options].each do |opt|
+          opt, banner = opt_data(opt)
+          str << line(opt, widest, banner)
+        end
+        str
+      end
+
+      def line(opt, widest_opt, banner_text)
+        max          = indent + banner_space + widest_opt
+        banner       = wrap(banner_text, max)
+        pad          = create_padding(widest_opt, opt)
+        indent_str   = ' ' * indent
+        column_space = ' ' * banner_space
+        "#{indent_str}#{opt}#{pad}#{column_space}#{banner}\n"
+      end
+
+      def create_padding(widest, opt)
+        ' ' * (widest - opt.size)
+      end
+
+      def empty?(data)
+        !data.key?(:options) || data[:options].empty?
+      end
+
+      def wrap(text, widest_text)
+        return text if (widest_text + text.size) < max_width
+
+        pad = ' ' * widest_text
+        pattern = /(.{1,#{max_width - widest_text}})(\s+|$)/
+        text.gsub(pattern, "\\1\n#{pad}").strip
+      end
+
+      def widest_opt(options)
+        max = 0
+        options.each do |data|
+          size = "#{short_opt(data, '  ')} #{long_opt(data)}".size
+          max  = size if size > max
+        end
+        max
+      end
+
+      def opt_data(data)
+        ["#{short_opt(data, '  ')} #{long_opt(data)}", data[:banner] || '']
+      end
+    end
+  end
+end