WIP: Tests to show it works and how to use it

Author: Jaykul

Source/Classes/10. ParameterPosition.ps1

@@ -1,4 +1,4 @@
-class TextReplace {
+class TextReplacement {
     [int]$StartOffset = 0
     [int]$EndOffset = 0
     [string]$Text = ''

Source/Classes/11. TextReplace.ps1 Source/Classes/10. TextReplacement.ps1Source/Classes/11. TextReplace.ps1 renamed to Source/Classes/10. TextReplacement.ps1

@@ -0,0 +1,51 @@
+using namespace System.Management.Automation.Language
+using namespace System.Collections.Generic
+
+class ParameterExtractor : AstVisitor {
+    [System.Collections.Specialized.OrderedDictionary]$Parameters = @{}
+    [int]$InsertLineNumber = -1
+    [int]$InsertColumnNumber = -1
+    [int]$InsertOffset = -1
+
+    ParameterExtractor([Ast]$Ast) {
+        $ast.Visit($this)
+    }
+
+    [AstVisitAction] VisitParamBlock([ParamBlockAst]$ast) {
+        if ($Ast.Parameters) {
+            $Text = $ast.Extent.Text -split "\r?\n"
+
+            $FirstLine = $ast.Extent.StartLineNumber
+            $NextLine = 1
+            foreach ($parameter in $ast.Parameters | Select-Object Name -Expand Extent) {
+                $this.Parameters.Add($parameter.Name, ([TextReplacement]@{
+                    StartOffset = $parameter.StartOffset
+                    Text        = if (($parameter.StartLineNumber - $FirstLine) -ge $NextLine) {
+                        Write-Debug "Extracted parameter $($Parameter.Name) with surrounding lines"
+                        # Take lines after the last parameter
+                        $Lines = @($Text[$NextLine..($parameter.EndLineNumber - $FirstLine)].Where{ ![string]::IsNullOrWhiteSpace($_) })
+                        # If the last line extends past the end of the parameter, trim that line
+                        if ($Lines.Length -gt 0 -and $parameter.EndColumnNumber -lt $Lines[-1].Length) {
+                            $Lines[-1] = $Lines[-1].SubString($parameter.EndColumnNumber)
+                        }
+                        # Don't return the commas, we'll add them back later
+                                ($Lines -join "`n").TrimEnd(",")
+                    } else {
+                        Write-Debug "Extracted parameter $($Parameter.Name) text exactly"
+                        $parameter.Text.TrimEnd(",")
+                    }
+                }))
+                $NextLine = 1 + $parameter.EndLineNumber - $FirstLine
+            }
+
+            $this.InsertLineNumber = $ast.Parameters[-1].Extent.EndLineNumber
+            $this.InsertColumnNumber = $ast.Parameters[-1].Extent.EndColumnNumber
+            $this.InsertOffset = $ast.Parameters[-1].Extent.EndOffset
+        } else {
+            $this.InsertLineNumber = $ast.Extent.EndLineNumber
+            $this.InsertColumnNumber = $ast.Extent.EndColumnNumber - 1
+            $this.InsertOffset = $ast.Extent.EndOffset - 1
+        }
+        return [AstVisitAction]::StopVisit
+    }
+}

Source/Classes/20. ParameterExtractor.ps1

@@ -1,24 +1,19 @@
 using namespace System.Management.Automation.Language
 using namespace System.Collections.Generic
-class TextReplace {
-    [int]$StartOffset = 0
-    [int]$EndOffset = 0
-    [string]$Text = ''
-}
 
 class ModuleBuilderGenerator {
-    hidden [List[TextReplace]]$Replacements = @()
+    hidden [List[TextReplacement]]$Replacements = @()
 
     [void] Replace($StartOffset, $EndOffset, $Text) {
-        $this.Replacements.Add([TextReplace]@{
+        $this.Replacements.Add([TextReplacement]@{
                 StartOffset = $StartOffset
                 EndOffset   = $EndOffset
                 Text        = $Text
             })
     }
 
     [void] Insert($StartOffset, $Text) {
-        $this.Replacements.Add([TextReplace]@{
+        $this.Replacements.Add([TextReplacement]@{
                 StartOffset = $StartOffset
                 EndOffset   = $StartOffset
                 Text        = $Text
@@ -43,7 +38,7 @@ class ModuleBuilderGenerator {
 
         $Additional = $AdditionalParameters.Parameters.Where{ $_.Name -notin $ExistingParameters.Parameters.Name }
         if (($Text = $Additional.Text -join ",`n`n")) {
-            $Replacement = [TextReplace]@{
+            $Replacement = [TextReplacement]@{
                 StartOffset = $ExistingParameters.InsertOffset
                 EndOffset   = $ExistingParameters.InsertOffset
                 Text        = if ($ExistingParameters.Parameters.Count -gt 0) {
@@ -60,7 +55,7 @@ class ModuleBuilderGenerator {
 
 
 
-    [List[TextReplace]]Generate([Ast]$ast) {
+    [List[TextReplacement]]Generate([Ast]$ast) {
         $ast.Visit($this)
         return $this.Replacements
     }

Source/Classes/21. ParameterExtractor.ps1

@@ -5,21 +5,26 @@ class ParameterGenerator : ModuleBuilderGenerator {
     [System.Management.Automation.HiddenAttribute()]
     [ParameterExtractor]$AdditionalParameterCache
 
-    [ParameterExtractor]GetAdditional() {
+    ParameterGenerator($Path) : base($Path) {}
+
+    [System.Collections.Generic.Dictionary[string, TextReplacement]]GetAdditional() {
         if (!$this.AdditionalParameterCache) {
-            $this.AdditionalParameterCache = $this.Aspect
+            $this.AdditionalParameterCache = [ParameterExtractor]$this.Ast
         }
-        return $this.AdditionalParameterCache
+        return $this.AdditionalParameterCache.Parameters
     }
 
     [AstVisitAction] VisitFunctionDefinition([FunctionDefinitionAst]$ast) {
         if (!$ast.Where($this.Where)) {
             return [AstVisitAction]::SkipChildren
         }
+
         $Existing = [ParameterExtractor]$ast
-        $Additional = $this.GetAdditional().Parameters.Where{ $_.Name -notin $Existing.Parameters.Name }
-        if (($Text = $Additional.Text -join ",`n`n")) {
-            $Replacement = [TextReplace]@{
+
+        $AdditionalParameters = $this.GetAdditional()
+        $Additional = $AdditionalParameters.Keys.Where{ $_.Name -notin $Existing.Parameters.Name }
+        if (($Text = $AdditionalParameters.Values.Text -join ",`n`n")) {
+            $Replacement = [TextReplacement]@{
                 StartOffset = $Existing.InsertOffset
                 EndOffset   = $Existing.InsertOffset
                 Text        = if ($Existing.Parameters.Count -gt 0) {
@@ -29,7 +34,7 @@ class ParameterGenerator : ModuleBuilderGenerator {
                 }
             }
 
-            Write-Debug "Adding parameters to $($ast.name): $($Additional.Name -join ', ')"
+            Write-Debug "Adding parameters to $($ast.name): $($Additional.Keys -join ', ')"
             $this.Replacements.Add($Replacement)
         }
         return [AstVisitAction]::SkipChildren

…e/Classes/20. ModuleBuilderGenerator.ps1 …e/Classes/30. ModuleBuilderGenerator.ps1Source/Classes/20. ModuleBuilderGenerator.ps1 renamed to Source/Classes/30. ModuleBuilderGenerator.ps1 Source/Classes/20. ModuleBuilderGenerator.ps1 renamed to Source/Classes/30. ModuleBuilderGenerator.ps1

@@ -11,21 +11,23 @@ class BlockGenerator : ModuleBuilderGenerator {
     [System.Management.Automation.HiddenAttribute()]
     [NamedBlockAst]$EndBlockTemplate
 
-    [List[TextReplace]]Generate([Ast]$ast) {
-        if (!($this.BeginBlockTemplate = $this.Aspect.Find({ $args[0] -is [NamedBlockAst] -and $args[0].BlockKind -eq "Begin" }, $false))) {
-            Write-Debug "No Aspect for BeginBlock"
+    BlockGenerator($Path) : base($Path) {}
+
+    [List[TextReplacement]]Generate([Ast]$ast) {
+        if (!($this.BeginBlockTemplate = $this.Ast.Find({ $args[0] -is [NamedBlockAst] -and $args[0].BlockKind -eq "Begin" }, $false))) {
+            Write-Debug "No Generator for BeginBlock"
         } else {
-            Write-Debug "BeginBlock Aspect: $($this.BeginBlockTemplate)"
+            Write-Debug "BeginBlock Generator: $($this.BeginBlockTemplate)"
         }
-        if (!($this.ProcessBlockTemplate = $this.Aspect.Find({ $args[0] -is [NamedBlockAst] -and $args[0].BlockKind -eq "Process" }, $false))) {
-            Write-Debug "No Aspect for ProcessBlock"
+        if (!($this.ProcessBlockTemplate = $this.Ast.Find({ $args[0] -is [NamedBlockAst] -and $args[0].BlockKind -eq "Process" }, $false))) {
+            Write-Debug "No Generator for ProcessBlock"
         } else {
-            Write-Debug "ProcessBlock Aspect: $($this.ProcessBlockTemplate)"
+            Write-Debug "ProcessBlock Generator: $($this.ProcessBlockTemplate)"
         }
-        if (!($this.EndBlockTemplate = $this.Aspect.Find({ $args[0] -is [NamedBlockAst] -and $args[0].BlockKind -eq "End" }, $false))) {
-            Write-Debug "No Aspect for EndBlock"
+        if (!($this.EndBlockTemplate = $this.Ast.Find({ $args[0] -is [NamedBlockAst] -and $args[0].BlockKind -eq "End" }, $false))) {
+            Write-Debug "No Generator for EndBlock"
         } else {
-            Write-Debug "EndBlock Aspect: $($this.EndBlockTemplate)"
+            Write-Debug "EndBlock Generator: $($this.EndBlockTemplate)"
         }
 
         $ast.Visit($this)
@@ -44,7 +46,7 @@ class BlockGenerator : ModuleBuilderGenerator {
                 $BeginBlockText = ($BeginExtent.Text -replace "^begin[\s\r\n]*{|}[\s\r\n]*$", "`n").Trim("`r`n").TrimEnd("`r`n ")
 
 
-                $Replacement = [TextReplace]@{
+                $Replacement = [TextReplacement]@{
                     StartOffset = $BeginExtent.StartOffset
                     EndOffset   = $BeginExtent.EndOffset
                     Text        = $this.BeginBlockTemplate.Extent.Text.Replace("existingcode", $BeginBlockText)
@@ -73,7 +75,7 @@ class BlockGenerator : ModuleBuilderGenerator {
                     $StartOffset = $ProcessBlockExtent.StartOffset
                 }
 
-                $Replacement = [TextReplace]@{
+                $Replacement = [TextReplacement]@{
                     StartOffset = $StartOffset
                     EndOffset   = $ProcessBlockExtent.EndOffset
                     Text        = $this.ProcessBlockTemplate.Extent.Text.Replace("existingcode", $ProcessBlockText)
@@ -103,7 +105,7 @@ class BlockGenerator : ModuleBuilderGenerator {
                     $EndBlockText = ($EndBlockExtent.Text -replace "^end[\s\r\n]*{|}[\s\r\n]*$", "`n").Trim("`r`n").TrimEnd("`r`n ")
                 }
 
-                $Replacement = [TextReplace]@{
+                $Replacement = [TextReplacement]@{
                     StartOffset = $StartOffset
                     EndOffset   = $EndBlockExtent.EndOffset
                     Text        = $this.EndBlockTemplate.Extent.Text.Replace("existingcode", $EndBlockText)

Source/Classes/22. ParameterGenerator.ps1 Source/Classes/40. ParameterGenerator.ps1Source/Classes/22. ParameterGenerator.ps1 renamed to Source/Classes/40. ParameterGenerator.ps1

@@ -11,7 +11,8 @@
 
             # Release Notes have to be here, so we can update them
             ReleaseNotes   = '
-            Add support for Aspect Oriented Programming (AOP) with the new `Aspects` parameter.
+            Add support for Generators, so you can weave in solutions for cross-cutting concerns at "build" time.
+            Specifically targeting support for module-wide common parameters, standardized fall-back error handling, etc.
             '
 
             # Tags applied to this module. These help with module discovery in online galleries.

Source/Classes/23. BlockGenerator.ps1 Source/Classes/50. BlockGenerator.ps1Source/Classes/23. BlockGenerator.ps1 renamed to Source/Classes/50. BlockGenerator.ps1

@@ -111,9 +111,9 @@ function GetBuildInfo {
         }
     }
 
-    # Make sure Aspects is an array of objects (instead of hashtables)
-    if ($BuildInfo.Aspects) {
-        $BuildInfo.Aspects = $BuildInfo.Aspects | ForEach-Object {
+    # Make sure Generators is an array of objects (instead of hashtables)
+    if ($BuildInfo.Generators) {
+        $BuildInfo.Generators = $BuildInfo.Generators | ForEach-Object {
             if ($_ -is [hashtable]) {
                 [PSCustomObject]$_
             } else {

Source/ModuleBuilder.psd1

@@ -5,53 +5,54 @@ function InvokeGenerator {
         .DESCRIPTION
             This is an aspect-oriented programming approach for adding cross-cutting features to functions in a module.
 
-            The [ModuleBuilderGenerator] implementations are [AstVisitors] that return [TextReplace] object representing modifications to be performed on the source.
+            The [ModuleBuilderGenerator] implementations are [AstVisitors] that return [TextReplacement] objects representing modifications to be performed on the source.
     #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', 'Function', Justification = 'PSSA reads the AST wrong')]
     [CmdletBinding()]
     param(
-        # The path to the RootModule psm1 to merge the aspect into
+        # The path to the RootModule psm1 to apply the Generator to
         [Parameter(Mandatory, Position = 0)]
         [string]$RootModule,
 
         # The name of the ModuleBuilder Generator to invoke.
-        # There are two built in:
-        # - MergeBlocks. Supports Before/After/Around blocks for aspects like error handling or authentication.
-        # - AddParameter. Supports adding common parameters to functions (usually in conjunction with MergeBlock that use those parameters)
+        # There are only two Generators built in:
+        # - ParameterGenerator. Supports adding parameters to functions in the module. Parameters come from a template file, which must be a script with a param block.
+        # - BlockGenerator.  Supports adding code before, after, and around existing blocks for generators like error handling, authentication, and implementations for common parameters. The added blocks come from a template file, which must be a script with named begin/process/end blocks.
         [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
-        [ValidateScript({ (($_ -As [Type]), ("${_}Aspect" -As [Type])).BaseType -eq [ModuleBuilderGenerator] })]
-        [string]$Action,
+        [ValidateScript({ (($_ -As [Type]), ("${_}Generator" -As [Type])).BaseType -eq [ModuleBuilderGenerator] })]
+        [string]$Generator,
 
-        # The name(s) of functions in the module to run the generator against. Supports wildcards.
+        # The name(s) of functions in the RootModule to run the generator against. Supports wildcards.
         [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
         [string[]]$Function,
 
-        # The name of the script path or function that contains the base which drives the generator
+        # The name of a template file that customizes the generator
         [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
-        [string]$Source
+        [string]$Template
     )
     process {
         #! We can't reuse the AST because it needs to be updated after we change it
         #! But we can handle this in a wrapper
-        Write-Verbose "Parsing $RootModule for $Action with $Source"
+        Write-Verbose "Parsing $RootModule for $Generator with $Template"
         $Ast = ConvertToAst $RootModule
 
-        $Action = if ($Action -As [Type]) {
-            $Action
-        } elseif ("${Action}Aspect" -As [Type]) {
-            "${Action}Aspect"
+        $Generator = if ($Generator -As [Type]) {
+            $Generator
+        } elseif ("${Generator}Generator" -As [Type]) {
+            "${Generator}Generator"
         } else {
-            throw "Can't find $Action ModuleBuilderGenerator"
+            throw "Can't find $Generator ModuleBuilderGenerator"
         }
 
-        $Aspect = New-Object $Action -Property @{
+        $Generator = New-Object $Generator -Property @{
             Where  = { $Func = $_; $Function.ForEach({ $Func.Name -like $_ }) -contains $true }.GetNewClosure()
-            Aspect = @(Get-Command (Join-Path $AspectDirectory $Source), $Source -ErrorAction Ignore)[0].ScriptBlock.Ast
+            Generator = @(Get-Command (Join-Path $GeneratorDirectory $Template), $Template -ErrorAction Ignore)[0].ScriptBlock.Ast
         }
 
         #! Process replacements from the bottom up, so the line numbers work
         $Content = Get-Content $RootModule -Raw
-        Write-Verbose "Generating $Action in $RootModule"
-        foreach ($replacement in $Aspect.Generate($Ast.Ast) | Sort-Object StartOffset -Descending) {
+        Write-Verbose "Generating $Generator in $RootModule"
+        foreach ($replacement in $Generator.Generate($Ast.Ast) | Sort-Object StartOffset -Descending) {
             $Content = $Content.Remove($replacement.StartOffset, ($replacement.EndOffset - $replacement.StartOffset)).Insert($replacement.StartOffset, $replacement.Text)
         }
         Set-Content $RootModule $Content