https://github.com/startautomating/poshmacros
Sleek and Simple PowerShell Macros
https://github.com/startautomating/poshmacros
Last synced: 10 months ago
JSON representation
Sleek and Simple PowerShell Macros
- Host: GitHub
- URL: https://github.com/startautomating/poshmacros
- Owner: StartAutomating
- License: mit
- Created: 2020-02-09T22:28:59.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2020-02-09T23:03:27.000Z (almost 6 years ago)
- Last Synced: 2025-03-24T08:46:08.011Z (10 months ago)
- Language: PowerShell
- Size: 17.6 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
PoshMacros [0.1]
================
Sleek and Simple PowerShell Macros
----------------
### Commands
---------------
| Verb|Noun |
|-----:|:-----|
| Add|-Macro|
|Export|-Macro|
| Get|-Macro|
|Import|-Macro|
|Remove|-Macro|
---------------
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
~~~