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 method that will return the expected value when called.

• - (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 method (not accessor) that will be called when the value is set.

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.

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

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

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

371
372
373

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

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

133
134
135

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

def reader
  @reader
end

  add_param :visible, Boolean :required => true

144
145
146

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

def required
  @required
end

375
376
377

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

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

356
357
358

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

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

  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

158
159
160

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

def type
  @type
end

163
164
165

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

def value
  @value
end

  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

428
429
430

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

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

279
280
281

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

def default
  @default
end

  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

339
340
341

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

def default_option_parser_declaration
  [ prefix, option_parser_name ]
end

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

300
301
302

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

def hidden_name?
  @hidden_name
end

307
308
309

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

def hidden_value?
  @hidden_value
end

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

410
411
412

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

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

345
346
347

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

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

414
415
416

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

def option_parser_type_name
  @option_parser_type_name
end

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

286
287
288
289

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

def prepare
  prepare_prerequisites
  @prepared = true
end

423
424

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

def prepare_prerequisites
end

293
294
295

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

def prepared?
  @prepared
end

251
252
253

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

def required?
  (required == true)
end

367
368
369

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

def shell_value
  value.to_s
end

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

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

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

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

245
246
247

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

def visible?
  !value.nil?
end