sparkle_formation 1.0.4 → 1.1.0

data/docs/compile-time-parameters.md

@@ -0,0 +1,182 @@
+---
+title: "Compile Time Parameters"
+category: "dsl"
+weight: 10
+anchors:
+  - title: "Usage"
+    url: "#usage"
+  - title: "Template Nesting"
+    url: "#template-nesting"
+---
+
+## Compile Time Parameters
+
+Compile time parameters are parameters utilized during the compilation
+of a template. These parameters can _only_ be used via the SparkleFormation
+library. It is for this reason that compile time parameters are generally
+discouraged from use. In most situations the structure of the template
+can be refactored to remove any requirement of compile time parameters. To
+handle the cases that fall outside of "most situations", SparkleFormation
+provides support for compile time parameters.
+
+### Usage
+
+Compile time parameters are defined during the instantiation of a template:
+
+~~~ruby
+SparkleFormation.new(:test,
+  :compile_time_parameters => {
+    :number_of_nodes => {
+      :type => :number,
+      :default => 1
+    }
+  }
+) do
+
+  state!(:number_of_nodes).times do |i|
+    dynamic!(:ec2_instance, "node_#{i}")
+  end
+
+end
+~~~
+
+#### Parameter Declaration
+
+Declaring compile time parameters is done via the `:compile_time_parameters`
+option when instantiating a new template. This option expects a `Hash` value
+in which the keys are parameter names, and their respective values are a `Hash`
+defining options for the parameter. The available items within the option
+`Hash` for compile time parameters:
+
+* `:type` - Data type of parameter
+  * Required: yes
+  * Valid: `:number`, `:string`
+  * Default: none
+* `:description` - Description of the parameter
+  * Required: no
+  * Valid: `String`
+  * Default: none
+* `:default` - Default value for parameter
+  * Required: no
+  * Valid: `String`, `Integer`
+  * Default: none
+* `:multiple` - Accept multiple values
+  * Required: no
+  * Valid: `TrueClass`, `FalseClass`
+  * Default: `false`
+* `:prompt_when_nested` - Prompt for value when template is nested
+  * Required: no
+  * Valid: `TrueClass`, `FalseClass`
+  * Default: `true`
+
+##### Multiple value support
+
+The `:multiple` option for compile time parameters will automatically convert
+a received comma-delimited list into an `Array` of items. Each item in the list
+must be the expected type for the parameter. For example, a compile time parameter
+defined as:
+
+~~~ruby
+SparkleFormation.new(:test,
+  :compile_time_parameters => {
+    :network_ids => {
+      :type => :string,
+      :multiple => true
+    }
+  }
+)
+~~~
+
+If the value provided for this parameter is:
+
+~~~
+network-a2413, network-cs214, network-as113
+~~~
+
+The resulting value when accessed will be:
+
+~~~ruby
+[
+  "network-a2413",
+  "network-cs214",
+  "network-as113"
+]
+~~~
+
+##### Prompting when nested
+
+The `:prompt_when_nested` is used by implementations to suppress parameter prompts
+when the template is encountered in a nested context. This allows for parent templates
+to handle compile time parameters for a nested template, but the nested template still
+retains its ability to be built in a standalone context.
+
+#### Accessing Parameter Values
+
+Compile time parameter values can be accessed via the `state!` method. If a compile time
+parameter has been defined for a template, and no value has been provided when that template
+is compiled, `state!` will raise an `ArgumentError`. This exception will only be raised on
+defined compile time parameters, and not other values that may be persisted within the state.
+
+Example usage:
+
+~~~ruby
+SparkleFormation.new(:test,
+  :compile_time_parameters => {
+    :number_of_nodes => {
+      :type => :number,
+      :default => 1
+    }
+  }
+) do
+
+  state!(:number_of_nodes).times do |i|
+    dynamic!(:ec2_instance, "node_#{i}")
+  end
+
+end
+~~~
+
+#### Template Modification
+
+When compile time parameters are present SparkleFormation will automatically adjust the outputs
+of the template to include a `CompileState` output. The output will contain a JSON dump of the
+compile time parameter values used to generate the template. This allows update requests to
+fetch the previous state and seed the compilation of the updated template. This approach provides
+consistency and removes any requirement of prior knowledge about how a template was used to build
+a stack.
+
+### Template Nesting
+
+Compile time parameters are local to a given template instance. A parent template can provide
+compile time parameters when nesting a template. This is done using the `:parameters` option
+when nesting:
+
+~~~ruby
+SparkleFormation.new(:node_generator,
+  :parameters => {
+    :number_of_nodes => {
+      :type => :number,
+      :prompt_when_nested => false
+    }
+  }
+) do
+  state!(:number_of_nodes).times do |i|
+    dynamic!(:ec2_instance, "node_#{i}")
+  end
+
+end
+
+SparkleFormation.new(:root) do
+  nest!(:nested_template,
+    :parameters => {
+      :number_of_nodes => 5
+    }
+  )
+end
+~~~
+
+In this example the `:root` template is providing the compile time parameter `:number_of_nodes`
+explicitly to the `:node_generator` template. Due to the compile time parameter option
+`:prompt_when_nested` being set to false, when the `:root` template is compiled, no prompt
+will be received for the `:number_of_nodes` compile time parameter. However, if the
+`:node_generator` template is compiled directly, the prompt will be received.

data/docs/helper-methods.md

@@ -0,0 +1,157 @@
+---
+title: "Helper Methods"
+category: "dsl"
+weight: 5
+anchors:
+  - title: "Dynamics"
+    url: "#dynamics"
+  - title: "Registries"
+    url: "#registries"
+  - title: "Nests"
+    url: "#nests"
+  - title: "Local System Call"
+    url: "#local-system-call"
+  - title: "AWS Helpers"
+    url: "#aws-helpers"
+---
+
+## Helper methods
+
+SparkleFormation provides a collection of helper methods
+for facilitating faster development and cleaner code. Some
+helpers provide easier access to underlying SparkleFormation
+functionality, while others provide automatic generation of
+known template data structures.
+
+### Functionality Helpers
+
+#### Dynamics
+
+Inserting a dynamic directly requires calling out to the
+singleton method and providing the local context, which
+looks like this:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  SparkleFormation.insert(:my_dynamic, self, :some => [:value])
+end
+~~~
+
+The helper compacts this call to:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  dynamic!(:my_dynamic, :some => [:value])
+end
+~~~
+
+#### Registries
+
+Registries are used by calling out the singleton method and
+providing the local context:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  SparkleFormation::Registry.insert(:my_registry, self, :some => [:value])
+end
+~~~
+
+and can be compacted to:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  registry!(:my_registry, :some => [:value])
+end
+~~~
+
+#### Nests
+
+Nests are used by calling out to the singleton method and
+providing the local context:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  SparkleFormation.nest(:my_template, self, :some => [:value])
+end
+~~~
+
+and can be compacted to:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  nest!(:my_template, :some => [:value])
+end
+~~~
+
+#### Other
+
+##### Local system call
+
+Use the `system!` helper method to shell out to the local system,
+execute a command, and return the string output:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters.creator.default system!('whoami')
+end
+~~~
+
+### Generation Helpers
+
+#### AWS Helpers
+
+Data generation helpers are available for all the AWS
+intrinsic functions and pseudo parameters:
+
+
+##### Base intrinsic functions
+
+* `base64!(VAL)`
+* `find_in_map!(A, B, C)`
+* `attr!(RESOURCE, ATTRIBUTE)`
+* `azs!(REGION)`
+* `join!(VAL1, VAL2, ...)`
+* `select!(INDEX, ITEM)`
+* `ref!(NAME)`
+
+##### Pseudo Parameters
+
+* `account_id!`
+* `notification_arns!`
+* `no_value!`
+* `region!`
+* `stack_id!`
+* `stack_name!`
+
+##### Conditional functions
+
+AWS CFN supports runtime conditions. Helpers for building conditions:
+
+* `and!(VAL1, VAL2, ...)`
+* `equals!(VAL1, VAL2)`
+* `not!(VAL)`
+* `or!(VAL1, VAL2, ...)`
+* `condition!(CONDITION_NAME)`
+
+Helpers for using conditions:
+
+* `if!(CONDITION_NAME)`
+
+~~~ruby
+SparkleFormation.new(:test) do
+...
+  some_value if!(:my_condition, TRUE_VALUE, FALSE_VALUE)
+...
+end
+~~~
+
+* `on_condition!(CONDITION_NAME)`
+
+~~~ruby
+SparkleFormation.new(:test) do
+...
+  resources.my_cool_resource do
+    on_condition!(:stack_is_cool)
+...
+end
+~~~