Class: Rubikon::Command

Inherits:
Object show all
Includes:
HasArguments
Defined in:
lib/rubikon/command.rb

Overview

Instances of the Command class are used to define the real code that should be executed when running the Application.

See Also:

Author:

  • Sebastian Staudt

Since:

  • 0.3.0

Constant Summary

Constants included from HasArguments

HasArguments::ARGUMENT_MATCHERS

Instance Attribute Summary collapse

Attributes included from Parameter

#aliases, #name

Instance Method Summary collapse

Methods included from HasArguments

#[], #args

Methods included from Parameter

#active?

Constructor Details

#initialize(app, name, *options, &block) ⇒ Command

Create a new application command with the given name with a reference to the app it belongs to

Parameters:

  • app (Application::Base) —

    The application this command belongs to

  • name (Symbol, #to_sym) —

    The name of this command, used in application arguments

  • block (Proc) —

    The code block which should be executed by this command

  • options (Array) —

    A range allows any number of arguments inside the limits of the range or array (-1 stands for an arbitrary number of arguments). A positive number indicates the exact amount of required arguments while a negative argument count indicates the amount of required arguments, but allows additional, optional arguments. A argument count of 0 means there are no required arguments, but it allows optional arguments. An array of symbols enables named arguments where the argument count is the size of the array and each argument is named after the corresponding symbol. Finally a hash may be used to specify options for named arguments. The keys of the hash will be the names of the arguments and the values are options for this argument. You may specify multiple options as an array. Possible options are:

    • :optional makes the argument optional

    • :remainder makes the argument take all remaining arguments as an array

    • One or more strings will cause the argument to be checked to be equal to one of the strings

    • One or more regular expressions will cause the argument to be checked to match one of the expressions

    • Other symbols may reference to a predefined regular expression from HasArguments::ARGUMENT_MATCHERS

Raises:

  • (ArgumentError) —

    if the given application object isn’t a Rubikon application

  • (BlockMissingError) —

    if no command code block is given and a command file does not exist

Since:

  • 0.3.0



44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/rubikon/command.rb', line 44

def initialize(app, name, *options, &block)
  super

  @params = {}

  if block_given?
    @block = block
  else
    @file_name = "#{@app.path}/commands/#{name}.rb"
    raise BlockMissingError unless File.exists?(@file_name)
    code = open(@file_name).read
    @block = Proc.new { instance_eval(code) }
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args, &block) ⇒ Object (private)

If a parameter with the specified method name exists, a call to that method will return the value of the parameter.

Examples:

option :user, [:who]
command :hello, [:mood] do
  puts "Hello #{user.who}"
  puts "I feel #{mood}"
end

Since:

  • 0.3.0



177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/rubikon/command.rb', line 177

def method_missing(name, *args, &block)
  if args.empty? && !block_given?
    if @params.key?(name)
      return @params[name]
    else
      active_params.each do |param|
        return param.send(name) if param.respond_to_missing?(name)
      end
    end
  end

  super
end

Instance Attribute Details

#description ⇒ String

Returns The description of this command.

Returns:

  • (String) —

    The description of this command

Since:

  • 0.3.0



25
26
27
 
# File 'lib/rubikon/command.rb', line 25

def description
  @description
end

#params ⇒ Array<Parameter> (readonly) Also known as: parameters

Returns The parameters of this command.

Returns:

  • (Array<Parameter>) —

    The parameters of this command

Since:

  • 0.3.0



28
29
30
 
# File 'lib/rubikon/command.rb', line 28

def params
  @params
end

Instance Method Details

#active_params ⇒ Array<Parameter> (private)

Returns all parameters of this command that are active, i.e. that have been supplied on the command-line

Returns:

  • (Array<Parameter>) —

    All currently active parameters of this command

Since:

  • 0.6.0



130
131
132
 
# File 'lib/rubikon/command.rb', line 130

def active_params
  @params.values.select { |param| param.active? }
end

#add_param(parameter) ⇒ Object (private)

Add a new parameter for this command

Parameters:

  • parameter (Parameter, Hash) —

    The parameter to add to this command. This might also be a Hash where every key will be an alias to the corresponding value, e.g. { :alias => :parameter }.

See Also:

Since:

  • 0.3.0



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/rubikon/command.rb', line 141

def add_param(parameter)
  if parameter.is_a? Hash
    parameter.each do |alias_name, name|
      alias_name = alias_name.to_sym
      name = name.to_sym
      parameter = @params[name]
      if parameter.nil?
        @params[alias_name] = name
      else
        parameter.aliases << alias_name
        @params[alias_name] = parameter
      end
    end
  else
    raise ArgumentError unless parameter.is_a? Parameter
    @params.each do |name, param|
      if param == parameter.name
        parameter.aliases << name
        @params[name] = parameter
      end
    end
    @params[parameter.name] = parameter
  end
end

#help(show_usage = true) ⇒ String

Generate help for this command

Parameters:

  • show_usage (Boolean) (defaults to: true) —

    If true, the returned String will also include usage information

Returns:

  • (String) —

    The contents of the help screen for this command

Since:

  • 0.6.0



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/rubikon/command.rb', line 65

def help(show_usage = true)
  help = ''

  if show_usage
    help << " #{name}" if name != :__default

    @params.values.uniq.sort_by {|a| a.name.to_s }.each do |param|
      help << ' ['
      ([param.name] + param.aliases).each_with_index do |name, index|
        name = name.to_s
        help << '|' if index > 0
        help << '-' if name.size > 1
        help << "-#{name}"
      end
      help << ' ...' if param.is_a?(Option)
      help << ']'
    end
  end

  help << "\n\n#{description}" unless description.nil?

  help_flags = {}
  help_options = {}
  params.each_value do |param|
    if param.is_a? Flag
      help_flags[param.name.to_s] = param
    else
      help_options[param.name.to_s] = param
    end
  end

  param_name = lambda { |name| "#{name.size > 1 ? '-' : ' '}-#{name}" }
  unless help_flags.empty? && help_options.empty?
    max_param_length = (help_flags.keys + help_options.keys).
      max_by { |a| a.size }.size + 2
  end

  unless help_flags.empty?
    help << "\n\nFlags:"
    help_flags.sort_by { |name, param| name }.each do |name, param|
      help << "\n  #{param_name.call(name).ljust(max_param_length)}"
      help << "      #{param.description}" unless param.description.nil?
    end
  end

  unless help_options.empty?
  help << "\n\nOptions:\n"
    help_options.sort_by { |name, param| name }.each do |name, param|
      help << "  #{param_name.call(name).ljust(max_param_length)} ..."
      help << "  #{param.description}" unless param.description.nil?
      help << "\n"
    end
  end

  help
end

#reset ⇒ Object (private)

Resets this command to its initial state

See Also:

  • HasArguments#reset

Since:

  • 0.4.0



195
196
197
198
199
200
 
# File 'lib/rubikon/command.rb', line 195

def reset
  super
  @params.values.uniq.each do |param|
    param.send(:reset) if param.is_a? Parameter
  end
end

#respond_to_missing?(name, include_private = false) ⇒ Boolean (private)

Checks whether a parameter with the given name exists for this command

This is used to determine if a method call would successfully return the value of a parameter.

Returns:

  • (Boolean) —

    true if named parameter with the specified name exists

See Also:

Since:

  • 0.3.0



209
210
211
212
213
 
# File 'lib/rubikon/command.rb', line 209

def respond_to_missing?(name, include_private = false)
  @params.key?(name) ||
  active_params.any? { |param| param.respond_to_missing?(name) } ||
  super
end

#run ⇒ Object (private)

Run this command’s code block

Since:

  • 0.3.0



216
217
218
219
220
 
# File 'lib/rubikon/command.rb', line 216

def run
  check_args
  Application::InstanceMethods.instance_method(:sandbox).bind(@app).call.
    instance_eval(&@block)
end