Class: Sprout::Executable::Param

Inherits:
Object
  • Object
show all
Defined in:
sprout/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.



227
228
229
230
231
232
233
# File 'sprout/lib/sprout/executable/param.rb', line 227

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 'sprout/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 'sprout/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 'sprout/lib/sprout/executable/param.rb', line 71

def description
  @description
end

- (Object) file_expression



364
365
366
# File 'sprout/lib/sprout/executable/param.rb', line 364

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 'sprout/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 'sprout/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 'sprout/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 'sprout/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 custom attribute reader that is available to instance methods on the Sprout::Executable that uses it.

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

def get_visible
  return @visible
end


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

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



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

def required
  @required
end

- (Object) shell_name



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

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.



349
350
351
# File 'sprout/lib/sprout/executable/param.rb', line 349

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" }


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

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.



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

def type
  @type
end

- (Object) value

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



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

def value
  @value
end

- (Object) writer

A Symbol that refers to a custom attribute writer that is available to instance methods on the Sprout::Executable that uses it.

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

def set_visible=(vis)
  @visible = vis
end


177
178
179
# File 'sprout/lib/sprout/executable/param.rb', line 177

def writer
  @writer
end

Instance Method Details

- (Object) clean_path(path) (protected)

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



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

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

- (Object) default

Return the default value or nil if none was provided.



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

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'


265
266
267
268
# File 'sprout/lib/sprout/executable/param.rb', line 265

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

- (Object) default_option_parser_declaration



332
333
334
# File 'sprout/lib/sprout/executable/param.rb', line 332

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:



435
436
437
# File 'sprout/lib/sprout/executable/param.rb', line 435

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:



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

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:



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

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.



320
321
322
323
324
325
326
327
328
329
330
# File 'sprout/lib/sprout/executable/param.rb', line 320

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)



403
404
405
# File 'sprout/lib/sprout/executable/param.rb', line 403

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

- (Object) option_parser_short_name

The Ruby OptionParser short name with prefix.



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

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

- (Object) option_parser_type_name (protected)



407
408
409
# File 'sprout/lib/sprout/executable/param.rb', line 407

def option_parser_type_name
  @option_parser_type_name
end

- (Object) option_parser_type_output (protected)



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

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.



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

def prepare
  prepare_prerequisites
  @prepared = true
end

- (Object) prepare_prerequisites (protected)



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

def prepare_prerequisites
end

- (Boolean) prepared?

Returns true if this parameter has already been prepared.

Returns:



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

def prepared?
  @prepared
end

- (Boolean) required?

Returns Boolean value if this parameter is required.

Returns:



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

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.



360
361
362
# File 'sprout/lib/sprout/executable/param.rb', line 360

def shell_value
  value.to_s
end

- (Object) short_prefix



313
314
315
# File 'sprout/lib/sprout/executable/param.rb', line 313

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



393
394
395
396
397
398
399
# File 'sprout/lib/sprout/executable/param.rb', line 393

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.



379
380
381
382
383
384
385
386
387
# File 'sprout/lib/sprout/executable/param.rb', line 379

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.



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

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:



238
239
240
# File 'sprout/lib/sprout/executable/param.rb', line 238

def visible?
  !value.nil?
end