Class: Nucleon::Environment

Inherits:
Core show all
Defined in:
lib/core/environment.rb

Overview

  • Nucleon::Plugin::Base

Instance Attribute Summary

Attributes inherited from Core

#logger, #ui

Instance Method Summary collapse

Methods inherited from Core

#initialized?, logger, ui, ui_group, #ui_group

Methods included from Mixin::Colors

#black, #blue, #cyan, #green, #grey, #purple, #red, #yellow

Methods inherited from Config

#[], #[]=, #append, array, #array, #clear, #defaults, #delete, #empty?, ensure, #export, #filter, filter, #get, #get_array, #get_hash, #has_key?, hash, #hash, #import, #init, init, init_flat, #keys, #prepend, #set, #string, string, string_map, #string_map, symbol, #symbol, #symbol_array, #symbol_map, symbol_map, test, #test

Methods included from Mixin::ConfigOptions

#all_options, #clear_options, #contexts, #get_options, #set_options

Methods included from Mixin::ConfigCollection

#all_properties, #clear_properties, #delete_property, #get_property, #save_properties, #set_property

Constructor Details

#initialize ⇒ Environment

Initialize a new Nucleon environment

IMORTANT: The environment constructor should accept no parameters!

  • Parameters

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

  • Nucleon::Manager



64
65
66
67
68
69
70
71
72
 
# File 'lib/core/environment.rb', line 64

def initialize
  super({
    :plugin_types => {},
    :load_info    => {},
    :active_info  => {}
  }, {}, true, true, false)

  @instance_map = Config.new
end

Instance Method Details

#active_plugins(namespace = nil, plugin_type = nil, provider = nil) ⇒ Object

Return active plugins for namespaces, plugin types, providers if specified

  • Parameters

    • nil, String, Symbol

      namespace Namespace to return plugin instance

    • nil, String, Symbol

      plugin_type Plugin type name to return plugin instance

    • nil, String, Symbol

      provider Plugin provider to return plugin instance

  • Returns

    • nil, Hash<Symbol|Symbol|Symbol|Symbol|Nucleon::Plugin::Base>

      Returns all plugin instances if no parameters given

    • nil, Hash<Symbol|Symbol|Symbol|Nucleon::Plugin::Base>

      Returns namespace plugin instances if only namespace given

    • nil, Hash<Symbol|Symbol|Nucleon::Plugin::Base>

      Returns plugin type instances if namespace and plugin type given

    • nil, Hash<Symbol|Nucleon::Plugin::Base>

      Returns provider instances if namespace, plugin type, and provider given

  • Errors

See:

  • Nucleon::Config#get_hash

See also:

  • #sanitize_id



550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
 
# File 'lib/core/environment.rb', line 550

def active_plugins(namespace = nil, plugin_type = nil, provider = nil)
  active_info = get_hash(:active_info)

  namespace   = namespace.to_sym if namespace
  plugin_type = sanitize_id(plugin_type) if plugin_type
  provider    = sanitize_id(provider) if provider
  results     = {}

  if namespace && active_info.has_key?(namespace)
    if plugin_type && active_info[namespace].has_key?(plugin_type)
      if provider && ! active_info[namespace][plugin_type].keys.empty?
        active_info[namespace][plugin_type].each do |instance_name, plugin|
          plugin                 = active_info[namespace][plugin_type][instance_name]
          results[instance_name] = plugin if plugin.plugin_provider == provider
        end
      elsif ! provider
        results = active_info[namespace][plugin_type]
      end
    elsif ! plugin_type
      results = active_info[namespace]
    end
  elsif ! namespace
    results = active_info
  end
  results
end

#autoload ⇒ Object

Autoload all of the defined plugins

  • Parameters

  • Returns

    • Void

      This method does not return a value

  • Errors

    • TODO

  • Yields

    • Symbol

      namespace Plugin namespace

    • Symbol

      plugin_type Plugin type

    • Symbol

      provider Plugin provider

    • Hash<Symbol|ANY>

      plugin Plugin load information

See:

  • #loaded_plugins

  • #class_const



378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/core/environment.rb', line 378

def autoload # :yields: namespace, plugin_type, provider, plugin
  load_info = loaded_plugins

  load_info.keys.each do |namespace|
    load_info[namespace].keys.each do |plugin_type|
      load_info[namespace][plugin_type].each do |provider, plugin|
        require plugin[:file]

        load_info[namespace][plugin_type][provider][:class] = class_const(plugin[:class_components])

        yield(namespace, plugin_type, provider, plugin) if block_given?
      end
    end
  end
end

#class_const(name, separator = '::') ⇒ Object

Return a fully formed class name as a machine usable constant

  • Parameters

    • String, Symbol, Array

      name Class name components

    • String, Symbol

      separator Class component separator (default ‘::’)

  • Returns

    • Class Constant

      Returns class constant for fully formed class name of given components

  • Errors

See also:

  • #class_name



629
630
631
632
633
634
635
636
637
638
639
 
# File 'lib/core/environment.rb', line 629

def class_const(name, separator = '::')
  components = class_name(name, separator, TRUE)
  constant   = Object

  components.each do |component|
    constant = constant.const_defined?(component) ?
                constant.const_get(component) :
                constant.const_missing(component)
  end
  constant
end

#class_name(name, separator = '::', want_array = false) ⇒ Object

Return a fully formed class name as a string

  • Parameters

    • String, Symbol, Array

      name Class name components

    • String, Symbol

      separator Class component separator (default ‘::’)

    • Boolean

      want_array Whether or not to return array of final components or string version

  • Returns

    • String

      Returns fully rendered class name as string unless want_array is true

    • Array

      Returns array of final class components if want_array is true

  • Errors



593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
 
# File 'lib/core/environment.rb', line 593

def class_name(name, separator = '::', want_array = false)
  components = []

  case name
  when String, Symbol
    components = name.to_s.split(separator)
  when Array
    components = name.flatten
  end

  components.collect! do |value|
    value    = value.to_s.strip
    value[0] = value.capitalize[0] if value =~ /^[a-z]/
    value
  end

  if want_array
    return components
  end
  components.join(separator)
end

#create_plugin(namespace, plugin_type, provider, options = {}, &code) ⇒ Object

Create a new plugin instance of a specified provider

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • String, Symbol

      plugin_type Plugin type name of provider

    • String, Symbol

      provider Plugin provider to return load information

    • Hash

      options Create options (plugin initialization configurations)

  • Returns

    • nil, Nucleon::Plugin::Base

      Returns plugin instance (inherited from Nucleon::Plugin::Base)

  • Errors

  • Yields

    • nil, Hash<Symbol|ANY>

      type_info Provider load information if it has been loaded

    • Hash

      options Create options (plugin initialization configurations)

See:

  • Nucleon::Plugin::Base

  • Nucleon::Config#get

  • Nucleon::Config#set

See also:

  • #sanitize_id

  • #plugin_type_defined?

  • #loaded_plugin

  • Nucleon::Config

  • Nucleon::Config::array

  • Nucleon::Util::Data::subset

  • Nucleon::Facade#sha1



429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
 
# File 'lib/core/environment.rb', line 429

def create_plugin(namespace, plugin_type, provider, options = {}, &code) # :yields: type_info, options
  namespace   = namespace.to_sym
  plugin_type = sanitize_id(plugin_type)
  provider    = sanitize_id(provider)
  options     = Util::Data.clone(options)
  plugin      = nil
  result      = nil

  unless plugin_type_defined?(namespace, plugin_type)
    return plugin
  end

  if type_info = Util::Data.clone(loaded_plugin(namespace, plugin_type, provider))
    ids             = array(type_info[:class].register_ids).flatten
    instance_config = Config.new(options, {}, true, false)
    ensure_new      = instance_config.delete(:new, false)

    instance_options = Util::Data.subset(instance_config.export, ids, true)
    instance_name    = "#{provider}_" + Nucleon.sha1(instance_options)
    plugin           = get([ :active_info, namespace, plugin_type, instance_name ])

    if ensure_new || ! ( instance_name && plugin )
      type_info[:instance_name] = instance_name

      result  = code.call(type_info, options) if code
      options = result if result.is_a?(Hash)

      options[:meta] = Config.new(type_info, {}, true, false).import(hash(options[:meta]))

      options.delete(:new)

      plugin = type_info[:class].new(namespace, plugin_type, provider, options)
      set([ :active_info, namespace, plugin_type, instance_name ], plugin)

      @instance_map.append([ namespace, plugin_type, plugin.plugin_name.to_sym ], instance_name.to_sym)
    end
  end
  plugin
end

#define_plugin(namespace, plugin_type, base_path, file, &code) ⇒ Object

Define a new plugin provider of a specified plugin type.

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • String, Symbol

      plugin_type Plugin type name to fetch default provider

    • String

      base_path Base load path of the plugin provider

    • String

      file File that contains the provider definition

  • Returns

    • Nucleon::Environment

      Returns reference to self for compound operations

  • Errors

  • Yields

    • Hash<Symbol|ANY>

      data Plugin load information

See:

  • Nucleon::Config#get_hash

  • Nucleon::Config#set

See also:

  • #sanitize_id

  • #parse_plugin_info



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/core/environment.rb', line 225

def define_plugin(namespace, plugin_type, base_path, file, &code) # :yields: data
  namespace   = namespace.to_sym
  plugin_type = sanitize_id(plugin_type)
  plugin_info = parse_plugin_info(namespace, plugin_type, base_path, file)

  unless get_hash([ :load_info, namespace, plugin_type ]).has_key?(plugin_info[:provider])
    data = {
      :namespace        => namespace,
      :type             => plugin_type,
      :base_path        => base_path,
      :file             => file,
      :provider         => plugin_info[:provider],
      :directory        => plugin_info[:directory],
      :class_components => plugin_info[:class_components]
    }
    code.call(data) if code

    set([ :load_info, namespace, plugin_type, plugin_info[:provider] ], data)
  end
  self
end

#define_plugin_type(namespace, plugin_type, default_provider = nil) ⇒ Object

Define a new plugin type in a specified namespace.

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • String, Symbol

      plugin_type Plugin type name within namespace

    • nil, String, Symbol

      default_provider Default provider (defaults to none)

  • Returns

    • Nucleon::Environment

      Returns reference to self for compound operations

  • Errors

See:

  • Nucleon::Config#set

See also:

  • #sanitize_id



128
129
130
 
# File 'lib/core/environment.rb', line 128

def define_plugin_type(namespace, plugin_type, default_provider = nil)
  set([ :plugin_types, namespace, sanitize_id(plugin_type) ], default_provider)
end

#define_plugin_types(namespace, type_info) ⇒ Object

Define one or more new plugin types in a specified namespace.

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • Hash<String, Symbol|String, Symbol>

      type_info Plugin type, default provider pairs

  • Returns

    • Nucleon::Environment

      Returns reference to self for compound operations

  • Errors

See:

  • #define_plugin_type



146
147
148
149
150
151
152
153
 
# File 'lib/core/environment.rb', line 146

def define_plugin_types(namespace, type_info)
  if type_info.is_a?(Hash)
    type_info.each do |plugin_type, default_provider|
      define_plugin_type(namespace, plugin_type, default_provider)
    end
  end
  self
end

#get_plugin(namespace, plugin_type, plugin_name) ⇒ Object

Return a plugin instance by name if it exists

  • Parameters

    • String, Symbol

      namespace Namespace that contains the plugin

    • String, Symbol

      plugin_type Plugin type name

    • String, Symbol

      plugin_name Plugin name to return

  • Returns

    • nil, Nucleon::Plugin::Base

      Returns a plugin instance of name specified if it exists

  • Errors

See:

  • Nucleon::Plugin::Base

  • Nucleon::Config#get_hash

See also:

  • #sanitize_id



488
489
490
491
492
493
494
495
496
497
498
499
 
# File 'lib/core/environment.rb', line 488

def get_plugin(namespace, plugin_type, plugin_name)
  namespace    = namespace.to_sym
  plugin_type  = sanitize_id(plugin_type)

  instances    = get_hash([ :active_info, namespace, plugin_type ])
  instance_ids = array(@instance_map.get([ namespace, plugin_type, plugin_name.to_s.to_sym ]))

  if instance_ids.size
    return instances[instance_ids[0]]
  end
  nil
end

#loaded_plugin(namespace, plugin_type, provider) ⇒ Object

Return the load information for a specified plugin provider if it exists

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • String, Symbol

      plugin_type Plugin type name of provider

    • String, Symbol

      provider Plugin provider to return load information

  • Returns

    • nil, Hash<Symbol|ANY>

      Returns provider load information if provider exists, nil otherwise

  • Errors

See:

  • Nucleon::Config#get

See also:

  • #sanitize_id



265
266
267
 
# File 'lib/core/environment.rb', line 265

def loaded_plugin(namespace, plugin_type, provider)
  get([ :load_info, namespace, sanitize_id(plugin_type), sanitize_id(provider) ], nil)
end

#loaded_plugins(namespace = nil, plugin_type = nil, provider = nil, default = {}) ⇒ Object

Return the load information for namespaces, plugin types, providers if it exists

  • Parameters

    • nil, String, Symbol

      namespace Namespace to return load information

    • nil, String, Symbol

      plugin_type Plugin type name to return load information

    • nil, String, Symbol

      provider Plugin provider to return load information

    • ANY

      default Default results if nothing found (empty hash by default)

  • Returns

    • nil, Hash<Symbol|Symbol|Symbol|Symbol|ANY>

      Returns all load information if no parameters given

    • nil, Hash<Symbol|Symbol|Symbol|ANY>

      Returns namespace load information if only namespace given

    • nil, Hash<Symbol|Symbol|ANY>

      Returns plugin type load information if namespace and plugin type given

    • nil, Hash<Symbol|ANY>

      Returns provider load information if namespace, plugin type, and provider given

  • Errors

See:

  • Nucleon::Config#get_hash

See also:

  • #sanitize_id



291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/core/environment.rb', line 291

def loaded_plugins(namespace = nil, plugin_type = nil, provider = nil, default = {})
  load_info   = get_hash(:load_info)

  namespace   = namespace.to_sym if namespace
  plugin_type = sanitize_id(plugin_type) if plugin_type
  provider    = sanitize_id(provider) if provider
  results     = default

  if namespace && load_info.has_key?(namespace)
    if plugin_type && load_info[namespace].has_key?(plugin_type)
      if provider && load_info[namespace][plugin_type].has_key?(provider)
        results = load_info[namespace][plugin_type][provider]
      elsif ! provider
        results = load_info[namespace][plugin_type]
      end
    elsif ! plugin_type
      results = load_info[namespace]
    end
  elsif ! namespace
    results = load_info
  end
  results
end

#namespaces ⇒ Object

Return all of the defined namespaces in the plugin environment.

  • Parameters

  • Returns

    • Array<Symbol>

      Array of defined plugin namespaces

  • Errors

See:

  • Nucleon::Config#get_hash



89
90
91
 
# File 'lib/core/environment.rb', line 89

def namespaces
  get_hash(:plugin_types).keys
end

#plugin_class(namespace, plugin_type) ⇒ Object

Return a class constant representing a base plugin class generated from namespace and plugin_type.

  • Parameters

    • String, Symbol

      namespace Plugin namespace to constantize

    • String, Symbol

      plugin_type Plugin type to constantize

  • Returns

    • String

      Returns a class constant representing the plugin namespace and type

  • Errors

See also:

  • #class_const

  • #sanitize_class



686
687
688
 
# File 'lib/core/environment.rb', line 686

def plugin_class(namespace, plugin_type)
  class_const([ sanitize_class(namespace), :plugin, sanitize_class(plugin_type) ])
end

#plugin_has_provider?(namespace, plugin_type, provider) ⇒ Boolean

Check if a specified plugin provider has been loaded

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • String, Symbol

      plugin_type Plugin type name to check

    • String, Symbol

      provider Plugin provider name to check

  • Returns

    • Boolean

      Returns true if plugin provider has been loaded, false otherwise

  • Errors

See:

  • Nucleon::Config#get_hash

See also:

  • #sanitize_id

Returns:

  • (Boolean) 


354
355
356
 
# File 'lib/core/environment.rb', line 354

def plugin_has_provider?(namespace, plugin_type, provider)
  get_hash([ :load_info, namespace, sanitize_id(plugin_type) ]).has_key?(sanitize_id(provider))
end

#plugin_has_type?(namespace, plugin_type) ⇒ Boolean

Check if a specified plugin type has been loaded

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • String, Symbol

      plugin_type Plugin type name to check

  • Returns

    • Boolean

      Returns true if plugin type has been loaded, false otherwise

  • Errors

See:

  • Nucleon::Config#get_hash

See also:

  • #sanitize_id

Returns:

  • (Boolean) 


332
333
334
 
# File 'lib/core/environment.rb', line 332

def plugin_has_type?(namespace, plugin_type)
  get_hash([ :load_info, namespace ]).has_key?(sanitize_id(plugin_type))
end

#plugin_type_default(namespace, plugin_type) ⇒ Object

Return the default provider currently registered for a plugin type

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • String, Symbol

      plugin_type Plugin type name to fetch default provider

  • Returns

    • nil, Symbol

      Returns default provider if plugin type exists, nil otherwise

  • Errors

See:

  • Nucleon::Config#get

See also:

  • #sanitize_id



193
194
195
 
# File 'lib/core/environment.rb', line 193

def plugin_type_default(namespace, plugin_type)
  get([ :plugin_types, namespace, sanitize_id(plugin_type) ])
end

#plugin_type_defined?(namespace, plugin_type) ⇒ Boolean

Check if a specified plugin type has been defined

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

    • String, Symbol

      plugin_type Plugin type name to check within namespace

  • Returns

    • Boolean

      Returns true if plugin type exists, false otherwise

  • Errors

See:

  • Nucleon::Config#get_hash

See also:

  • #sanitize_id

Returns:

  • (Boolean) 


172
173
174
 
# File 'lib/core/environment.rb', line 172

def plugin_type_defined?(namespace, plugin_type)
  get_hash([ :plugin_types, namespace ]).has_key?(sanitize_id(plugin_type))
end

#plugin_types(namespace) ⇒ Object

Return all of the defined plugin types in a plugin namespace.

  • Parameters

    • String, Symbol

      namespace Namespace that contains plugin types

  • Returns

    • Array<Symbol>

      Array of defined plugin types

  • Errors

See:

  • Nucleon::Config#get_hash



106
107
108
 
# File 'lib/core/environment.rb', line 106

def plugin_types(namespace)
  get_hash([ :plugin_types, namespace ]).keys
end

#provider_class(namespace, plugin_type, provider) ⇒ Object

Return a class constant representing a plugin provider class generated from namespace, plugin_type, and provider name.

The provider name can be entered as an array if it is included in sub modules.

  • Parameters

    • String, Symbol

      namespace Plugin namespace to constantize

    • String, Symbol

      plugin_type Plugin type to constantize

    • String, Symbol, Array

      provider Plugin provider name to constantize

  • Returns

    • String

      Returns a class constant representing the plugin provider

  • Errors

See also:

  • #class_const

  • #sanitize_class



709
710
711
 
# File 'lib/core/environment.rb', line 709

def provider_class(namespace, plugin_type, provider)
  class_const([ sanitize_class(namespace), sanitize_class(plugin_type), provider ])
end

#remove_plugin(namespace, plugin_type, instance_name, &code) ⇒ Object

Remove a plugin instance from the environment

  • Parameters

    • String, Symbol

      namespace Namespace that contains the plugin

    • String, Symbol

      plugin_type Plugin type name

    • String, Symbol

      instance_name Plugin instance name to tremove

  • Returns

    • nil, Nucleon::Plugin::Base

      Returns the plugin instance that was removed from environment

  • Errors

  • Yields

    • Nucleon::Plugin::Base

      plugin Plugin object being removed (cleanup)

See:

  • Nucleon::Plugin::Base

  • Nucleon::Config#delete

See also:

  • #sanitize_id



523
524
525
526
527
 
# File 'lib/core/environment.rb', line 523

def remove_plugin(namespace, plugin_type, instance_name, &code) # :yields: plugin
  plugin = delete([ :active_info, namespace, sanitize_id(plugin_type), instance_name ])
  code.call(plugin) if code && plugin
  plugin
end