Class: ActionCommand::InputOutput

Inherits:
Object
  • Object
show all
Defined in:
lib/action_command/input_output.rb

Overview

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

Constant Summary collapse

OPTIONAL =

shorthand to indicate the parameter is optional.

{ optional: true }.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(action, desc) ⇒ InputOutput

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.



14
15
16
17
18
19
20
21
22
 
# 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

Instance Attribute Details

#desc ⇒ Object (readonly)

Returns the description for this command.



107
108
109
 
# File 'lib/action_command/input_output.rb', line 107

def desc
  @desc
end

Instance Method Details

#help?(args) ⇒ Boolean

Returns:

  • (Boolean) 


110
111
112
113
114
 
# 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) ⇒ Object

Defines input for a command

Parameters:

  • sym (Symbol) —

    symbol identifying the parameter

  • desc (String) —

    description for use by internal developers, or on a rake task with rake your_task_name

  • opts (defaults to: {}) —

    Optional arguments.



129
130
131
 
# File 'lib/action_command/input_output.rb', line 129

def input(sym, desc, opts = {}, &_block)
  insert_io(@input, sym, desc, opts)
end

#input_count ⇒ Object

the number of input parameters for this command.



25
26
27
 
# File 'lib/action_command/input_output.rb', line 25

def input_count
  return @input.length
end

#keys ⇒ Object

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

Returns:

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



143
144
145
 
# File 'lib/action_command/input_output.rb', line 143

def keys 
  @input.collect { |p| p[:symbol] }
end

#output(sym, desc, opts = {}) ⇒ Object

Defines output for a command

Parameters:

  • sym (Symbol) —

    symbol identifying the parameter

  • desc (String) —

    description for use by internal developers, or on a rake task with rake your_task_name

  • opts (defaults to: {}) —

    Optional arguments.



138
139
140
 
# File 'lib/action_command/input_output.rb', line 138

def output(sym, desc, opts = {})
  insert_io(@output, sym, desc, opts)
end

#print_output(result) ⇒ Object

print out the defined output of the command



98
99
100
101
102
103
104
 
# File 'lib/action_command/input_output.rb', line 98

def print_output(result)
  @output.each do |param|
    sym = param[:symbol]
    puts "#{sym}: #{result[sym]}"
  end
  
end

#process_input(dest, args) ⇒ Object

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



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# 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) ⇒ Object

Goes through, and makes sure that required output parameters exist



72
73
74
75
76
77
78
79
80
81
82
 
# 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) ⇒ Object

convert rake task arguments to a standard hash.



85
86
87
88
89
90
91
92
93
94
95
 
# 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) ⇒ Object

Returns true if the executable is not in a testing context.

Parameters:

Returns:

  • true if the executable is not in a testing context.



31
32
33
 
# File 'lib/action_command/input_output.rb', line 31

def should_validate(dest)
  return dest.test_context?
end

#show_help ⇒ Object

displays the help for this command



117
118
119
120
121
 
# 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) ⇒ Object

Validates that the specified parameters are valid for this input description.

Parameters:

  • args (Hash) —

    the arguments to validate



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# 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