class ActionCommand::InputOutput

A static description of the input and output from a given command. Although adding this adds a bunch of documentation and validation, it is not required. If you don’t want to specify your input and output, you can just access the hash you passed into the command as @params

Constants

OPTIONAL

shorthand to indicate the parameter is optional.

Attributes

desc[R]

Returns the description for this command.

Public Class Methods

new(action, desc) click to toggle source

Do not use this. Instead, implment self.describe_io in your command subclass, and call the method ActionCommand#self.describe_io from within it, returning its result.

# File lib/action_command/input_output.rb, line 14
def initialize(action, desc)
  @action = action
  @desc = desc
  @input = []
  @output = []

  # universal parameters.
  # input(:help, 'Help on this command', OPTIONAL)
end

Public Instance Methods

help?(args) click to toggle source
# File lib/action_command/input_output.rb, line 110
def help?(args)
  first_arg_sym = @input.first[:symbol]
  first_arg_val = args[first_arg_sym]
  return first_arg_val == 'help'
end
input(sym, desc, opts = {}, &_block) click to toggle source

Defines input for a command @param sym [Symbol] symbol identifying the parameter @param desc [String] description for use by internal developers, or on a rake task with

rake your_task_name[help]

@param opts Optional arguments.

# File lib/action_command/input_output.rb, line 129
def input(sym, desc, opts = {}, &_block)
  insert_io(@input, sym, desc, opts)
end
input_count() click to toggle source

the number of input parameters for this command.

# File lib/action_command/input_output.rb, line 25
def input_count
  return @input.length
end
keys() click to toggle source

@return an array with the set of parameter symbols this command accepts.

# File lib/action_command/input_output.rb, line 143
def keys 
  @input.collect { |p| p[:symbol] }
end
output(sym, desc, opts = {}) click to toggle source

Defines output for a command @param sym [Symbol] symbol identifying the parameter @param desc [String] description for use by internal developers, or on a rake task with

rake your_task_name[help]

@param opts Optional arguments.

# File lib/action_command/input_output.rb, line 138
def output(sym, desc, opts = {})
  insert_io(@output, sym, desc, opts)
end
print_output(result) click to toggle source

print out the defined output of the command

process_input(dest, args) click to toggle source

Goes through, and assigns the value for each declared parameter to an accessor with the same name, validating that required parameters are not missing

# File lib/action_command/input_output.rb, line 55
def process_input(dest, args)
  # pass down predefined attributes.
  dest.parent = args[:parent]
  dest.test   = args[:test]
  
  return unless validate_input(dest, args)

  @input.each do |param|
    sym = param[:symbol]
    if args.key? sym
      sym_assign = "#{sym}=".to_sym
      dest.send(sym_assign, args[sym])      
    end
  end
end
process_output(dest, result) click to toggle source

Goes through, and makes sure that required output parameters exist

# File lib/action_command/input_output.rb, line 72
def process_output(dest, result)
  return unless result.ok? && should_validate(dest)

  @output.each do |param|
    sym = param[:symbol]
    unless result.key?(sym)
      opts = param[:opts]
      raise ArgumentError, "Missing required value #{sym} in output" unless opts[:optional]
    end
  end
end
rake_input(rake_arg) click to toggle source

convert rake task arguments to a standard hash.

# File lib/action_command/input_output.rb, line 85
def rake_input(rake_arg)
  params = {}
  rake_arg.each do |key, val| 
    params[key] = val
  end
  # by default, use human logging if a logger is enabled.
  params[:logger] = Logger.new(STDOUT) unless params.key?(:logger)
  params[:log_format] = :human unless params.key?(:log_format)
  
  return params
end
should_validate(dest) click to toggle source

@param dest [ActionCommand::Executable] the executable in question @return true if the executable is not in a testing context.

# File lib/action_command/input_output.rb, line 31
def should_validate(dest)
  return dest.test_context?
end
show_help() click to toggle source

displays the help for this command

# File lib/action_command/input_output.rb, line 117
def show_help
  puts "#{@action.name}: #{desc}"
  print_params('Input', @input)
  print_params('Output', @output)
end
validate_input(dest, args) click to toggle source

Validates that the specified parameters are valid for this input description. @param args [Hash] the arguments to validate

# File lib/action_command/input_output.rb, line 37
def validate_input(dest, args)
  return true unless should_validate(dest)
  @input.each do |p|
    val = args[p[:symbol]]
  
    # if the argument has a value, no need to test whether it is optional.
    next unless !val || val == '*' || val == ''
  
    opts = p[:opts]
    unless opts[:optional]
      raise ArgumentError, "You must specify the required input #{p[:symbol]}"
    end
  end
  return true
end

Private Instance Methods

insert_io(dest, sym, desc, opts) click to toggle source
# File lib/action_command/input_output.rb, line 158
def insert_io(dest, sym, desc, opts)
  dest << { symbol: sym, desc: desc, opts: opts }
end
print_params(title, vals) click to toggle source