Module: Rubycom

Defined in:
lib/rubycom.rb,
lib/rubycom/helpers.rb,
lib/rubycom/sources.rb,
lib/rubycom/version.rb,
lib/rubycom/executor.rb,
lib/rubycom/yard_doc.rb,
lib/rubycom/arg_parse.rb,
lib/rubycom/completions.rb,
lib/rubycom/error_handler.rb,
lib/rubycom/output_handler.rb,
lib/rubycom/command_interface.rb,
lib/rubycom/parameter_extract.rb,
lib/rubycom/singleton_commands.rb,
lib/rubycom/base_inclusion_runner.rb

Overview

Upon inclusion in another Module, Rubycom will attempt to call a method in the including module by parsing ARGV for a method name and a list of arguments. If found Rubycom will call the method specified in ARGV with the parameters parsed from the remaining arguments If a Method match can not be made, Rubycom will print help instead by parsing code comments from the including module.

Defined Under Namespace

Modules: ArgParse, BaseInclusionRunner, CommandInterface, Completions, ErrorHandler, Executor, Helpers, OutputHandler, ParameterExtract, SingletonCommands, Sources, YardDoc Classes: ArgParseError, ExecutorError, ParameterExtractError, RubycomError

Constant Summary collapse

VERSION = 
"0.4.3"

Class Method Summary collapse

Class Method Details

.included(base) ⇒ Object

Detects that Rubycom was included in another module and calls Rubycom#run

Parameters:

  • base (Module) —

    the module which invoked ‘include Rubycom’



38
39
40
 
# File 'lib/rubycom.rb', line 38

def self.included(base)
  Rubycom::BaseInclusionRunner.run(caller, Rubycom.public_method(:run), base, ARGV)
end

.process(base, args = [], steps = {}) ⇒ Object

Calls the given steps with the required parameters and ordering to locate and call a method on base or one of it’s included modules. This method expresses a procedure and calls the methods in steps to execute each step in the procedure. If not overridden in steps, then method called for each step will be determined by the return from #step_methods.

:arguments, :discover, :documentation, :source, :parameters, :executor, :output, :interface, :error matched to parameters by the :parameters method

Parameters:

  • base (Module) —

    the Module containing the Method or sub Module to run

  • args (Array) (defaults to: []) —

    a String Array representing the command to run followed by arguments to be passed

  • steps (Hash) (defaults to: {}) —

    should have the following keys mapped to Methods or Procs which will be called by the process method

Returns:

  • (Object) —

    the result of calling the method selected by the :discover method using the args from the :arguments method



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/rubycom.rb', line 103

def self.process(base, args=[], steps={})
  steps = self.step_methods.merge(steps)

  parsed_command_line = steps[:arguments].call(args)
  command = steps[:discover].call(base, parsed_command_line)
  begin
    command_doc = steps[:documentation].call(command, steps[:source])
    parameters = steps[:parameters].call(command, parsed_command_line, command_doc)
    command_result = steps[:executor].call(command, parameters)
    steps[:output].call(command_result)
  rescue RubycomError => e
    cli_output = steps[:interface].call(command, command_doc)
    steps[:error].call(e, cli_output)
  end
  command_result
end

.run(base, args = []) ⇒ Object

Main entry point for Rubycom. Uses #run_command to discover and run commands

Parameters:

  • base (Module) —

    this will be used to determine available commands

  • args (Array) (defaults to: []) —

    a String Array representing the command to run followed by arguments to be passed

Returns:

  • (Object) —

    the result of calling #run_command! or a String representing a default help message



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/rubycom.rb', line 47

def self.run(base, args=[])
  begin
    raise RubycomError, "base should should not be nil" if base.nil?
    case args[0]
      when 'register_completions'
        puts Rubycom::Completions.register_completions(base)
      when 'tab_complete'
        puts Rubycom::Completions.tab_complete(base, args, Rubycom::SingletonCommands)
      when 'help'
        help_topic = args[1]
        if help_topic == 'register_completions'
          puts "Usage: #{base} register_completions"
        elsif help_topic == 'tab_complete'
          usage = "Usage: #{base} tab_complete <word>\nParameters:\n  [String] word the word or partial word to find matches for"
          puts usage
          return usage
        else
          self.run_command(base, (args[1..-1] << '-h'))
          $stderr.puts <<-END.gsub(/^ {12}/, '')
          Default Commands:
            help                 - prints this help page
            register_completions - setup bash tab completion
            tab_complete         - print a list of possible matches for a given word
          END
        end
      else
        self.run_command(base, args)
    end
  rescue RubycomError => e
    $stderr.puts e
  end
end

.run_command(base, args = [], steps = {}, process = Rubycom.public_method(:process)) ⇒ Object

Calls the given process method with the given base, args, and steps.

:arguments, :discover, :documentation, :source, :parameters, :executor, :output, :interface, :error matched to parameters by the :parameters method

Parameters:

  • base (Module) —

    the Module containing the Method or sub Module to run

  • args (Array) (defaults to: []) —

    a String Array representing the command to run followed by arguments to be passed

  • steps (Hash) (defaults to: {}) —

    should have the following keys mapped to Methods or Procs which will be called by the process method

  • process (Method|Proc) (defaults to: Rubycom.public_method(:process)) —

    a Method or Proc which calls the step_methods in order to parse args and run a command on base

Returns:

  • (Object) —

    the result of calling the method selected by the :discover method using the args from the :arguments method



89
90
91
 
# File 'lib/rubycom.rb', line 89

def self.run_command(base, args=[], steps={}, process=Rubycom.public_method(:process))
  process.call(base, args, steps)
end

.step_methods ⇒ Hash

Convenience call for use with #process when the default Rubycom functionality is required.

to the default methods which carry out the step referred to by the key.

Returns:

  • (Hash) —

    mapping :arguments, :discover, :documentation, :source, :parameters, :executor, :output, :interface, :error



124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/rubycom.rb', line 124

def self.step_methods()
  {
      arguments: Rubycom::ArgParse.public_method(:parse_command_line),
      discover: Rubycom::SingletonCommands.public_method(:discover_command),
      documentation: Rubycom::YardDoc.public_method(:document_command),
      source: Rubycom::Sources.public_method(:source_command),
      parameters: Rubycom::ParameterExtract.public_method(:extract_parameters),
      executor: Rubycom::Executor.public_method(:execute_command),
      output: Rubycom::OutputHandler.public_method(:process_output),
      interface: Rubycom::CommandInterface.public_method(:build_interface),
      error: Rubycom::ErrorHandler.public_method(:handle_error)
  }
end