nucleon 0.2.2 → 0.2.3

data/lib/core/config/collection.rb

@@ -1,22 +1,77 @@
-
 module Nucleon
 class Config
+#
+# == Configuration collection
+#
+# The Nucleon::Config::Collection class defines a container for logging properties
+# and values.  This class is not currently used within Nucleon itself but it
+# does serve as a configuration log for the corl gem.
+#
+# This basically provides standard access methods.  It implements the ability
+# to dump registered properties to the file system through a machine readable
+# format.
+#
+# How we use it in CORL:
+#
+# 1. As we look up configurations and modify them we save new values in global registry
+# 2. When we get to the end of our execution we log them to disk so they are viewable
+#
+# Right now, largely for historical reasons, this class is structured as a
+# global interface and collection for grouping all of the defined options.
+# It was originally contained within Nucleon::Config as part of the global
+# configuration interface.  In the future, this class will be refactored to
+# support multiple property logs and will have more fully refined persistence
+# methods.
+#
+# *TODO*: Mutex synchronization probably not needed?
+#
+# For usage:
+#
+# - See core configuration object Nucleon::Config
+# - See configuration mixin Nucleon::Mixin::ConfigCollection
+#
 class Collection
 
-  #-----------------------------------------------------------------------------
+  #*****************************************************************************
   # Property accessor / modifiers
 
-  @@lock       = Mutex.new
+  # Global access lock
+  #
+  # *TODO*: Might not be needed?
+  #
+  @@lock = Mutex.new
+
+  # Global property collection
+  #
+  # Structure: @@properties[property] = value
+  #
   @@properties = {}
-  
-  #---
-  
+
+  # Return a reference to all of the globally defined properties.
+  #
+  # This method generally should not be used in favor of the ::get method.
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Hash<Symbol|ANY>]  Global reference to property registry
+  #
+  # * *Errors*
+  #
   def self.all
     @@properties
   end
-  
-  #---
-  
+
+  # Return specified property value.
+  #
+  # * *Parameters*
+  #   - [String, Symbol] *name*  Property name to return value
+  #
+  # * *Returns*
+  #   - [ANY]  Specified property value
+  #
+  # * *Errors*
+  #
   def self.get(name)
     value = nil
     @@lock.synchronize do
@@ -24,44 +79,98 @@ class Collection
     end
     value
   end
-  
-  #---
-  
+
+  # Set property value.
+  #
+  # * *Parameters*
+  #   - [String, Symbol] *name*  Property name to set value
+  #   - [ANY] *value*  Specified property value
+  #
+  # * *Returns*
+  #   - [Void]  This method does not currently have a return value
+  #
+  # * *Errors*
+  #
   def self.set(name, value)
     @@lock.synchronize do
       @@properties[name.to_sym] = value
     end
   end
-  
-  #---
-  
+
+  # Delete property from collection.
+  #
+  # * *Parameters*
+  #   - [String, Symbol] *name*  Property name to remove
+  #
+  # * *Returns*
+  #   - [Void]  This method does not currently have a return value
+  #
+  # * *Errors*
+  #
   def self.delete(name)
     @@lock.synchronize do
       @@properties.delete(name.to_sym)
     end
   end
-   
-  #---
-  
+
+  # Clear all properties from the collection.
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Void]  This method does not currently have a return value
+  #
+  # * *Errors*
+  #
   def self.clear
     @@lock.synchronize do
       @@properties = {}
     end
   end
-  
-  #---
-  
+
+  # Dump properties to disk.
+  #
+  # This class was originally designed as a logging mechanism so it is focused
+  # on providing write methods so far.  Notice the missing load() method.
+  #
+  # The property dump must be explicitly enabled with the :config_store option.
+  #
+  # *TODO*:
+  # 1. This method will undergo a large'ish transformation in the future as it
+  #    is rewritten to make it more flexible.
+  # 2. Throw appropriate error if write fails.
+  #
+  # * *Parameters*
+  #   - [Hash<Symbol|ANY>] *options*  Method options
+  #     - [String] *:log_dir*  Directory to store the log files
+  #     - [String] *:log_name*  Name of the log file (*no dot or extension*)
+  #     - [Boolean] *:config_store*  Check whether configurations should be stored
+  #
+  # * *Returns*
+  #   - [Void]  This method does not currently have a return value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Data::empty?
+  # - Nucleon::Util::Data.string_map
+  # - Nucleon::Util::Data::to_json
+  # - Nucleon::Util::Data::to_yaml
+  #
   def self.save(options = {})
     unless Util::Data.empty?(options[:log_dir])
       @@lock.synchronize do
-        log_dir = options[:log_dir]
-      
+        log_dir  = options[:log_dir]
+
+        log_name = options[:log_name]
+        log_name = 'properties' unless log_name
+
         if options[:config_store]
           unless File.directory?(log_dir)
             FileUtils.mkdir_p(log_dir)
           end
-          Util::Disk.write(File.join(log_dir, "properties.json"), Util::Data.to_json(@@properties, true))
-          Util::Disk.write(File.join(log_dir, "properties.yaml"), Util::Data.to_yaml(Util::Data.string_map(@@properties)))
+          Util::Disk.write(File.join(log_dir, "#{log_name}.json"), Util::Data.to_json(@@properties, true))
+          Util::Disk.write(File.join(log_dir, "#{log_name}.yaml"), Util::Data.to_yaml(Util::Data.string_map(@@properties)))
         end
       end
     end

data/lib/core/config/options.rb

@@ -1,74 +1,198 @@
-
 module Nucleon
 class Config
+#
+# == Contextualized option collection
+#
+# The Nucleon::Config::Options class defines a container for contextualized
+# access of grouped properties.
+#
+# This basically does three things:
+#
+# 1. Group properties by contextual identifiers and store in a centralized location
+# 2. Access all defined properties for one or more contextual identifiers
+# 3. Clear contextual properties
+#
+# Right now, largely for historical reasons, this class is structured as a
+# global interface and collection for grouping all of the defined options.
+# It was originally contained within Nucleon::Config as part of the global
+# configuration interface.  In the future, this class will be refactored to
+# support multiple collections of contextualized properties.
+#
+# For usage:
+#
+# - See core configuration object Nucleon::Config::init
+# - See configuration mixin Nucleon::Mixin::ConfigOptions
+#
 class Options
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Property accessors / modifiers
-  
+
+  # Global contextualized property collection
+  #
+  # Structure: @@options[context_name][property] = value
+  #
   @@options = {}
-  
-  #---
-  
+
+  # Return an array of context names based on given contexts and an optional
+  # hierarchy path.
+  #
+  # This method mainly exists to allow us to create cascading context groups
+  # for the properties based on a hierarchical list.  We use it to create
+  # contextual property lookups for configuring Puppet in the corl gem.
+  #
+  # For example:
+  #
+  #  contexts = Nucleon::Config::Options.contexts([ :parameter, :var_name ], :module)
+  #  contexts = [
+  #    'all',
+  #    'parameter',
+  #    'var_name',
+  #    'module_parameter',
+  #    'module_var_name'
+  #  ]
+  #
+  # * *Parameters*
+  #   - [Array<String, Symbol>, String, Symbol] *contexts*  Context names to include in list
+  #   - [Array<String, Symbol>, String, Symbol] *hierarchy*  Hierarchy of prefixes to apply to given contexts
+  #
+  # * *Returns*
+  #   - [Array<String>]  Generated array of ordered context names
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Data::empty?
+  # - Nucleon::Util::Data::prefix
+  #
   def self.contexts(contexts = [], hierarchy = [])
     contexts = [ 'all', contexts ].flatten
-    
+    results  = contexts
+
     unless hierarchy.is_a?(Array)
       hierarchy = ( ! Util::Data.empty?(hierarchy) ? [ hierarchy ].flatten : [] )
     end
-    
-    hierarchy.each do |group|  
+
+    hierarchy.each do |group|
       group_contexts = Util::Data.prefix(group, contexts)
-      contexts       = [ contexts, group_contexts ].flatten
+      results        = [ results, group_contexts ].flatten
     end
-    
-    return contexts
+
+    return results
   end
-  
-  #---
-  
+
+  # Return a reference to all of the globally defined context properties.
+  #
+  # This method generally should not be used in favor of the ::get method.
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Hash<Symbol|Symbol|ANY>]  Global reference to option registry
+  #
+  # * *Errors*
+  #
   def self.all
     @@options
   end
-  
-  #---
-  
+
+  # Return merged option groups for given context names.
+  #
+  # This method allows us to easily request combinations of properties.
+  #
+  # For example:
+  #
+  #  Nucleon::Config::Options.set(:context1, { :property1 => 'some value' })
+  #  Nucleon::Config::Options.set(:context2, { :property2 => 'another value' })
+  #
+  #  options = Nucleon::Config::Options.get([ :context1, :context2 ])
+  #  options = {
+  #    :property1 => 'some value',
+  #    :property2 => 'another value'
+  #  }
+  #
+  # * *Parameters*
+  #   - [Array<String, Symbol>, String, Symbol] *contexts*  Context names to aggregate
+  #   - [Boolean] *force*  Force merge override if different types of data being merged
+  #
+  # * *Returns*
+  #   - [Hash<Symbol|ANY>]  Aggregated context property collection
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Data::empty?
+  # - Nucleon::Util::Data::merge
+  #
   def self.get(contexts, force = true)
     options = {}
-    
+
     unless contexts.is_a?(Array)
       contexts = ( ! Util::Data.empty?(contexts) ? [ contexts ].flatten : [] )
     end
     contexts.each do |name|
       name = name.to_sym
       if @@options.has_key?(name)
-        options = Util::Data.merge([ options, @@options[name] ], force)
+        options = Util::Data.merge([ options, @@options[name] ], force, false)
       end
     end
     return options
   end
-  
-  #---
-  
+
+  # Assign property values to specified context identifiers.
+  #
+  # This method allows us to easily merge properties across various contexts.
+  #
+  # For example, see ::get method
+  #
+  # * *Parameters*
+  #   - [Array<String, Symbol>, String, Symbol] *contexts*  Context names to assign properties
+  #   - [Hash<String, Symbol|ANY>] *options*  Property collection to merge with existing properties
+  #   - [Boolean] *force*  Force merge override if different types of data being merged
+  #
+  # * *Returns*
+  #   - [Void]  This method does not currently have a return value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Data::empty?
+  # - Nucleon::Util::Data::merge
+  #
   def self.set(contexts, options, force = true)
     unless contexts.is_a?(Array)
       contexts = ( ! Util::Data.empty?(contexts) ? [ contexts ].flatten : [] )
     end
     contexts.each do |name|
-      name = name.to_sym    
+      name = name.to_sym
       current_options = ( @@options.has_key?(name) ? @@options[name] : {} )
-      @@options[name] = Util::Data.merge([ current_options, Config.symbol_map(options) ], force)
-    end  
-  end
-  
-  #---
-  
-  def self.clear(contexts)
-    unless contexts.is_a?(Array)
-      contexts = [ contexts ]
+      @@options[name] = Util::Data.merge([ current_options, Config.symbol_map(options) ], force, false)
     end
-    contexts.each do |name|
-      @@options.delete(name.to_sym)
+  end
+
+  # Clear all properties for specified contexts.
+  #
+  # Contexts are entirely removed, even the name itself.  If nil is given (default)
+  # then all data is removed and options are reinitialized.
+  #
+  # * *Parameters*
+  #   - [nil, Array<String, Symbol>, String, Symbol] *contexts*  Context names to remove
+  #
+  # * *Returns*
+  #   - [Void]  This method does not currently have a return value
+  #
+  # * *Errors*
+  #
+  def self.clear(contexts = nil)
+    if contexts.nil?
+      @@options = {}
+    else
+      unless contexts.is_a?(Array)
+        contexts = [ contexts ]
+      end
+      contexts.each do |name|
+        @@options.delete(name.to_sym)
+      end
     end
   end
 end

data/lib/core/core.rb

@@ -1,99 +1,261 @@
-
 module Nucleon
+#
+# == Core Nucleon object
+#
+# The Nucleon::Core class defines a minimal base class for creating other
+# capable objects, combining configurations, console capabilities, and logging
+# capabilities.
+#
+# All of the plugins build off of the Core object, as do some utility classes.
+#
+# Five main goals with this object:
+#
+# 1. Global and instance Nucleon::Util::Logger interfaces
+# 2. Global and instance Nucleon::Util::Console interfaces
+# 3. Include color methods
+# 4. Provide contextually prefixed UI groups for console output operations
+# 5. Provide an initialized lookup
+#
 class Core < Config
-  
+
+  #
+  # Provide colored text rendering methods
+  #
+  # See:
+  # - Nucleon::Mixin::Colors
+  # - Nucleon::Util::Console
+  #
   include Mixin::Colors
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Properties
-  
-  @@logger  = Util::Logger.new('core')
-  @@ui      = Util::Console.new('core')
+
+  #
+  # Global logger instance
+  #
+  # See:
+  # - Nucleon::Util::Logger
+  #
+  @@logger = Util::Logger.new('core')
+  #
+  # Global console instance
+  #
+  # See:
+  # - Nucleon::Util::Console
+  #
+  @@ui = Util::Console.new('core')
+  #
+  # Global UI Mutex
+  #
+  # TODO: This may not be needed?
+  #
   @@ui_lock = Mutex.new
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Constructor / Destructor
-  
+
+  # Initialize a new core Nucleon object
+  #
+  # TODO: Figure out some way to make the console and logging systems pluggable?
+  #
+  # * *Parameters*
+  #   - [nil, Hash, Nucleon::Config] *data*  Configurations to import
+  #   - [Hash] *defaults*  Configuration defaults that may be overridden by config data
+  #   - [Boolean] *force*  Whether or not to force override of values where types don't match during merge
+  #   - [Boolean] *set_initialized*  Whether or not to the initialized flag is set after this object is constructed
+  #   - [Boolean] *basic_merge*  Whether or not to perform a basic merge or deep (recursive) merge
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Config::new
+  # - Nucleon::Config#delete
+  # - Nucleon::Config#export
+  # - Nucleon::Config#defaults
+  # - Nucleon::Util::Data::ensure_value
+  # - Nucleon::Util::Console::colorize
+  #
   def initialize(data = {}, defaults = {}, force = true, set_initialized = true, basic_merge = true)
-    super(data, defaults, force, basic_merge)   
-    
+    super(data, defaults, force, basic_merge)
+
+    @initialized = false
     @class_color = Util::Data.ensure_value(delete(:class_color, :cyan), :cyan)
     @class_label = self.class.to_s.downcase.gsub(/^nucleon::/, '')
-    
+
     self.logger = delete(:logger, @class_label)
     self.ui     = Config.new(export).defaults({ :resource => Util::Console.colorize(@class_label, @class_color) })
-    
+
     logger.debug('Initialized instance logger and interface')
     @initialized = true if set_initialized
   end
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Checks
-  
+
+  # Check if object is initialized?
+  #
+  # The initialized flag must be set from a method within the class.  It can not
+  # be set externally.
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Boolean]  Whether or not object has been marked as initialized
+  #
+  # * *Errors*
+  #
   def initialized?
     @initialized
   end
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # Accessor / Modifiers
-  
-  attr_reader :logger, :ui
-  
-  #---
-  
+
+  #
+  # [Nucleon::Util::Logger]  Instance logger
+  #
+  attr_reader :logger
+  #
+  # [Nucleon::Util::Console]  Instance console
+  #
+  attr_reader :ui
+
+  # Return global logger instance
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Nucleon::Util::Logger]  Global logger instance
+  #
+  # * *Errors*
+  #
   def self.logger
     return @@logger
   end
-  
+
+  # Set current object logger instance
+  #
+  # * *Parameters*
+  #   - [String, Nucleon::Util::Logger] *logger*  Logger instance or resource name for new logger
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Logger::loggers
+  # - Nucleon::Util::Logger::new
+  #
   def logger=logger
     Util::Logger.loggers.delete(self.logger.resource) if self.logger
-    
+
     if logger.is_a?(Util::Logger)
       @logger = logger
     else
       @logger = Util::Logger.new(logger)
     end
   end
-  
-  #---
-  
+
+  # Return global console instance
+  #
+  # This is named ui for historical reasons.  It might change to console in the
+  # future.
+  #
+  # * *Parameters*
+  #
+  # * *Returns*
+  #   - [Nucleon::Util::Console]  Global console instance
+  #
+  # * *Errors*
+  #
   def self.ui
     return @@ui
   end
-  
+
+  # Set current object console instance
+  #
+  # * *Parameters*
+  #   - [String, Nucleon::Util::Console] *ui*  Console instance or resource name for new console
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # See also:
+  # - Nucleon::Util::Console::new
+  #
   def ui=ui
     if ui.is_a?(Util::Console)
       @ui = ui
     else
       @ui = Util::Console.new(ui)
-    end  
+    end
   end
-  
-  #-----------------------------------------------------------------------------
+
+  #*****************************************************************************
   # General utilities
-  
-  def self.ui_group(resource, color = :cyan)
+
+  # Contextualize console operations in a code block with a given resource name.
+  #
+  # TODO: May not need Mutex synchronization?
+  #
+  # * *Parameters*
+  #   - [String, Symbol] *resource*  Console resource identifier (prefix)
+  #   - [Symbol] *color*  Color to use; *:black*, *:red*, *:green*, *:yellow*, *:blue*, *:purple*, *:cyan*, *:grey*
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # * *Yields*
+  #   - [Nucleon::Util::Console] *ui*  Current global console instance
+  #
+  # See also:
+  # - Nucleon::Util::Console::colorize
+  #
+  def self.ui_group(resource, color = :cyan) # :yields: ui
     @@ui_lock.synchronize do
       begin
         ui_resource = ui.resource
         ui.resource = Util::Console.colorize(resource, color)
         yield(ui)
-    
+
       ensure
         ui.resource = ui_resource
       end
-    end  
-  end 
-  
-  #---
-  
-  def ui_group(resource, color = :cyan)
+    end
+  end
+
+  # Contextualize console operations in a code block with a given resource name.
+  #
+  # * *Parameters*
+  #   - [String, Symbol] *resource*  Console resource identifier (prefix)
+  #   - [Symbol] *color*  Color to use; *:black*, *:red*, *:green*, *:yellow*, *:blue*, *:purple*, *:cyan*, *:grey*
+  #
+  # * *Returns*
+  #   - [Void]  This method does not return a value
+  #
+  # * *Errors*
+  #
+  # * *Yields*
+  #   - [Nucleon::Util::Console] *ui*  Current object console instance
+  #
+  # See also:
+  # - Nucleon::Util::Console::colorize
+  #
+  def ui_group(resource, color = :cyan) # :yields: ui
     ui_resource = ui.resource
     ui.resource = Util::Console.colorize(resource, color)
     yield(ui)
-    
+
   ensure
-    ui.resource = ui_resource  
-  end 
+    ui.resource = ui_resource
+  end
 end
 end