Refactor to support better template processing.

.vscode/launch.json

@@ -2,9 +2,17 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "PowerShell",
             "type": "PowerShell",
             "request": "launch",
+            "name": "PowerShell Launch (debugHarness.ps1)",
+            "program": "${workspaceRoot}/debugHarness.ps1",
+            "args": [],
+            "cwd": "${workspaceRoot}"
+        },
+        {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Launch (current file)",
             "program": "${file}",
             "args": [],
             "cwd": "${file}"

ScriptAnalyzerSettings.psd1

@@ -3,7 +3,7 @@
     # subset of: Error, Warning and Information.
     # Uncomment the following line if you only want Errors and Warnings but
     # not Information diagnostic records.
-    #Severity = @('Error','Warning')
+    Severity = @('Error','Warning')
 
     # Use IncludeRules when you want to run only a subset of the default rule set.
     #IncludeRules = @('PSAvoidDefaultValueSwitchParameter',
@@ -19,7 +19,6 @@
     # and ExcludeRules, the rule will be excluded.
     ExcludeRules = @('PSAvoidUsingWriteHost','PSMissingModuleManifestField')
 
-
     # You can use the following entry to supply parameters to rules that take parameters.
     # For instance, the PSAvoidUsingCmdletAliases rule takes a whitelist for aliases you
     # want to allow.

debugHarness.ps1

@@ -11,15 +11,31 @@ $OutDir = "$PSScriptRoot\examples\Out"
 Remove-Item $OutDir -Recurse -ErrorAction SilentlyContinue
 
 $PlasterParams = @{
-    TemplatePath = "$PSScriptRoot\examples\NewModule"
+    TemplatePath = "$PSScriptRoot\src\Templates\NewPowerShellModule"
     DestinationPath = $OutDir
     ModuleName = 'FooUtils'
-    ModuleDesc = 'Utilities for Foo.'
-    FullName = 'John Q. Doe'
     Version = '1.2.0'
-    Options = 'Git','psake','Pester','PSScriptAnalyzer','platyPS'
+    AddTest = 'Yes'
     Editor = 'VSCode'
-    License = 'MIT'
 }
 
+# $PlasterParams = @{
+#     TemplatePath = "$PSScriptRoot\examples\NewDscResourceScript"
+#     DestinationPath = $OutDir
+#     TargetResourceName = 'ZipFile'
+#     Ensure = 'Yes'
+# }
+
+# $PlasterParams = @{
+#     TemplatePath = "$PSScriptRoot\examples\NewModule"
+#     DestinationPath = $OutDir
+#     ModuleName = 'FooUtils'
+#     ModuleDesc = 'Utilities for Foo.'
+#     FullName = 'John Q. Doe'
+#     Version = '1.2.0'
+#     Options = 'Git','psake','Pester','PSScriptAnalyzer','platyPS'
+#     Editor = 'VSCode'
+#     License = 'MIT'
+# }
+
 Invoke-Plaster @PlasterParams -Force

docs/en-US/about_Plaster_CreatingAManifest.help.md

@@ -222,8 +222,6 @@ Some elements use the encoding attribute, while not a common attribute, has a co
 
 Element attribute values support the use of Plaster parameters, which are parameter values that can be expanded into file names, or other pieces of information the template deals with. These map to available parameters, licenses and other data that is provided in the template.
 
-TODO: Explain Plaster parameters and provide a list.
-
 ### Content element: File
 One or more files can be selected (using wild cards like `*`) with each file element. Attribute values support the inclusion of Plaster parameters to control (as an example) the location or the name of the resulting file.
 
@@ -365,15 +363,33 @@ Available attributes for this content element:
 ```
 
 ## Attribute and Condition Evaluation
-Most of the XML attributes in a manifest can contain variables or expressions that evaluate to a string.
-The attribute's value is passed into a constrained runspace for evaluation and the resulting string is used for template processing.
-Note the XML attributes on the `<parameter>` directive are not processed this way because they are processed during `dynamicparam` execution.
+Many of the XML attributes in a manifest can contain variables or expressions that evaluate to a string.
+The attribute's value is passed into a constrained runspace in the context of a double quoted string for interpolation and the resulting string is used for template processing.
+Note the XML attributes on the `<parameter>` directive, except for the `default` and `prompt` attributes, are not processed this way because they are processed during `dynamicparam` execution.
 At that time, the constrained runspace in which these expressions are evaluated has not been created.
 
 Many of the directives in a Plaster manifest have a `condition` attribute.
 The contents of this condition attribute are evaluated in the same constrained runspace that attribute values are evaluated in.
 However, in the case of a `condition` attribute the resulting value is coerced to a [bool] which determines whether the associated directive is executed.
 
+## TemplateFile processing
+A file that is processed with the `<templateFile>` directive will be processed, replacing script expression delimiters and script block delimiters with PowerShell generated text.
+The script expression delimiter is `<%= %>`.  The contents of a script expression delimiter are executed and the results cast to a string and inserted into the file.
+
+The script block delimiter is:
+```
+<%
+    if ($PLASTER_PARAM_Ensure -eq 'Yes') {
+"        # Ensure the presence/absene of the resource."
+"        [ValidateSet('Present','Absent')]"
+"        [string]"
+"        `$Ensure = 'Present'"
+    }
+%>
+```
+Where both starting and closing delimiter must appear in column zero.
+The contents of a script block delimiter are executed and the results cast to a string array and inserted into the file.
+
 ## PowerShell constrained runspace
 
 The manifest parameters you define are available via variables named `PLASTER_PARAM_<parameter-name>`.

src/Templates/NewDscResourceScript/plasterManifest.xml → examples/NewDscResourceScript/plasterManifest.xml

@@ -30,22 +30,9 @@
     <content>
         <message>&#10;&#10;Scaffolding your PowerShell DSC Resource Script...&#10;&#10;&#10;</message>
 
-        <templateFile source='resource.ps1'
+        <templateFile source='resource.ps1.txt'
                       destination='${PLASTER_PARAM_TargetResourceName}.ps1'/>
 
-        <modify condition="$PLASTER_PARAM_Ensure -eq 'Yes'"
-                path="${PLASTER_PARAM_TargetResourceName}.ps1"
-                encoding="UTF8">
-            <replace>
-                <original><![CDATA[(?si)(?<=param\s*\()(.)]]></original>
-                <substitute><![CDATA[
-        # Ensure the presence/absence of the resource.
-        [ValidateSet("Present","Absent")]
-        [string]
-        $Ensure = "Present"]]></substitute>
-            </replace>
-        </modify>
-
         <message>
 
 Your new PowerShell DSC Resource script file '${PLASTER_DestinationPath}${PLASTER_DirSepChar}${PLASTER_PARAM_TargetResourceName}.ps1' has been created.

src/Templates/NewDscResourceScript/resource.ps1 → examples/NewDscResourceScript/resource.ps1.txt

@@ -3,6 +3,14 @@
 function Get-<%=$PLASTER_PARAM_TargetResourceName%> {
     [OutputType([Hashtable])]
     param (
+<%
+    if ($PLASTER_PARAM_Ensure -eq 'Yes') {
+"        # Ensure the presence/absene of the resource."
+"        [ValidateSet('Present','Absent')]"
+"        [string]"
+"        `$Ensure = 'Present'"
+    }
+%>
     )
 
     # Return a hashtable of name/value pairs representing the target resource instance.
@@ -16,6 +24,14 @@ function Get-<%=$PLASTER_PARAM_TargetResourceName%> {
 function Set-<%=$PLASTER_PARAM_TargetResourceName%> {
     [CmdletBinding(SupportsShouldProcess=$true)]
     param (
+<%
+    if ($PLASTER_PARAM_Ensure -eq 'Yes') {
+"        # Ensure the presence/absene of the resource."
+"        [ValidateSet('Present','Absent')]"
+"        [string]"
+"        `$Ensure = 'Present'"
+    }
+%>
     )
 
     # Set the target resource instance based on parameters passed into function.
@@ -30,6 +46,14 @@ function Test-<%=$PLASTER_PARAM_TargetResourceName%> {
     [CmdletBinding()]
     [OutputType([System.Boolean])]
     param (
+<%
+    if ($PLASTER_PARAM_Ensure -eq 'Yes') {
+"        # Ensure the presence/absene of the resource."
+"        [ValidateSet('Present','Absent')]"
+"        [string]"
+"        `$Ensure = 'Present'"
+    }
+%>
     )
 
     [bool]$result = $false