Class: Sprout::Executable::Param

Inherits:

Object

• Object
• Sprout::Executable::Param

show all

Defined in:

lib/sprout/executable/param.rb

Overview

class Foo
  include Sprout::Executable

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

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)

• - (Object) belongs_to

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

• - (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.

• - (Object) description

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

• - (Object) file_expression
• - (Object) hidden_name

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

• - (Object) hidden_value

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

• - (Object) name

  The String (or Symbol) name of the parameter.

• - (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 '-'.

• - (Object) reader

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

• - (Object) required

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

• - (Object) shell_name
• - (Object) short_name

  The short name for this parameter.

• - (Object) to_shell_proc

  An optional Proc that should be called when this parameter is serialized to shell output.

• - (Object) type

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

• - (Object) value

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

• - (Object) writer

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

Instance Method Summary (collapse)

• - (Object) clean_path(path) protected

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

• - (Object) default

  Return the default value or nil if none was provided.

• - (Object) default=(value)

  Set the default value of the parameter.

• - (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.

• - (Boolean) hidden_name?

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

• - (Boolean) hidden_value?

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

• - (Param) initialize constructor

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

• - (Object) option_parser_declaration

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

• - (Object) option_parser_name protected
• - (Object) option_parser_short_name

  The Ruby OptionParser short name with prefix.

• - (Object) option_parser_type_name protected
• - (Object) option_parser_type_output protected
• - (Object) prepare

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

• - (Object) prepare_prerequisites protected
• - (Boolean) prepared?

  Returns true if this parameter has already been prepared.

• - (Boolean) required?

  Returns Boolean value if this parameter is required.

• - (Object) shell_value

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

• - (Object) short_prefix
• - (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.

• - (Object) to_shell

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

• - (Object) validate

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

• - (Boolean) visible?

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

227
228
229
230
231
232
233

# File '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

60
61
62

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

def belongs_to
  @belongs_to
end

66
67
68

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

def delimiter
  @delimiter
end

71
72
73

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

def description
  @description
end

360
361
362

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

def file_expression
  @file_expression ||= belongs_to.default_file_expression
end

add_param :name, String, :hidden_name => true

foo --name=Value

foo Value

89
90
91

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

def hidden_name
  @hidden_name
end

add_param :visible, Boolean, :hidden_value => true

foo --visible=true

foo --visible

107
108
109

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

def hidden_value
  @hidden_value
end

111
112
113

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

def name
  @name
end

121
122
123

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

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

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

def get_visible
  return @visible
end

134
135
136

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

def reader
  @reader
end

add_param :visible, Boolean :required => true

145
146
147

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

def required
  @required
end

364
365
366

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

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

345
346
347

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

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

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

154
155
156

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

def to_shell_proc
  @to_shell_proc
end

159
160
161

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

def type
  @type
end

164
165
166

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

def value
  @value
end

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

def set_visible=(vis)
  @visible = vis
end

177
178
179

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

def writer
  @writer
end

417
418
419

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

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

272
273
274

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

def default
  @default
end

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

265
266
267
268

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

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

431
432
433

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

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

293
294
295

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

def hidden_name?
  @hidden_name
end

300
301
302

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

def hidden_value?
  @hidden_value
end

320
321
322
323
324
325
326
327
328
329
330

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

def option_parser_declaration
  declaration = [ prefix, option_parser_name ]
  # 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

399
400
401

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

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

334
335
336

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

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

403
404
405

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

def option_parser_type_name
  @option_parser_type_name
end

407
408
409
410

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

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

279
280
281
282

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

def prepare
  prepare_prerequisites
  @prepared = true
end

412
413

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

def prepare_prerequisites
end

286
287
288

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

def prepared?
  @prepared
end

244
245
246

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

def required?
  (required == true)
end

356
357
358

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

def shell_value
  value.to_s
end

313
314
315

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

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

389
390
391
392
393
394
395

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

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

375
376
377
378
379
380
381
382
383

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

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

251
252
253
254
255

# File '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

238
239
240

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

def visible?
  !value.nil?
end