diff --git a/Plaster/Plaster.psm1 b/Plaster/Plaster.psm1 index 2dd3e8c..8095153 100644 --- a/Plaster/Plaster.psm1 +++ b/Plaster/Plaster.psm1 @@ -171,5 +171,25 @@ $MyInvocation.MyCommand.ScriptBlock.Module.OnRemove = { Remove-Variable -Name 'ParameterDefaultValueStoreRootPath' -Scope Script -ErrorAction SilentlyContinue } +# Register argument completers +Register-ArgumentCompleter -CommandName Invoke-Plaster -ParameterName TemplateName -ScriptBlock { + param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) + + # Trim single, or double quotes from the start/end of the word to complete. + if ($wordToComplete -match '^[''"]') { + $wordToComplete = $wordToComplete.Trim($Matches.Values[0]) + } + + # Get all unique names starting with the characters provided, if any. + Get-PlasterTemplate -Name "$wordToComplete*" | Select-Object Name -Unique | ForEach-Object { + # Wrap the completion in single quotes if it contains any whitespace. + if ($_.Name -match '\s') { + "'{0}'" -f $_.Name + } else { + $_.Name + } + } +} + # Module initialization complete Write-PlasterLog -Level Information -Message "Plaster v$PlasterVersion module loaded successfully (PowerShell $($PSVersionTable.PSVersion))" diff --git a/Plaster/Public/Invoke-Plaster.ps1 b/Plaster/Public/Invoke-Plaster.ps1 index a78b999..40779bf 100644 --- a/Plaster/Public/Invoke-Plaster.ps1 +++ b/Plaster/Public/Invoke-Plaster.ps1 @@ -27,6 +27,11 @@ function Invoke-Plaster { [string] $TemplateDefinition, + [Parameter(Position = 0, Mandatory = $true, ParameterSetName = 'TemplateName')] + [ValidateNotNullOrEmpty()] + [string] + $TemplateName, + [Parameter(Position = 1, Mandatory = $true)] [ValidateNotNullOrEmpty()] [string] @@ -70,6 +75,10 @@ function Invoke-Plaster { EvaluateAttributeValue since we are only grabbing the parameter's value which is static.#> + if ($PSCmdlet.ParameterSetName -eq 'TemplateName') { + $TemplatePath = (Get-PlasterTemplate -Name $TemplateName).TemplatePath + } + $templateAbsolutePath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($TemplatePath) # Load manifest file using culture lookup - try both JSON and XML formats @@ -194,7 +203,10 @@ function Invoke-Plaster { #endregion Script Scope Variables # Determine template source and type - if ($PSCmdlet.ParameterSetName -eq 'TemplatePath') { + if ($PSCmdlet.ParameterSetName -eq 'TemplateName') { + $TemplatePath = (Get-PlasterTemplate -Name $TemplateName).TemplatePath + } + if ($PSCmdlet.ParameterSetName -in @('TemplatePath', 'TemplateName')) { $templateAbsolutePath = $PSCmdlet.GetUnresolvedProviderPathFromPSPath($TemplatePath) if (!(Test-Path -LiteralPath $templateAbsolutePath -PathType Container)) { throw ($LocalizedData.ErrorTemplatePathIsInvalid_F1 -f $templateAbsolutePath) diff --git a/docs/en-US/Invoke-Plaster.md b/docs/en-US/Invoke-Plaster.md index 463ab88..d4d7416 100644 --- a/docs/en-US/Invoke-Plaster.md +++ b/docs/en-US/Invoke-Plaster.md @@ -1,215 +1,238 @@ ---- -external help file: Plaster-help.xml -Module Name: Plaster -online version: https://github.com/PowerShell/Plaster/blob/master/docs/en-US/Invoke-Plaster.md -schema: 2.0.0 ---- - -# Invoke-Plaster - -## SYNOPSIS -Invokes the specified Plaster template which will scaffold out a file or a set of files and directories. - -## SYNTAX - -### TemplatePath (Default) -``` -Invoke-Plaster [-TemplatePath] [-DestinationPath] [-Force] [-NoLogo] [-PassThru] - [-ProgressAction ] [-WhatIf] [-Confirm] [] -``` - -### TemplateDefinition -``` -Invoke-Plaster [-TemplateDefinition] [-DestinationPath] [-Force] [-NoLogo] [-PassThru] - [-ProgressAction ] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -Invokes the specified Plaster template which will scaffold out a file or a -set of files and directories. - -## EXAMPLES - -### EXAMPLE 1 -``` -Invoke-Plaster -TemplatePath . -Destination ~\GitHub\NewModule -``` - -This will invoke the Plaster template in the current directory. -The template will generate any files and -directories in the ~\GitHub\NewModule directory. - -### EXAMPLE 2 -``` -Invoke-Plaster -TemplatePath . -Destination ~\GitHub\NewModule -ModuleName Foo -Version 1.0.0 -``` - -This will invoke the Plaster template in the current directory using dynamic -parameters ModuleName and Version extracted from the parameters section of -the manifest file. The template will generate any files and directories in -the ~\GitHub\NewModule directory. - -Note: The parameters -ModuleName and -Version are dynamically added from the plaster manifest file in the current directory. If you run this command it may fail if the manifest file you are testing with does not contain these parameters. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -DestinationPath -Specifies the path to directory in which the template will use as a root directory when generating files. -If the directory does not exist, it will be created. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Force -Specify Force to override user prompts for conflicting handling. -This will override the confirmation -prompt and allow the template to overwrite existing files. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -NoLogo -Suppresses the display of the Plaster logo. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PassThru -Returns an InvokePlasterInfo object with the following fields: - -* TemplatePath -* DestinationPath -* Success -* CreatedFiles -* UpdatedFiles -* MissingModules - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -TemplateDefinition -{{ Fill TemplateDefinition Description }} - -```yaml -Type: String -Parameter Sets: TemplateDefinition -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -TemplatePath -Specifies the path to the template directory. - -```yaml -Type: String -Parameter Sets: TemplatePath -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction -{{ Fill ProgressAction Description }} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[New-PlasterManifest](https://github.com/PowerShell/Plaster/blob/master/docs/en-US/New-PlasterManifest.md) -[Test-PlasterManifest](https://github.com/PowerShell/Plaster/blob/master/docs/en-US/Test-PlasterManifest.md) - +--- +external help file: Plaster-help.xml +Module Name: Plaster +online version: https://github.com/PowerShell/Plaster/blob/master/docs/en-US/Invoke-Plaster.md +schema: 2.0.0 +--- + +# Invoke-Plaster + +## SYNOPSIS +Invokes the specified Plaster template which will scaffold out a file or a set of files and directories. + +## SYNTAX + +### TemplatePath (Default) +``` +Invoke-Plaster [-TemplatePath] [-DestinationPath] [-Force] [-NoLogo] [-PassThru] + [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +### TemplateDefinition +``` +Invoke-Plaster [-TemplateDefinition] [-DestinationPath] [-Force] [-NoLogo] [-PassThru] + [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +### TemplateName +``` +Invoke-Plaster [-TemplateName] [-DestinationPath] [-Force] [-NoLogo] [-PassThru] + [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +Invokes the specified Plaster template which will scaffold out a file or a +set of files and directories. + +## EXAMPLES + +### EXAMPLE 1 +``` +Invoke-Plaster -TemplatePath . -Destination ~\GitHub\NewModule +``` + +This will invoke the Plaster template in the current directory. +The template will generate any files and +directories in the ~\GitHub\NewModule directory. + +### EXAMPLE 2 +``` +Invoke-Plaster -TemplatePath . -Destination ~\GitHub\NewModule -ModuleName Foo -Version 1.0.0 +``` + +This will invoke the Plaster template in the current directory using dynamic +parameters ModuleName and Version extracted from the parameters section of +the manifest file. The template will generate any files and directories in +the ~\GitHub\NewModule directory. + +Note: The parameters -ModuleName and -Version are dynamically added from the plaster manifest file in the current directory. If you run this command it may fail if the manifest file you are testing with does not contain these parameters. + +## PARAMETERS + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DestinationPath +Specifies the path to directory in which the template will use as a root directory when generating files. +If the directory does not exist, it will be created. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Specify Force to override user prompts for conflicting handling. +This will override the confirmation +prompt and allow the template to overwrite existing files. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoLogo +Suppresses the display of the Plaster logo. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru +Returns an InvokePlasterInfo object with the following fields: + +* TemplatePath +* DestinationPath +* Success +* CreatedFiles +* UpdatedFiles +* MissingModules + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TemplateDefinition +{{ Fill TemplateDefinition Description }} + +```yaml +Type: String +Parameter Sets: TemplateDefinition +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TemplateName + +Specifies the name of an available plaster template. Use Get-PlasterTemplate to +list the available templates. + +```yaml +Type: String +Parameter Sets: TemplateName +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TemplatePath +Specifies the path to the template directory. + +```yaml +Type: String +Parameter Sets: TemplatePath +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[New-PlasterManifest](https://github.com/PowerShell/Plaster/blob/master/docs/en-US/New-PlasterManifest.md) +[Test-PlasterManifest](https://github.com/PowerShell/Plaster/blob/master/docs/en-US/Test-PlasterManifest.md) +