DOC update for guard_interpreter, powershell_script, and convert_boolean_return

1 files changed, 106 insertions, 0 deletions

diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index dff930ac09..1657d86f3f 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -177,3 +177,109 @@ end
 * installer_type - The type of package being installed. Can be auto-detected. Currently only :msi is supported.
 * timeout - The time in seconds allowed for the package to successfully be installed. Defaults to 600 seconds.
 * returns - Return codes that signal a successful installation. Defaults to 0.
+
+### New resource attribute: `guard_interpreter`
+Resources have a new attribute, `guard_interpreter`, which specifies a
+Chef script resource's that should be used to evaluate a
+string passed to a guard. Any attributes for that resource may be specified in
+the options that normally follow the guard's command string argument. For example:
+
+    # Use a guard command that is valid for bash but not for csh
+    bash 'backupsettings' do
+      guard_interpreter :bash
+      code 'cp ~/appsettings.json ~/backup/appsettings.json'
+      not_if '[[ -e ./appsettings.json ]]', :cwd => '~/backup'
+    end
+
+The argument for `guard_interpreter` may be set to any of the following values:
+* The symbol name for a Chef Resource derived from the Chef `script` resource
+  such as `:bash`, `:powershell_script`, etc.
+* The symbol `:default` which means that a resource is not used to evaluate
+  the guard command argument, it is simply executed by the default shell as in
+  previous releases of Chef.
+
+By default, guard_interpreter is set to `:default` in this release.
+
+#### Attribute inheritance with `guard_interpreter`
+
+When `guard_interpreter` is used, the resource that evaluates the command will
+also inherit certain attribute values from the resource that contains the
+guard.
+
+Inherited attributes for all `script` resources are:
+
+* :cwd
+* :environment
+* :group
+* :path
+* :user
+* :umask
+
+For the `powershell_script` resource, the following attribute is inherited:
+* :architecture
+
+Inherited attributes may be overridden by specifying the same attribute as an
+argument to the guard itself.
+
+#### Guard inheritance example
+
+In the following example, the :environment hash only needs to be set once
+since the `bash` resource that execute the guard will inherit the same value:
+
+    script "javatooling" do
+      environment {"JAVA_HOME" => '/usr/lib/java/jdk1.7/home'}
+      code 'java-based-daemon-ctl.sh -start'
+      not_if 'java-based-daemon-ctl.sh -test-started' # No need to specify environment again
+    end
+
+### New `powershell_script` resource attribute: `convert_boolean_return`
+
+The `powershell_script` resource has a new attribute, `convert_boolean_return`
+that causes the script interpreter to return 0 if the last line of the command
+evaluted by PowerShell results in a boolean PowerShell data type that is true, or 1 if
+it results in a boolean PowerShell data type that is false. For example, the
+following two fragments will run successfully without error:
+
+    powershell_script 'false' do
+      code '$false'
+    end
+
+    powershell_script 'true' do
+      code '$true'
+    end
+
+When `convert_boolean_return` is set to `true`, the "true" case above will
+still succeed, but the false case will raise an exception:
+
+    # Raises an exception
+    powershell_script 'false' do
+      convert_boolean_return true
+      code '$false'
+    end
+
+When used at recipe scope, the default value of `convert_boolean_return` is
+`false` in this release. However, if `guard_interpreter` is set to
+`:powershell_script`, the guard expression will be evaluted with a
+`powershell_script` resource that has the `convert_boolean_return` attribute
+set to `true`.
+
+#### Guard command example
+
+The behavior of `convert_boolean_return` is similar to the "$?"
+expression's value after use of the `test` command in Unix-flavored shells and
+its translation to an exit code for the shell. Since this attribute is set to
+`true` when `powershell_script` is used via the `guard_interpreter` to
+evaluate the guard expression, the behavior of `powershell_script` is very
+similar to guards executed with Unix shell interpreters as seen below:
+
+    bash 'make_safe_backup' do
+      code 'cp ~/data/nodes.json ~/data/nodes.bak'
+      not_if 'test -e ~/data/nodes.bak'
+    end
+
+    # convert_boolean_return is true by default in guards
+    powershell_script 'make_safe_backup' do
+      guard_interpreter :powershell_script
+      code 'cp ~/data/nodes.json ~/data/nodes.bak'
+      not_if 'test-path ~/data/nodes.bak'
+    end