sparkle_formation 0.1.6 → 0.2.0

data/lib/sparkle_formation/aws.rb

@@ -1,24 +1,31 @@
 require 'sparkle_formation'
 
 class SparkleFormation
+  # AWS resource helper
   class Aws
     class << self
 
       include SparkleFormation::Utils::AnimalStrings
+      # @!parse include SparkleFormation::Utils::AnimalStrings
 
-      # type:: AWS CFN resource type
-      # hash:: Hash of information
       # Register an AWS resource
+      #
+      # @param type [String] AWS CFN resource type
+      # @param hash [Hash] metadata information
+      # @return [TrueClass]
       def register(type, hash)
         unless(class_variable_defined?(:@@registry))
           @@registry = AttributeStruct.hashish.new
         end
         @@registry[type] = hash
+        true
       end
 
-      # identifier:: resource identifier
-      # key:: key of value to return from information hash
-      # Return the associated aws resource information
+      # Resource information
+      #
+      # @param identifier [String, Symbol] resource identifier
+      # @param key [String, Symbol] specific data
+      # @return [Hashish]
       def resource(identifier, key=nil)
         res = lookup(identifier)
         if(key && res)
@@ -28,8 +35,10 @@ class SparkleFormation
         end
       end
 
-      # json_path_or_hash:: Path to JSON file or Hash instance of resources
       # Register all discovered resources
+      #
+      # @param json_path_or_hash [String, Hashish] path to files or hash
+      # @return [TrueClass]
       def load(json_path_or_hash)
         if(json_path_or_hash.is_a?(String))
           require 'json'
@@ -44,14 +53,18 @@ class SparkleFormation
       end
 
       # Load the builtin AWS resources
+      #
+      # @return [TrueClass]
       def load!
         require File.join(File.dirname(__FILE__), 'aws', 'cfn_resources.rb')
         load(AWS_RESOURCES)
+        true
       end
 
-      # key:: string or symbol
-      # Return matching registry key. Uses snaked resource type for
-      # matching and will attempt all parts for match
+      # Discover registry key via part searching
+      #
+      # @param key [String, Symbol]
+      # @return [String, NilClass]
       def registry_key(key)
         key = key.to_s
         @@registry.keys.detect do |ref|
@@ -66,19 +79,20 @@ class SparkleFormation
         end
       end
 
-      # key:: string or symbol
-      # Returns resource information of type discovered via matching
-      # using #registry_key
+      # Registry information for given type
+      #
+      # @param key [String, Symbol]
+      # @return [Hashish, NilClass]
       def lookup(key)
         @@registry[registry_key(key)]
       end
 
-      # Return the currently loaded AWS registry
+      # @return [Hashish] currently loaded AWS registry
       def registry
         if(class_variable_defined?(:@@registry))
           @@registry
         else
-          {}
+          @@registry = AttributeStruct.hashish.new
         end
       end
 
@@ -86,4 +100,5 @@ class SparkleFormation
   end
 end
 
+# Shortcut helper constant
 SfnAws = SparkleFormation::Aws

data/lib/sparkle_formation/sparkle_attribute.rb

@@ -19,8 +19,14 @@
 require 'sparkle_formation'
 
 class SparkleFormation
+
+  # Provides template helper methods
   module SparkleAttribute
 
+    # Fn::Join generator
+    #
+    # @param args [Object]
+    # @return [Hash]
     def _cf_join(*args)
       options = args.detect{|i| i.is_a?(Hash) && i[:options]} || {:options => {}}
       args.delete(options)
@@ -29,13 +35,26 @@ class SparkleFormation
       end
       {'Fn::Join' => [options[:options][:delimiter] || '', *args]}
     end
+    alias_method :join!, :_cf_join
 
+    # Ref generator
+    #
+    # @param thing [String, Symbol] reference name
+    # @return [Hash]
+    # @note Symbol value will force key processing
     def _cf_ref(thing)
       thing = _process_key(thing, :force) if thing.is_a?(Symbol)
       {'Ref' => thing}
     end
     alias_method :_ref, :_cf_ref
-
+    alias_method :ref!, :_cf_ref
+
+    # Fn::FindInMap generator
+    #
+    # @param thing [String, Symbol] thing to find
+    # @param key [String, Symbol] thing to search
+    # @param suffix [Object] additional args
+    # @return [Hash]
     def _cf_map(thing, key, *suffix)
       suffix = suffix.map do |item|
         if(item.is_a?(Symbol))
@@ -49,7 +68,13 @@ class SparkleFormation
       {'Fn::FindInMap' => [_process_key(thing), {'Ref' => _process_key(key)}, *suffix]}
     end
     alias_method :_cf_find_in_map, :_cf_map
+    alias_method :find_in_map!, :_cf_map
+    alias_method :map!, :_cf_map
 
+    # Fn::GetAtt generator
+    #
+    # @param [Object] pass through arguments
+    # @return [Hash]
     def _cf_attr(*args)
       args = args.map do |thing|
         if(thing.is_a?(Symbol))
@@ -62,11 +87,22 @@ class SparkleFormation
       {'Fn::GetAtt' => args}
     end
     alias_method :_cf_get_att, :_cf_attr
+    alias_method :get_att!, :_cf_attr
+    alias_method :attr!, :_cf_attr
 
+    # Fn::Base64 generator
+    #
+    # @param arg [Object] pass through
+    # @return [Hash]
     def _cf_base64(arg)
       {'Fn::Base64' => arg}
     end
+    alias_method :base64!, :_cf_base64
 
+    # Fn::GetAZs generator
+    #
+    # @param region [String, Symbol] String will pass through. Symbol will be converted to ref
+    # @return [Hash]
     def _cf_get_azs(region=nil)
       region = case region
                when Symbol
@@ -78,30 +114,55 @@ class SparkleFormation
                end
       {'Fn::GetAZs' => region}
     end
-
+    alias_method :get_azs!, :_cf_get_azs
+    alias_method :azs!, :_cf_get_azs
+
+    # Fn::Select generator
+    #
+    # @param index [String, Symbol, Integer] Symbol will be converted to ref
+    # @param item [Object, Symbol] Symbol will be converted to ref
+    # @return [Hash]
     def _cf_select(index, item)
+      index = index.is_a?(Symbol) ? _cf_ref(index) : index
       item = _cf_ref(item) if item.is_a?(Symbol)
-      {'Fn::Select' => [index.to_i.to_s, item]}
+      {'Fn::Select' => [index, item]}
     end
+    alias_method :select!, :_cf_select
 
+    # @return [TrueClass, FalseClass]
     def rhel?
       !!@platform[:rhel]
     end
 
+    # @return [TrueClass, FalseClass]
     def debian?
       !!@platform[:debian]
     end
 
+    # Set the destination platform
+    #
+    # @param plat [String, Symbol] one of :rhel or :debian
+    # @return [TrueClass]
     def _platform=(plat)
       @platform || __hashish
       @platform.clear
       @platform[plat.to_sym] = true
     end
 
+    # Dynamic insertion helper method
+    #
+    # @param name [String, Symbol] dynamic name
+    # @param args [Object] argument list for dynamic
+    # @return [self]
     def dynamic!(name, *args, &block)
       SparkleFormation.insert(name, self, *args, &block)
     end
 
+    # Registry insertion helper method
+    #
+    # @param name [String, Symbol] name of registry item
+    # @param args [Object] argument list for registry
+    # @return [self]
     def registry!(name, *args)
       SfnRegistry.insert(name, self, *args)
     end

data/lib/sparkle_formation/sparkle_formation.rb

@@ -20,24 +20,31 @@ require 'sparkle_formation'
 
 SparkleFormation::SparkleStruct.camel_keys = true
 
+# Formation container
 class SparkleFormation
 
   include SparkleFormation::Utils::AnimalStrings
+  # @!parse include SparkleFormation::Utils::AnimalStrings
+  extend SparkleFormation::Utils::AnimalStrings
+  # @!parse extend SparkleFormation::Utils::AnimalStrings
 
   class << self
 
-    include SparkleFormation::Utils::AnimalStrings
-
-    attr_reader :dynamics
+    # @return [Hashish] loaded dynamics
+    def dynamics
+      @dynamics ||= SparkleStruct.hashish.new
+    end
 
-    # Return custom paths
+    # @return [Hashish] custom paths
     def custom_paths
-      @_paths ||= {}
+      @_paths ||= SparkleStruct.hashish.new
       @_paths
     end
 
-    # path:: Path
-    # Path to sparkle directory
+    # Get/set path to sparkle directory
+    #
+    # @param path [String] path to directory
+    # @return [String] path to directory
     def sparkle_path=(path=nil)
       if(path)
         custom_paths[:sparkle_path] = path
@@ -49,8 +56,10 @@ class SparkleFormation
     end
     alias_method(:sparkle_path, :sparkle_path=)
 
-    # path:: Path
-    # Set path to component files
+    # Get/set path to component files
+    #
+    # @param path [String] path to component files
+    # @return [String] path to component files
     def components_path=(path=nil)
       if(path)
         custom_paths[:components_directory] = path
@@ -59,8 +68,10 @@ class SparkleFormation
     end
     alias_method(:components_path, :components_path=)
 
-    # path:: Path
-    # Set path to dynamic files
+    # Get/set path to dynamic files
+    #
+    # @param path [String] path to dynamic files
+    # @return [String] path to dynamic files
     def dynamics_path=(path=nil)
       if(path)
         custom_paths[:dynamics_directory] = path
@@ -69,8 +80,10 @@ class SparkleFormation
     end
     alias_method(:dynamics_path, :dynamics_path=)
 
-    # path:: Path
-    # Set path to registry files
+    # Get/set path to registry files
+    #
+    # @param path [String] path to registry files
+    # @return [String] path to registry files
     def registry_path=(path=nil)
       if(path)
         custom_paths[:registry_directory] = path
@@ -79,32 +92,40 @@ class SparkleFormation
     end
     alias_method(:registry_path, :registry_path=)
 
-    # path:: Path
-    # args:: Option symbols
-    #   - :sparkle:: Return formation instead of Hash
-    # Compile file at given path and return Hash
+    # Compile file
+    #
+    # @param path [String] path to file
+    # @param args [Object] use :sparkle to return struct
+    # @return [Hashish, SparkleStruct]
     def compile(path, *args)
       formation = self.instance_eval(IO.read(path), path, 1)
       args.include?(:sparkle) ? formation : formation.compile._dump
     end
 
-    # base:: Base SparkleStruct
-    # Execute given block within base
+    # Execute given block within struct context
+    #
+    # @param base [SparkleStruct] context for block
+    # @yield block to execute
+    # @return [SparkleStruct] provided base or new struct
     def build(base=nil, &block)
       struct = base || SparkleStruct.new
       struct.instance_exec(&block)
       @_struct = struct
     end
 
-    # path:: Path
-    # Load component at given path
+    # Load component
+    #
+    # @param path [String] path to component
+    # @return [SparkleStruct] resulting struct
     def load_component(path)
       self.instance_eval(IO.read(path), path, 1)
       @_struct
     end
 
-    # directory:: Path
-    # Load all dynamics within given directory
+    # Load all dynamics within a directory
+    #
+    # @param directory [String]
+    # @return [TrueClass]
     def load_dynamics!(directory)
       @loaded_dynamics ||= []
       Dir.glob(File.join(directory, '*.rb')).each do |dyn|
@@ -117,8 +138,10 @@ class SparkleFormation
       true
     end
 
-    # directory:: Path
-    # Load all registry entries within given directory
+    # Load all registry entries within a directory
+    #
+    # @param directory [String]
+    # @return [TrueClass]
     def load_registry!(directory)
       Dir.glob(File.join(directory, '*.rb')).each do |reg|
         reg = File.expand_path(reg)
@@ -127,49 +150,66 @@ class SparkleFormation
       true
     end
 
-    # name:: Name of dynamic
-    # args:: Optional dynamic metadata
-    # Define a new dynamic and store associated block
+    # Define and register new dynamic
+    #
+    # @param name [String, Symbol] name of dynamic
+    # @param args [Hash] dynamic metadata
+    # @param args [Hash] :parameters description of _config parameters
+    # @example
+    #   metadata describes dynamic parameters for _config hash:
+    #   :item_name => {:description => 'Defines item name', :type => 'String'}
+    # @yield dynamic block
+    # @return [TrueClass]
     def dynamic(name, args={}, &block)
       @dynamics ||= SparkleStruct.hashish.new
-      @dynamics[name] = SparkleStruct.hashish[
+      dynamics[name] = SparkleStruct.hashish[
         :block, block, :args, SparkleStruct.hashish[args.map(&:to_a)]
       ]
+      true
     end
 
-    # name:: Name of dynamic
-    # Return metadata about dynamic
+    # Metadata for dynamic
+    #
+    # @param name [String, Symbol] dynamic name
+    # @return [Hashish] metadata information
     def dynamic_info(name)
-      if(@dynamics[name])
-        @dynamics[name][:args]
+      if(dynamics[name])
+        dynamics[name][:args] ||= SparkleStruct.hashish.new
       else
         raise KeyError.new("No dynamic registered with provided name (#{name})")
       end
     end
     alias_method :dynamic_information, :dynamic_info
 
-    # dynamic_name:: Name of dynamic
-    # struct:: SparkleStruct instances
-    # args:: Args to pass to dynamic
-    # Inserts a dynamic into the given SparkleStruct instance
+    # Insert a dynamic into a context
+    #
+    # @param dynamic_name [String, Symbol] dynamic name
+    # @param struct [SparkleStruct] context for insertion
+    # @param args [Object] parameters for dynamic
+    # @return [SparkleStruct]
     def insert(dynamic_name, struct, *args, &block)
       result = false
       if(@dynamics && @dynamics[dynamic_name])
-        struct.instance_exec(*args, &@dynamics[dynamic_name][:block])
+        result = struct.instance_exec(*args, &@dynamics[dynamic_name][:block])
+        if(block_given?)
+          result.instance_exec(&block)
+        end
         result = struct
       else
         result = builtin_insert(dynamic_name, struct, *args, &block)
       end
       unless(result)
-        raise "Failed to locate requested dynamic block for insertion: #{dynamic_name} (valid: #{@dynamics.keys.sort.join(', ')})"
+        raise "Failed to locate requested dynamic block for insertion: #{dynamic_name} (valid: #{(@dynamics || {}).keys.sort.join(', ')})"
       end
       result
     end
 
-    # dynamic_name:: Name of dynamic
-    # struct:: SparkleStruct instances
-    # args:: Args to pass to dynamic
-    # Inserts a builtin dynamic into the given SparkleStruct instance
+    # Insert a builtin dynamic into a context
+    #
+    # @param dynamic_name [String, Symbol] dynamic name
+    # @param struct [SparkleStruct] context for insertion
+    # @param args [Object] parameters for dynamic
+    # @return [SparkleStruct]
     def builtin_insert(dynamic_name, struct, *args, &block)
       if(defined?(SfnAws) && lookup_key = SfnAws.registry_key(dynamic_name))
         _name, _config = *args
@@ -195,10 +235,11 @@ class SparkleFormation
       end
     end
 
-    # hash:: Hash
-    # Attempts to load an SparkleStruct instance from and existing
-    # Hash instance
-    # NOTE: camel keys will do best effort at auto discovery
+    # Convert hash to SparkleStruct instance
+    #
+    # @param hash [Hashish]
+    # @return [SparkleStruct]
+    # @note will do best effort on camel key auto discovery
     def from_hash(hash)
       struct = SparkleStruct.new
       struct._camel_keys_set(:auto_discovery)
@@ -208,16 +249,33 @@ class SparkleFormation
     end
   end
 
+  # @return [Symbol] name of formation
   attr_reader :name
+  # @return [String] base path
   attr_reader :sparkle_path
+  # @return [String] components path
   attr_reader :components_directory
+  # @return [String] dynamics path
   attr_reader :dynamics_directory
+  # @return [String] registry path
   attr_reader :registry_directory
+  # @return [Array] components to load
   attr_reader :components
+  # @return [Array] order of loading
   attr_reader :load_order
 
+  # Create new instance
+  #
+  # @param name [String, Symbol] name of formation
+  # @param options [Hash] options
+  # @option options [String] :sparkle_path custom base path
+  # @option options [String] :components_directory custom components path
+  # @option options [String] :dynamics_directory custom dynamics path
+  # @option options [String] :registry_directory custom registry path
+  # @option options [Truthy, Falsey] :disable_aws_builtins do not load builtins
+  # @yield base context
   def initialize(name, options={}, &block)
-    @name = name
+    @name = name.to_sym
     @sparkle_path = options[:sparkle_path] ||
       self.class.custom_paths[:sparkle_path] ||
       File.join(Dir.pwd, 'cloudformation')
@@ -244,15 +302,21 @@ class SparkleFormation
     end
   end
 
-  # block:: block to execute
-  # Loads block
-  def load_block(block)
+  # Add block to load order
+  #
+  # @param block [Proc]
+  # @return [TrueClass]
+  def block(block)
     @components[:__base__] = self.class.build(&block)
     @load_order << :__base__
+    true
   end
+  alias_method :load_block, :block
 
-  # args:: symbols or paths for component loads
-  # Loads components into instance
+  # Load components into instance
+  #
+  # @param args [String, Symbol] Symbol component names or String paths
+  # @return [self]
   def load(*args)
     args.each do |thing|
       if(thing.is_a?(Symbol))
@@ -268,12 +332,17 @@ class SparkleFormation
   end
 
   # Registers block into overrides
+  #
+  # @param args [Hash] optional arguments to provide state
+  # @yield override block
   def overrides(args={}, &block)
     @overrides << {:args => args, :block => block}
     self
   end
 
-  # Returns compiled Mash instance
+  # Compile the formation
+  #
+  # @return [SparkleStruct]
   def compile
     compiled = SparkleStruct.new
     @load_order.each do |key|
@@ -288,4 +357,14 @@ class SparkleFormation
     compiled
   end
 
+  # @return [Hash] dumped hash
+  def dump
+    MultiJson.load(self.to_json)
+  end
+
+  # @return [String] dumped hash JSON
+  def to_json
+    MultiJson.dump(compile.dump!)
+  end
+
 end