Refactor handling of CommandSuite settings file (#23)

SeeminglyScience · SeeminglyScience · commit f1b0e75943aa · 2018-07-05T18:04:13.000-04:00
- Generate default settings file using StringBuilder instead of
  PSStringTemplate

- Add function Import-CommandSuite to start initialization on
  explicit module import.

- Add a FileSystemWatcher to watch for changes to the settings file

- Add on module remove event handler to dispose of the
  FileSystemWatcher and unregister editor commands

- Fix an issue where an internal setting would be added to the default
  settings file
diff --git a/README.md b/README.md
@@ -33,32 +33,21 @@ Install-Module EditorServicesCommandSuite -Scope CurrentUser
 
 ```powershell
 # Place this in your VSCode profile
-Import-Module EditorServicesCommandSuite
-Import-EditorCommand -Module EditorServicesCommandSuite
+Import-CommandSuite
 ```
 
 ```powershell
 # Or copy this command and paste it into the integrated console
-psedit $profile;$psEditor|% g*t|% c*e|% i* "Import-Module EditorServicesCommandSuite`nImport-EditorCommand -Module EditorServicesCommandSuite`n" 1 1 1 1
+psedit $profile;$psEditor|% g*t|% c*e|% i* "Import-CommandSuite`n" 1 1 1 1
 ```
 
 ## Importing
 
-You can call any of the editor commands as functions like you would from any module. Or you can import them as registered editor commands in Editor Services.
-
-### Import all Editor Commands
-
 ```powershell
-Import-Module EditorServicesCommandSuite
-Import-EditorCommand -Module EditorServicesCommandSuite
+Import-CommandSuite
 ```
 
-### Import specific Editor Commands
-
-```powershell
-Import-Module EditorServicesCommandSuite
-Get-Command ConvertTo-MarkdownHelp, ConvertTo-SplatExpression | Import-EditorCommand
-```
+This function will import all editor commands in the module and initialize event handlers.
 
 ## Using Editor Commands
 
diff --git a/docs/en-US/EditorServicesCommandSuite.md b/docs/en-US/EditorServicesCommandSuite.md
@@ -46,6 +46,10 @@ The ConvertTo-MarkdownHelp function will replace existing CBH (comment based hel
 The ConvertTo-SplatExpression function transforms a CommandAst to use a splat expression instead
 of inline parameters.
 
+### [Import-CommandSuite](Import-CommandSuite.md)
+
+The Import-CommandSuite function imports the EditorServicesCommandSuite module and initalizes internal processes like setting up event handlers. You can import the module directly without using this function, but it isn't supported and may cause unexpected behavior. This function can be invoked after the module is loaded in case of accidental or auto loading.
+
 ### [Expand-Expression](Expand-Expression.md)
 
 The Expand-Expression function replaces text at a specified range with it's output in PowerShell. As an editor command it will expand output of selected text.
diff --git a/docs/en-US/Import-CommandSuite.md b/docs/en-US/Import-CommandSuite.md
@@ -0,0 +1,49 @@
+---
+external help file: EditorServicesCommandSuite-help.xml
+online version: https://github.com/SeeminglyScience/EditorServicesCommandSuite/blob/master/docs/en-US/Import-CommandSuite.md
+schema: 2.0.0
+---
+
+# Import-CommandSuite
+
+## SYNOPSIS
+
+Initialize the EditorServicesCommandSuite module.
+
+## SYNTAX
+
+```powershell
+Import-CommandSuite
+```
+
+## DESCRIPTION
+
+The Import-CommandSuite function imports the EditorServicesCommandSuite module and initalizes internal processes like setting up event handlers. You can import the module directly without using this function, but it isn't supported and may cause unexpected behavior. This function can be invoked after the module is loaded in case of accidental or auto loading.
+
+## EXAMPLES
+
+### -------------------------- EXAMPLE 1 --------------------------
+
+```powershell
+Import-CommandSuite
+```
+
+Imports EditorServicesCommandSuite functions, editor commands, and event handlers.
+
+## PARAMETERS
+
+## INPUTS
+
+### None
+
+This function does not accept input from the pipeline.
+
+## OUTPUTS
+
+### None
+
+This function does not output to the pipeline.
+
+## NOTES
+
+## RELATED LINKS
diff --git a/module/Classes/MemberExpressionGeneration.ps1 b/module/Classes/MemberExpressionGeneration.ps1
@@ -3,7 +3,8 @@ using namespace System.Reflection
 using namespace System.Text
 
 class MemberExpressionGeneration {
-    static [string] $Indent = '    ';
+    # Work around for type resolution issues.
+    hidden static [string] $Indent = ('TextOps' -as [type])::Indent
 
     [MemberInfo] $Member;
     [psobject] $Target;
diff --git a/module/Classes/TextOps.ps1 b/module/Classes/TextOps.ps1
@@ -5,6 +5,8 @@ enum CaseType {
 }
 
 class TextOps {
+    static [string] $Indent = '    ';
+
     static [string] TransformCase([psobject] $text, [CaseType] $type) {
         $methodName = 'ToUpperInvariant'
         if ($type -eq [CaseType]::Camel) {
diff --git a/module/EditorServicesCommandSuite.psd1 b/module/EditorServicesCommandSuite.psd1
@@ -55,6 +55,7 @@ FunctionsToExport = 'Add-CommandToManifest',
                     'Expand-Expression',
                     'Expand-MemberExpression',
                     'Expand-TypeImplementation',
+                    'Import-CommandSuite',
                     'New-ESCSSettingsFile',
                     'Remove-Semicolon',
                     'Set-HangingIndent',
@@ -83,6 +84,7 @@ FileList = 'EditorServicesCommandSuite.psd1',
            'Public\Expand-Expression.ps1',
            'Public\Expand-MemberExpression.ps1',
            'Public\Expand-TypeImplementation.ps1',
+           'Public\Import-CommandSuite.ps1',
            'Public\New-ESCSSettingsFile.ps1',
            'Public\Remove-Semicolon.ps1',
            'Public\Set-HangingIndent.ps1',
diff --git a/module/Private/GetSettings.ps1 b/module/Private/GetSettings.ps1
@@ -1,30 +1,46 @@
 function GetSettings {
-    [CmdletBinding()]
-    param()
+    [CmdletBinding(DefaultParameterSetName='Auto')]
+    param(
+        [Parameter(ParameterSetName='Auto')]
+        [switch] $Auto,
+
+        [Parameter(ParameterSetName='Reload')]
+        [switch] $ForceReload,
+
+        [Parameter(ParameterSetName='Default')]
+        [switch] $ForceDefault
+    )
     end {
+        function GetSettingsFile {
+            $importLocalizedDataSplat = @{
+                BaseDirectory = $psEditor.Workspace.Path
+                FileName      = 'ESCSSettings.psd1'
+            }
+
+            return Import-LocalizedData @importLocalizedDataSplat
+        }
+
         function GetHashtable {
             if ($script:CSSettings) { return $script:CSSettings }
 
             if (-not [string]::IsNullOrWhiteSpace($psEditor.Workspace.Path)) {
                 $targetPath = Join-Path $psEditor.Workspace.Path -ChildPath 'ESCSSettings.psd1'
 
                 if (Test-Path $targetPath) {
-                    $importLocalizedDataSplat = @{
-                        BaseDirectory = $psEditor.Workspace.Path
-                        FileName      = 'ESCSSettings.psd1'
-                    }
-
-                    $script:CSSettings = Import-LocalizedData @importLocalizedDataSplat
-                    return $script:CSSettings
+                    return GetSettingsFile
                 }
             }
 
-            $script:CSSettings = $script:DEFAULT_SETTINGS
+            return $script:DEFAULT_SETTINGS
+        }
 
-            return $script:CSSettings
+        $settings = switch ($PSCmdlet.ParameterSetName) {
+            Auto { GetHashtable }
+            Reload { GetSettingsFile }
+            Default { $script:DEFAULT_SETTINGS }
         }
 
-        $settings = GetHashtable
+        $script:CSSettings = $settings
 
         # Ensure all settings have a default value even if not present in user supplied file.
         if ($settings.PreValidated) { return $settings }
@@ -34,6 +50,7 @@ function GetSettings {
                 $settings.Add($setting.Key, $setting.Value)
             }
         }
+
         $settings.PreValidated = $true
         return $settings
     }
diff --git a/module/Public/Import-CommandSuite.ps1 b/module/Public/Import-CommandSuite.ps1
@@ -0,0 +1,69 @@
+function Import-CommandSuite {
+    <#
+    .EXTERNALHELP EditorServicesCommandSuite-help.xml
+    #>
+    [CmdletBinding()]
+    param()
+    end {
+        Import-EditorCommand -Module EditorServicesCommandSuite
+        if ([string]::IsNullOrWhiteSpace($psEditor.Workspace.Path)) {
+            return
+        }
+
+        $watcher = [System.IO.FileSystemWatcher]::new(
+            <# path:   #> $psEditor.Workspace.Path,
+            <# filter: #> 'ESCSSettings.psd1')
+
+        $watcher.NotifyFilter = 'LastWrite, CreationTime, FileName'
+        $watcher.EnableRaisingEvents = $true
+        $subscribers = & {
+            $guid = [guid]::NewGuid().ToString('n')
+            $identifier = 'EditorServicesCommandSuite-{0}-{1}'
+            $eventSplat = @{
+                InputObject  = $watcher
+                SupportEvent = $true
+            }
+
+            # Register event subscribers to handle changes to the settings file.
+            $eventSplat.SourceIdentifier = ($identifier -f $guid, 'Changed')
+            $null = Register-ObjectEvent @eventSplat -EventName Changed -Action {
+                $module = Get-Module EditorServicesCommandSuite
+                $null = & $module { GetSettings -ForceReload }
+            }
+
+            $eventSplat.SourceIdentifier = ($identifier -f $guid, 'Created')
+            $null = Register-ObjectEvent @eventSplat -EventName Created -Action {
+                $module = Get-Module EditorServicesCommandSuite
+                $null = & $module { GetSettings -ForceReload }
+            }
+
+            $eventSplat.SourceIdentifier = ($identifier -f $guid, 'Deleted')
+            $null = Register-ObjectEvent @eventSplat -EventName Deleted -Action {
+                $module = Get-Module EditorServicesCommandSuite
+                $null = & $module { GetSettings -ForceDefault }
+            }
+
+            # yield
+            Get-EventSubscriber -SourceIdentifier "EditorServicesCommandSuite-$guid*" -Force
+        }
+
+        $script:SETTINGS_WATCHER = $watcher
+        $script:SETTINGS_SUBSCRIBERS = $subscribers
+
+        # When the module is removed, remove the editor commands it registered and dispose of
+        # event subscribers.
+        $ExecutionContext.SessionState.Module.OnRemove = {
+            $editorCommands = $ExecutionContext.SessionState.Module.ExportedFunctions.Values | Where-Object {
+                $PSItem.ScriptBlock.Ast.Body.ParamBlock.Attributes.TypeName.Name -contains
+                    'EditorCommand'
+            }
+
+            foreach ($command in $editorCommands) {
+                $psEditor.UnregisterCommand($command.Name -replace '-')
+            }
+
+            $script:SETTINGS_SUBSCRIBERS | Unregister-Event -Force
+            $script:SETTINGS_WATCHER.Dispose()
+        }
+    }
+}
diff --git a/module/Public/New-ESCSSettingsFile.ps1 b/module/Public/New-ESCSSettingsFile.ps1
@@ -5,8 +5,9 @@ function New-ESCSSettingsFile {
     .EXTERNALHELP EditorServicesCommandSuite-help.xml
     #>
     [CmdletBinding()]
-    [SuppressMessage('PSAvoidShouldContinueWithoutForce', '',
-                     Justification='ShouldContinue is called from a subroutine without CmdletBinding.')]
+    [SuppressMessage(
+        'PSAvoidShouldContinueWithoutForce', '',
+        Justification='ShouldContinue is called from a subroutine without CmdletBinding.')]
     param(
         [ValidateNotNullOrEmpty()]
         [string]
@@ -41,27 +42,29 @@ function New-ESCSSettingsFile {
         $targetFilePath = Join-Path $Path -ChildPath 'ESCSSettings.psd1'
         HandleFileExists $targetFilePath
 
-        try {
-            $groupDefinition = Get-Content $PSScriptRoot\..\Templates\SettingsFile.stg -Raw -ErrorAction Stop
+        $builder = [System.Text.StringBuilder]::new().Append('@{')
 
-            $templateSplat = @{
-                Group = (New-StringTemplateGroup -Definition $groupDefinition)
-                Name  = 'Base'
-                Parameters = @{
-                    Settings = $script:DEFAULT_SETTINGS.GetEnumerator()
-                    Strings  = [pscustomobject]$Strings
-                }
+        $null = foreach ($setting in $DEFAULT_SETTINGS.GetEnumerator()) {
+            if ($settings.Key -eq 'PreValidated') {
+                continue
             }
 
-            $content = Invoke-StringTemplate @templateSplat
-        } catch {
-            ThrowError -Exception ([InvalidOperationException]::new($Strings.TemplateGroupCompileError)) `
-                       -Id        TemplateGroupCompileError `
-                       -Category  InvalidOperation `
-                       -Target    $groupDefinition
-            return
+            $builder.AppendLine().Append([TextOps]::Indent)
+            $resourceStringName = 'SettingComment{0}' -f $setting.Key
+            if ($Strings.ContainsKey($resourceStringName)) {
+                $builder.
+                    AppendFormat('# {0}', $Strings[$resourceStringName]).
+                    AppendLine().
+                    Append([TextOps]::Indent)
+            }
+
+            $builder.
+                AppendFormat('{0} = ''{1}''', $setting.Key, $setting.Value).
+                AppendLine()
         }
 
+        $content = $builder.AppendLine('}').ToString()
+
         $null = New-Item $targetFilePath -Value $content
         if ($psEditor) {
             try {
diff --git a/module/Templates/MemberExpression.stg b/module/Templates/MemberExpression.stg
diff --git a/module/Templates/SettingsFile.stg b/module/Templates/SettingsFile.stg

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,8 @@ enum CaseType {`
`5`	`5`	`}`
`6`	`6`
`7`	`7`	`class TextOps {`
	`8`	`+ static [string] $Indent = ' ';`
	`9`	`+`
`8`	`10`	`static [string] TransformCase([psobject] $text, [CaseType] $type) {`
`9`	`11`	`$methodName = 'ToUpperInvariant'`
`10`	`12`	`if ($type -eq [CaseType]::Camel) {`