Class Boson::Command

  1. lib/boson/command.rb
Parent: Object

A command starts with the functionality of a ruby method and adds benefits with options, render_options, etc.

Constants

ATTRIBUTES = [:name, :lib, :alias, :desc, :options, :args, :config]

Attributes

all_option_commands [RW]

Public class methods

create (name, library)

Creates a command given its name and a library.

[show source] 
# File lib/boson/command.rb, line 7
    def self.create(name, library)
      obj = new(new_attributes(name, library))
      if @all_option_commands && !%w{get method_missing}.include?(name)
        obj.make_option_command(library)
      end
      obj
    end
find (command, commands=Boson.commands)

Finds a command, namespaced or not and aliased or not. If found returns the command object, otherwise returns nil.

[show source] 
# File lib/boson/command.rb, line 22
    def self.find(command, commands=Boson.commands)
      command, subcommand = command.to_s.split(NAMESPACE, 2)
      is_namespace_command = lambda {|current_command|
        [current_command.name, current_command.alias].include?(subcommand) &&
        current_command.library && (current_command.library.namespace == command)
      }
      find_lambda = subcommand ? is_namespace_command : lambda {|e| [e.name, e.alias].include?(command)}
      commands.find(&find_lambda)
    end
new (attributes)

A hash of attributes which map to instance variables and values. :name and :lib are required keys.

Attributes that can be configured:

:desc
Description that shows up in command listings
:alias
Alternative name for command
:options
Hash of options passed to OptionParser
:render_options
Hash of rendering options to pass to OptionParser. If the key :output_class is passed, that class’s Hirb config will serve as defaults for this rendering hash.
:option_command
Boolean to wrap a command with an OptionCommand object i.e. allow commands to have options.
:args
Should only be set if not automatically set. This attribute is only important for commands that have options/render_options. Its value can be an array (as ArgumentInspector.scrape_with_eval produces), a number representing the number of arguments or ’*’ if the command has a variable number of arguments.
:default_option
Only for an option command that has one or zero arguments. This treats the given option as an optional first argument. Example: 
# For a command with default option 'query' and options --query and -v
'some -v'   -> '--query=some -v'
'-v'        -> '-v'
:config
A hash for third party libraries to get and set custom command attributes.
[show source] 
# File lib/boson/command.rb, line 54
    def initialize(attributes)
      hash = attributes.dup
      @name = hash.delete(:name) or raise ArgumentError
      @lib = hash.delete(:lib) or raise ArgumentError
      [:alias, :desc, :options, :namespace, :default_option, :option_command].each do |e|
          instance_variable_set("@#{e}", hash.delete(e)) if hash.key?(e)
      end

      if hash[:render_options] && (@render_options = hash.delete(:render_options))[:output_class]
        @render_options = Util.recursive_hash_merge View.class_config(@render_options[:output_class]), @render_options
      end

      if (args = hash.delete(:args))
        if args.is_a?(Array)
          @args = args
        elsif args.to_s[/^\d+/]
          @arg_size = args.to_i
        elsif args == '*'
          @args = [['*args']]
        end
      end
      @config = Util.recursive_hash_merge hash, hash.delete(:config) || {}
    end
new_attributes (name, library)

Used to generate a command’s initial attributes when creating a command object

[show source] 
# File lib/boson/command.rb, line 16
    def self.new_attributes(name, library)
      (library.commands_hash[name] || {}).merge({:name=>name, :lib=>library.name, :namespace=>library.namespace})
    end

Public instance methods

args (lib=library)

Array of array args with optional defaults. Scraped with ArgumentInspector.

[show source] 
# File lib/boson/command.rb, line 84
    def args(lib=library)
      @args = !@args.nil? ? @args : begin
        if lib
          file_string, meth = file_string_and_method_for_args(lib)
          (file_string && meth && (@file_parsed_args = true) &&
            ArgumentInspector.scrape_with_text(file_string, meth))
        end || false
      end
    end
full_name ()

Full name is only different than name if a command has a namespace. The full name should be what you would type to execute the command.

[show source] 
# File lib/boson/command.rb, line 123
    def full_name
      @namespace ? "#{@namespace}.#{@name}" : @name
    end
library ()

Library object a command belongs to.

[show source] 
# File lib/boson/command.rb, line 79
    def library
      @library ||= Boson.library(@lib)
    end
option_help ()

Help string for options if a command has it.

[show source] 
# File lib/boson/command.rb, line 105
    def option_help
      @options ? option_parser.to_s : ''
    end
option_parser ()

Option parser for command as defined by @options.

[show source] 
# File lib/boson/command.rb, line 95
    def option_parser
      @option_parser ||= OptionParser.new(@options || {})
    end
render_option_parser ()

Option parser for command as defined by @render_options.

[show source] 
# File lib/boson/command.rb, line 100
    def render_option_parser
      option_command? ? Boson::Scientist.option_command(self).option_parser : nil
    end
usage ()

Usage string for command, created from options and args.

[show source] 
# File lib/boson/command.rb, line 110
    def usage
      return '' if options.nil? && args.nil?
      usage_args = args && @options && !has_splat_args? ?
        (@default_option ? [[@default_option.to_s, @file_parsed_args ? ''.inspect : '']] + args[0..-2] :
        args[0..-2]) : args
      str = args ? usage_args.map {|e|
        (e.size < 2) ? "[#{e[0]}]" : "[#{e[0]}=#{@file_parsed_args ? e[1] : e[1].inspect}]"
      }.join(' ') : '[*unknown]'
      str + option_help
    end