Class: Sprout::Executable::Param

Inherits:
Object
  • Object
show all
Defined in:
lib/sprout/executable/param.rb

Overview

The abstract base class for all Executable parameters.

This class provides a variety of template methods and general functionality to the different executable parameter types.

Many of these parameter attributes are exposed to Sprout::Executable concrete classes as the options hash like:

class Foo
  include Sprout::Executable

  add_param :name, String, :hidden_name => true
end

See Also:

Direct Known Subclasses

Boolean, FileParam, Files, Number, Path, StringParam, Strings

Constant Summary

DEFAULT_DELIMITER =

Default value for the delimiter that will separate parameter names from their values.

'='
DEFAULT_OPTION_PARSER_TYPE_NAME =

Defaut TYPE assumed for parameters when creating documentation for the OptionParser.

'STRING'
DEFAULT_PREFIX =

Default value for the parameter prefix. Should usually be pulled from the belongs_to Sprout::Executable.

'--'
DEFAULT_SHORT_PREFIX =

Default prefix for truncated parameters. Should usually be pulled from the belongs_to Sprout::Executable.

'-'

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Param) initialize

Default constructor for Params, if you create a new concrete type, be sure to call super() in your own constructor.



234
235
236
237
238
239
240
 
# File 'lib/sprout/executable/param.rb', line 234

def initialize
  @description             = 'Default Description'
  @hidden_value            = false
  @hidden_name             = false
  @delimiter               = DEFAULT_DELIMITER
  @option_parser_type_name = DEFAULT_OPTION_PARSER_TYPE_NAME
end

Instance Attribute Details

- (Object) belongs_to

The Sprout::Executable that this parameter instance belongs to.



60
61
62
 
# File 'lib/sprout/executable/param.rb', line 60

def belongs_to
  @belongs_to
end

- (Object) delimiter

Executable::Params join their name/value pair with an equals sign by default, this can be modified To a space or whatever you wish.



66
67
68
 
# File 'lib/sprout/executable/param.rb', line 66

def delimiter
  @delimiter
end

- (Object) description

The String description that will be used for RDoc documentation and user help.



71
72
73
 
# File 'lib/sprout/executable/param.rb', line 71

def description
  @description
end

- (Object) file_expression 



371
372
373
 
# File 'lib/sprout/executable/param.rb', line 371

def file_expression
  @file_expression ||= belongs_to.default_file_expression
end

- (Object) hidden_name

Boolean value that hides the name parameter from the shell execution.

add_param :name, String, :hidden_name => true

Without this option, the above parameter would serialize to the process like:

foo --name=Value

But with this option, the above parameter would serialize to the process like:

foo Value


89
90
91
 
# File 'lib/sprout/executable/param.rb', line 89

def hidden_name
  @hidden_name
end

- (Object) hidden_value

Boolean value that hides the value parameter from the shell execution.

add_param :visible, Boolean, :hidden_value => true

Without this option, the above parameter would serialize to the process like:

foo --visible=true

But with this option, the above parameter would serialize to the process like:

foo --visible


107
108
109
 
# File 'lib/sprout/executable/param.rb', line 107

def hidden_value
  @hidden_value
end

- (Object) name

The String (or Symbol) name of the parameter.



111
112
113
 
# File 'lib/sprout/executable/param.rb', line 111

def name
  @name
end

- (Object) prefix

Leading character for each parameter Can sometimes be an empty string, other times it's a double dash '--' but usually it's just a single dash '-'



121
122
123
 
# File 'lib/sprout/executable/param.rb', line 121

def prefix
  @prefix ||= (belongs_to.nil?) ? DEFAULT_PREFIX : belongs_to.default_prefix
end

- (Object) reader

A Symbol that refers to a method that will return the expected value when called. This method can be private.

add_param :visible, Boolean, :reader => :get_visible

def get_visible
  return @visible
end


133
134
135
 
# File 'lib/sprout/executable/param.rb', line 133

def reader
  @reader
end

- (Object) required

Boolean value that will cause a Sprout::Errors::UsageError if the executable is invoked without this parameter first being set.

add_param :visible, Boolean :required => true

Default false



144
145
146
 
# File 'lib/sprout/executable/param.rb', line 144

def required
  @required
end

- (Object) shell_name 



375
376
377
 
# File 'lib/sprout/executable/param.rb', line 375

def shell_name
  @shell_name ||= prefix + name.to_s.split('_').join('-')
end

- (Object) short_name

The short name for this parameter. If it's not explicitly, the first character of the parameter name will be used. When multiple parameters have the same first character, the first one encountered will win.



356
357
358
 
# File 'lib/sprout/executable/param.rb', line 356

def short_name
  @short_name ||= name.to_s.split('').shift
end

- (Object) to_shell_proc

An optional Proc that should be called when this parameter is serialized to shell output. The Proc should return a String value that makes sense to the underlying process.

add_param :visible, Boolean, :to_shell_proc => Proc.new {|p| "---result" }


153
154
155
 
# File 'lib/sprout/executable/param.rb', line 153

def to_shell_proc
  @to_shell_proc
end

- (Object) type

The data type of the parameter, used to generate more appropriate RDoc content for the concrete Sprout::Executable.



158
159
160
 
# File 'lib/sprout/executable/param.rb', line 158

def type
  @type
end

- (Object) value

The value that was assigned to this parameter when the concrete Sprout::Executable was instantiated and configured.



163
164
165
 
# File 'lib/sprout/executable/param.rb', line 163

def value
  @value
end

- (Object) writer

A Symbol that refers to a method (not accessor) that will be called when the value is set. This method is not responsible for actually storing the value, but should instead be thought of as a badly named callback that will be triggered with the new value whenever the value changes.

This method can be private.

add_param :visible, Boolean, :writer => :set_visible

private

def set_visible value
  do_something_with value
  value
end


184
185
186
 
# File 'lib/sprout/executable/param.rb', line 184

def writer
  @writer
end

Instance Method Details

- (Object) clean_path(path) (protected)

Clean the provided path using the current Sprout::System.



428
429
430
 
# File 'lib/sprout/executable/param.rb', line 428

def clean_path path
  Sprout::System.create.clean_path path
end

- (Object) default

Return the default value or nil if none was provided.



279
280
281
 
# File 'lib/sprout/executable/param.rb', line 279

def default
  @default
end

- (Object) default=(value)

Set the default value of the parameter. Using this option will ensure that required parameters are not nil, and default values can be overridden on instances.

add_param :name, String, :default => 'Bob'


272
273
274
275
 
# File 'lib/sprout/executable/param.rb', line 272

def default=(value)
  self.value = value
  @default = value
end

- (Object) default_option_parser_declaration 



339
340
341
 
# File 'lib/sprout/executable/param.rb', line 339

def default_option_parser_declaration
  [ prefix, option_parser_name ]
end

- (Boolean) file_is_output?(file) (protected)

Return true if the Sprout::Executable that this parameter belongs_to has an output method (or parameter), and if the provided file matches the value of that parameter.

This method (convention) is used to avoid creating circular prerequisites in Rake. For most types of File parameters we want to make them into prerequisites, but not if the File is the one being created by the outer Sprout::Executable.

Returns:



442
443
444
 
# File 'lib/sprout/executable/param.rb', line 442

def file_is_output? file
  belongs_to.respond_to?(:output) && belongs_to.output.to_s == file
end

- (Boolean) hidden_name?

Should the param name be hidden from the shell? Used for params like 'input' on mxmlc

Returns:



300
301
302
 
# File 'lib/sprout/executable/param.rb', line 300

def hidden_name?
  @hidden_name
end

- (Boolean) hidden_value?

Should the param value be hidden from the shell? Usually used for Boolean toggles like '-debug'

Returns:



307
308
309
 
# File 'lib/sprout/executable/param.rb', line 307

def hidden_value?
  @hidden_value
end

- (Object) option_parser_declaration

How this parameter is provided to the Ruby OptionParser when being exposed as a Ruby Executable.



327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/sprout/executable/param.rb', line 327

def option_parser_declaration
  declaration = default_option_parser_declaration
  # TODO: Need to figure out how to support hidden name inputs...
  #if(hidden_name?)
    #declaration = [option_parser_type_output]
  #
  if(!hidden_value?)
    declaration << delimiter << option_parser_type_output
  end
  declaration.join('')
end

- (Object) option_parser_name (protected) 



410
411
412
 
# File 'lib/sprout/executable/param.rb', line 410

def option_parser_name
  name.to_s.gsub('_', '-')
end

- (Object) option_parser_short_name

The Ruby OptionParser short name with prefix.



345
346
347
 
# File 'lib/sprout/executable/param.rb', line 345

def option_parser_short_name
  [ short_prefix, short_name ].join('')
end

- (Object) option_parser_type_name (protected) 



414
415
416
 
# File 'lib/sprout/executable/param.rb', line 414

def option_parser_type_name
  @option_parser_type_name
end

- (Object) option_parser_type_output (protected) 



418
419
420
421
 
# File 'lib/sprout/executable/param.rb', line 418

def option_parser_type_output
  type = hidden_value? ? '' : option_parser_type_name
  required? ? type : "[#{type}]"
end

- (Object) prepare

Prepare the parameter for execution or delegation, depending on what context we're in.



286
287
288
289
 
# File 'lib/sprout/executable/param.rb', line 286

def prepare
  prepare_prerequisites
  @prepared = true
end

- (Object) prepare_prerequisites (protected) 



423
424
 
# File 'lib/sprout/executable/param.rb', line 423

def prepare_prerequisites
end

- (Boolean) prepared?

Returns true if this parameter has already been prepared.

Returns:



293
294
295
 
# File 'lib/sprout/executable/param.rb', line 293

def prepared?
  @prepared
end

- (Boolean) required?

Returns Boolean value if this parameter is required.

Returns:



251
252
253
 
# File 'lib/sprout/executable/param.rb', line 251

def required?
  (required == true)
end

- (Object) shell_value

The String representation of the value in a format that is appropriate for the terminal.

For certain types of parameters, like File, spaces may be escaped on some platforms.



367
368
369
 
# File 'lib/sprout/executable/param.rb', line 367

def shell_value
  value.to_s
end

- (Object) short_prefix 



320
321
322
 
# File 'lib/sprout/executable/param.rb', line 320

def short_prefix
  @short_prefix ||= (belongs_to.nil?) ? DEFAULT_SHORT_PREFIX : belongs_to.default_short_prefix
end

- (Object) to_rdoc

Create a string that can be turned into a file that rdoc can parse to describe the customized or generated task using param name, type and description



400
401
402
403
404
405
406
 
# File 'lib/sprout/executable/param.rb', line 400

def to_rdoc
  result = ''
  parts = description.split("\n") unless description.nil?
  result << "# #{parts.join("\n# ")}\n" unless description.nil?
  result << "def #{name}=(#{type})\n  @#{name} = #{type}\nend\n\n"
  return result
end

- (Object) to_shell

Prepare and serialize this parameter to a string that is appropriate for shell execution on the current platform.

Calling to_shell will first trigger a call to the prepare template method unless prepared? returns true.



386
387
388
389
390
391
392
393
394
 
# File 'lib/sprout/executable/param.rb', line 386

def to_shell
  prepare if !prepared?
  validate
  return '' if !visible?
  return @to_shell_proc.call(self) unless @to_shell_proc.nil?
  return shell_value if hidden_name?
  return shell_name if hidden_value?
  return [shell_name, delimiter, shell_value].join
end

- (Object) validate

Ensure this parameter is in a valid state, raise a Sprout::Errors::MissingArgumentError if it is not.



258
259
260
261
262
 
# File 'lib/sprout/executable/param.rb', line 258

def validate
  if(required? && value.nil?)
    raise Sprout::Errors::MissingArgumentError.new("#{name} is required and must not be nil")
  end
end

- (Boolean) visible?

By default, Executable::Params only appear in the shell output when they are not nil

Returns:



245
246
247
 
# File 'lib/sprout/executable/param.rb', line 245

def visible?
  !value.nil?
end