Class: Sprout::Executable::Base

Inherits:
Object
  • Object
show all
Includes:
Sprout::Executable
Defined in:
sprout/lib/sprout/executable/base.rb

Direct Known Subclasses

FlashSDK::ADL, FlashSDK::ADT, FlashSDK::CompilerBase, CommandLine, Session, Generator::Base

Constant Summary

Constants included from Sprout::Executable

DEFAULT_FILE_EXPRESSION, DEFAULT_PREFIX, DEFAULT_SHORT_PREFIX

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Concern

#append_features, extended, #included

Constructor Details

- (Base) initialize

A new instance of Base



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
# File 'sprout/lib/sprout/executable/base.rb', line 223

def initialize
  super
  @abort_on_failure     = true
  @appended_args        = nil
  @prepared             = false
  @prepended_args       = nil
  @param_hash           = {}
  @params               = []
  @prerequisites        = []
  @option_parser        = OptionParser.new
  @default_prefix       = DEFAULT_PREFIX
  @default_short_prefix = DEFAULT_SHORT_PREFIX
  initialize_defaults
  initialize_parameters
end

Instance Attribute Details

- (Object) abort_on_failure

Configure the executable instance to output failure messages to stderr and abort with non-zero response.



209
210
211
# File 'sprout/lib/sprout/executable/base.rb', line 209

def abort_on_failure
  @abort_on_failure
end

- (Object) default_prefix

The default command line prefix that should be used in front of parameter names.

The default value for this parameter is '--', but some command line applications (like MXMLC) prefer '-'.



178
179
180
# File 'sprout/lib/sprout/executable/base.rb', line 178

def default_prefix
  @default_prefix
end

- (Object) default_short_prefix

The default command line prefix for short name parameters.

This value defaults to '-', but can be changed to whatever a particular tool prefers.



186
187
188
# File 'sprout/lib/sprout/executable/base.rb', line 186

def default_short_prefix
  @default_short_prefix
end

- (Object) executable

The default Sprout executable that we will use for this executable.

Classes that include the Task can set the default value for this property at the class level with:

set :executable, :mxmlc

But that value can be overriden on each instance like:

executable = SomeToolTask.new
too.executable :compc

This parameter is required - either from the including class or instance configuration.



204
205
206
# File 'sprout/lib/sprout/executable/base.rb', line 204

def executable
  @executable
end

- (Object) param_hash (readonly)

Returns the value of attribute param_hash



219
220
221
# File 'sprout/lib/sprout/executable/base.rb', line 219

def param_hash
  @param_hash
end

- (Object) params (readonly)

Returns the value of attribute params



220
221
222
# File 'sprout/lib/sprout/executable/base.rb', line 220

def params
  @params
end

- (Object) pkg_name

The default RubyGem that we will use when requesting our executable.

Classes that include the Executable can set the default value for this property at the class level with:

set :pkg_name, 'sprout-sometoolname'

But that value can be overridden on each instance like:

executable = SomeToolTask.new
executable.pkg_name = 'sprout-othertoolname'

This parameter is required - either from the including class or instance configuration.



150
151
152
# File 'sprout/lib/sprout/executable/base.rb', line 150

def pkg_name
  @pkg_name
end

- (Object) pkg_version

The default RubyGem version that we will use when requesting our executable.

Classes that include the Task can set the default value for this property at the class level with:

set :pkg_version, '>= 1.0.3'

But that value can be overriden on each instance like:

executable = SomeToolTask.new
too.pkg_version = '>= 2.0.0'

This parameter is required - either from the including class or instance configuration.



168
169
170
# File 'sprout/lib/sprout/executable/base.rb', line 168

def pkg_version
  @pkg_version
end

- (Object) prerequisites (readonly)

Returns the value of attribute prerequisites



221
222
223
# File 'sprout/lib/sprout/executable/base.rb', line 221

def prerequisites
  @prerequisites
end

- (Object) rake_task_name

If the executable is configured as a Rake::Task, it will extract the Rake::Task[:name] property and apply it to this field.

Concrete parameters can pull this value from their belongs_to parameter.



217
218
219
# File 'sprout/lib/sprout/executable/base.rb', line 217

def rake_task_name
  @rake_task_name
end

Class Method Details

+ (Object) add_param(name, type, options = nil)

add_param is the workhorse of the Task. This method is used to add new shell parameters to the executable interface.

name is a symbol or string that represents the parameter that you would like to add such as :debug or :source_path.

type is a class reference of the Executable::Param that you'd like to use. At the time of this writing, add_param will accept 2 class references that do not extend Param - String and File. The ParameterFactory will automatically resolve these to the correct data type when they are created.

Boolean  true or false
File     Path to a file
Number   Any number
Path     Path to a directory
String   Any string value
Url      Basic URL

Files    Collection of files
Paths    Collection of directories
Strings  Collection of arbitrary strings
Urls     Collection of URLs

Be sure to check out the Sprout::Executable::Param class to learn more about working with executable parameters.

Once parameters have been added using the add_param method, clients can set and get those parameters from any newly created executable instance, or from the command line.

In the case of an executable delegate, parameter values will be sent to the command line executable in the order they are added using add_param.

In the case of a Ruby executable, command line parameters will be interpreted in the order they are defined using add_param.



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
# File 'sprout/lib/sprout/executable/base.rb', line 49

def add_param(name, type, options=nil) # :yields: Sprout::Executable::Param
  raise Sprout::Errors::UsageError.new "[DEPRECATED] add_param no longer uses closures, you can provide the same values as a hash in the optional last argument." if block_given?
  raise Sprout::Errors::UsageError.new "The first parameter (name:SymbolOrString) is required" if name.nil?
  raise Sprout::Errors::UsageError.new "The second parameter (type:Class) is required" if type.nil?
  raise Sprout::Errors::UsageError.new "The type parameter must be a Class by reference" if !type.is_a?(Class)

  options ||= {}
  options[:name] = name
  options[:type] = type
  # TODO: Integrate the RDOC-parsed parameter description here:
  #options[:description] ||= Sprout::RDocParser.description_for_caller caller.shift

  create_param_accessors options
  static_parameter_collection << options
  options
end

+ (Object) add_param_alias(new_name, old_name)



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

def add_param_alias new_name, old_name
  create_param_accessors :name => new_name, :real_name => old_name
end

+ (Object) set(key, value)



78
79
80
# File 'sprout/lib/sprout/executable/base.rb', line 78

def set key, value
  set_default_value key, value
end

+ (Object) static_default_value_collection



74
75
76
# File 'sprout/lib/sprout/executable/base.rb', line 74

def static_default_value_collection
  @static_default_value_collection ||= []
end

+ (Object) static_parameter_collection



70
71
72
# File 'sprout/lib/sprout/executable/base.rb', line 70

def static_parameter_collection
  @static_parameter_collection ||= []
end

Instance Method Details

- (File) binary_path

Path to the executable binary that should be executed.

Returns:

  • (File)

    Path to the executable binary that should be executed.



389
390
391
# File 'sprout/lib/sprout/executable/base.rb', line 389

def binary_path
  @binary_path ||= Sprout::Executable.load(executable, pkg_name, pkg_version).path
end

- (File) binary_path=(path)

Replace the binary that will be executed with a path to one of your choosing. This work is usually performed on the yielded instance from Rake like:

mxmlc 'bin/SomeProject.swf' do |t|
  t.input = 'src/SomeProject.as'
  t.binary_path = 'vendor/sdks/4.1.0/bin/mxmlc'
end

It's important to note that Windows systems will check the provided path for binaries of the same name that end with .exe and .bat and will use those in place of the provided name if they exist.

For example, if you set binary_path to:

t.binary_path = 'vendor/sdks/4.0.1/bin/mxmlc'

And there is a similarly-named file in the same directory, but named:

vendor/sdks/4.0.1/bin/mxmlc.bat

Windows systems will execute this .bat file.

Parameters:

  • (File) path

    Path to the executable binary that should be executed instead of whatever Sprout.load would have provided. If a value is set here, Sprout.load will not be called.

Returns:

  • (File)

    Path to the executable binary that should be executed.



383
384
385
# File 'sprout/lib/sprout/executable/base.rb', line 383

def binary_path=(path)
  @binary_path = path
end

- (Object) create_outer_task(*args) (protected)

Create the outer rake task. For most executables, this will be a Rake::File task, This is a template method that should be overridden for executables that do not result in the creation of a file.

See Also:

  • update_rake_task_name_from_args


420
421
422
423
424
# File 'sprout/lib/sprout/executable/base.rb', line 420

def create_outer_task *args
  file *args do
    execute
  end
end

- (Object) default_file_expression

Called by Parameters like :path and :paths



348
349
350
# File 'sprout/lib/sprout/executable/base.rb', line 348

def default_file_expression
  @default_file_expression ||= Sprout::Executable::DEFAULT_FILE_EXPRESSION
end

- (Object) execute

Execute the feature after calling parse with command line arguments.

Subclasses will generally override this method if they are a Ruby executable, but if you're just delegating to an external CLI application, calling execute will wind up executing the external process.



274
275
276
277
# File 'sprout/lib/sprout/executable/base.rb', line 274

def execute
  prepare
  execute_delegate
end

- (Object) execute_delegate (protected)

Call the provided executable delegate.

This method is generally called from Rake task wrappers.



400
401
402
# File 'sprout/lib/sprout/executable/base.rb', line 400

def execute_delegate
  system_execute binary_path, to_shell
end

- (Object) from_hash(hash)

This will ignore unknown parameters, because our very first use case, is when generators call other generators and generator A might have different parameters than generator B.



318
319
320
321
322
323
324
# File 'sprout/lib/sprout/executable/base.rb', line 318

def from_hash hash
  hash.each_pair do |key, value|
    if(self.respond_to?(key))
      self.send "#{key}=", value
    end
  end
end

- (Object) library_added(path_or_paths) (protected)

This method will generally be overridden by subclasses and they can do whatever customization is necessary for a particular library type.

It's important to note that this value can be a String path to a file (or folder), or it can be an Array of paths to files (or folders).



468
469
# File 'sprout/lib/sprout/executable/base.rb', line 468

def library_added path_or_paths
end

- (Object) parse!(commandline_options)



255
256
257
258
259
260
261
262
263
# File 'sprout/lib/sprout/executable/base.rb', line 255

def parse! commandline_options
  begin
    option_parser.parse! commandline_options
    parse_extra_options! commandline_options
    validate unless help_requested? commandline_options
  rescue StandardError => e
    handle_parse_error e
  end
end

- (Object) parse_extra_options!(options) (protected)



449
450
451
452
453
454
455
456
457
458
# File 'sprout/lib/sprout/executable/base.rb', line 449

def parse_extra_options! options
  options.each do |value|
    params.each do |param|
      if param.hidden_name?
        self.send "#{param.name}=", value
        break
      end
    end
  end
end

- (Object) parse_rake_task_arg(arg) (protected)



441
442
443
444
445
446
447
# File 'sprout/lib/sprout/executable/base.rb', line 441

def parse_rake_task_arg arg
  return arg if arg.is_a?(Symbol) || arg.is_a?(String)
  arg.each_pair do |key, value|
    return key
  end
  nil
end

- (Object) prepare (protected)



404
405
406
407
408
409
410
# File 'sprout/lib/sprout/executable/base.rb', line 404

def prepare
  return if @prepared
  @prepared = true
  params.each do |param|
    param.prepare
  end
end

- (Object) stderr



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

def stderr
  @stderr ||= Sprout.stderr
end

- (Object) stderr=(io)



247
248
249
# File 'sprout/lib/sprout/executable/base.rb', line 247

def stderr=(io)
  @stderr = io
end

- (Object) stdout



243
244
245
# File 'sprout/lib/sprout/executable/base.rb', line 243

def stdout
  @stdout ||= Sprout.stdout
end

- (Object) stdout=(io)



239
240
241
# File 'sprout/lib/sprout/executable/base.rb', line 239

def stdout=(io)
  @stdout = io
end

- (Object) system_execute(binary, params) (protected)



471
472
473
# File 'sprout/lib/sprout/executable/base.rb', line 471

def system_execute binary, params
  Sprout.current_system.execute binary, params
end

- (Object) to_hash

This will create a hash of ONLY values that are created using add_param, properties that are created with attr_accessor must be handled manually, or patches are welcome!



305
306
307
308
309
310
311
# File 'sprout/lib/sprout/executable/base.rb', line 305

def to_hash
  result = {}
  params.each do |param|
    result[param.name] = self.send(param.name)
  end
  result
end

- (Object) to_help



326
327
328
# File 'sprout/lib/sprout/executable/base.rb', line 326

def to_help
  option_parser.to_s
end

- (Object) to_rake(*args) {|_self| ... }

Yields:

  • (_self)

Yield Parameters:



279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
# File 'sprout/lib/sprout/executable/base.rb', line 279

def to_rake *args
  # Define the file task first - so that
  # desc blocks hook up to it...
  outer_task = create_outer_task *args
  update_rake_task_name_from_args *args
  yield self if block_given?
  prepare
  
  # TODO: Tried auto-updating with library
  # prerequisites, but this led to strange
  # behavior with multiple registrations.
  handle_library_prerequisites outer_task.prerequisites

  # Add the library resolution rake task
  # as a prerequisite
  outer_task.prerequisites << task(Sprout::Library::TASK_NAME)
  prerequisites.each do |prereq|
    outer_task.prerequisites << prereq
  end
  outer_task
end

- (Object) to_shell

Create a string that represents this configured executable for shell execution



331
332
333
334
335
336
337
338
339
340
341
342
343
# File 'sprout/lib/sprout/executable/base.rb', line 331

def to_shell
  return @to_shell_proc.call(self) unless @to_shell_proc.nil?

  result = []
  result << @prepended_args unless @prepended_args.nil?
  params.each do |param|
    if(param.visible?)
      result << param.to_shell
    end
  end
  result << @appended_args unless @appended_args.nil?
  return result.join(' ')
end

- (Object) update_rake_task_name_from_args(*args) (protected)

This method will add the current task to the Rake CLEAN collection.

Any Executable that does not create a Rake::File task should also override this method and prevent it from calling CLEAN.add.

See Also:

  • create_outer_task


435
436
437
438
439
# File 'sprout/lib/sprout/executable/base.rb', line 435

def update_rake_task_name_from_args *args
  self.rake_task_name = parse_rake_task_arg args.last
  CLEAN.add(self.rake_task_name)
  self.rake_task_name
end