en-us/about_PoshMacros.help.txt
|
PoshMacros is a module to help build useful command line macros in PowerShell
Macro functions are quick commands that tend to start with an _. They can be a: * -Path (to a file or folder) * -Alias * -Command proxies (these can -RemoveParameter(s), have -OptionalParameter(s) and have -DefaultParameter(s)) * -ScriptBlock * -URI (with variables in enclosed in curly brackets or braces, or preceeded by a dollar sign or colon) ### Defining Macros Macros are defined with Add-Macro. Add-Macro is aliased to _+. #### Path Macros You can define path macros. These work like named directories in certain advanced shells: * Running the command pushes into the directory (if already there, it echoes). * Assigning the command returns the [IO.DirectoryInfo] ~~~ # Define a path macro. Running this will pop you into the PoshMacros directory. Assigning it will return the [IO.DirectoryInfo]. Add-Macro -Name PoshMacrosRoot -Path (Get-Module PoshMacros | Split-Path) ~~~ ShowUI\New-Path Macros can also point to files. If the file one of a few data file types, the data will be returned: * .CSV | .TSV (using Import-CSV) * .CLIXML | .CLIX (using Import-Clixml) * .JSON (using ConvertFrom-JSON) * .svg | *.xml (by casting to [xml]) * .psd1 (using Import-LocalizedData) * .ps1 (as an ExternalScript) * .md | .htm[l] | .txt ~~~ Add-Macro -Name PesterManifest -Path (Get-Module Pester | Split-Path | Join-Path -ChildName 'Pester.psd1') ~~~ #### Aliases, Proxy Commands, and Script Blocks You can also define aliases. These act just like any other alias in PowerShell: ~~~ Add-Macro -Name Now -Alias Get-Date _Now ~~~ You can also define a proxy -Command. If you provide a variable name as a default value, it will be expanded when the proxy runs. ~~~ Add-Macro -Name MyProcess -Command Get-Process -DefaultParameter @{Id='$pid'} -RemoveParameter * _MyProcess ~~~ You can also define a macro as an arbitrary -ScriptBlock ~~~ Add-Macro -Name Today -ScriptBlock { [DateTime]::Now.Date } _Today ~~~ #### URI Macros You can define a macro for a -URI with embedded variables. As the example below makes clear, you can include ~~~ Add-Macro -Name GitRepos -Uri 'https://api.github.com/users/:username/repos?page={page}&per_page=$perPage' -DefaultParameter @{ page = 1 perpage = 50 } $StartAutomatingRepos = _GitRepos -UserName StartAutomating ~~~ Like path macros, URI macros work differently when assigned or piped (at least on Windows). On Windows, running a URI macro without assigning or piping will open the URL in a browser. URI macros wrap Invoke-RestMethod, and will carry over all parameters from Invoke-RestMethod except for the URI. Providing any of these parameters will override ### Getting Macros Each Macro is defined in a dynamic module, so you can get macros either by running Get-Macro or Get-Module -Name NameOfMacro ~~~ Get-Macro ~~~ ~~~ Get-Macro -Prefix '_' # Gets all macros with the prefix _ ~~~ ### Exporting Macros You can use Export-Macro to export a macro definition. These can be re-imported at any time, independently of the PoshMacros module. ~~~ Add-Macro -Name MyProcess -Command Get-Process -DefaultParameter @{Id='$pid'} -RemoveParameter * Export-Macro -Name MyProcess ~~~ By default, Export-Macro will declare the dynamic module and metadata associated with a macro. You can also simply export function definitions and aliases with -Inline. ~~~ Add-Macro -Name Now -Alias Get-Date Export-Macro -Name Now -Inline ~~~ ### Importing Macros Macros can be defined within a module by adding a .PoshMacros section of a module's PrivateData, or attaching a .PoshMacros property to a module. To see an example of this in action, use: ~~~ Import-Macro -Name PoshMacros -PassThru ~~~ You can examine the PrivateData of PoshMacros with: ~~~ (_PoshMacrosManifest).PrivateData.PoshMacros ~~~ Any modules that have PoshMacros will be automatically imported when PoshMacros loads. ### Removing Macros Remove-Macro will undeclare macros: ~~~ Add-Macro -Name Now -ScriptBlock { [DateTime]::Now } _Now # it works Remove-Macro -Name _Now _Now # it doesn't ~~~ |