en-us/about_PoshMacros.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
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
~~~