Skip to content

Commit 884d370

Browse files
JaykulJaykul
committed
Document New-Hyperlink
1 parent 3c2a986 commit 884d370

File tree

5 files changed

+198
-12
lines changed

5 files changed

+198
-12
lines changed

‎Docs/New-Hyperlink.md

+179
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
external help file: Pansies-help.xml
3+
online version:
4+
schema: 2.0.0
5+
---
6+
7+
# New-Hyperlink
8+
9+
## SYNOPSIS
10+
Create a hyperlink with the specified Uri, and optionally using different text, background and foreground colors
11+
12+
## SYNTAX
13+
14+
```
15+
New-Hyperlink [-Uri] <String> [[-Object] <Object>] [-Separator <Object>] [-BackgroundColor <RgbColor>] [-ForegroundColor <RgbColor>] [-LeaveColor] [-IgnoreEntities] [-Passthru]
16+
```
17+
18+
## DESCRIPTION
19+
Create a hyperlink with the specified Uri, using ANSI Virtual Terminal escape sequences.
20+
As with New-Text, there's full support for setting background and foreground colors, and rendering HTML-style entities.
21+
22+
With -Passthru, returns the Text object, but normally outputs the text string with the Uri hyperlink embedded.
23+
24+
## EXAMPLES
25+
26+
### Example 1
27+
```
28+
PS C:\> New-Hyperlink https://PoshCode.org -ForegroundColor Green
29+
30+
`e[92m`e]8;;https://PoshCode.org`ahttps://PoshCode.org`e]8;;`a`e[39m
31+
```
32+
33+
Generates a hyperlink to https://PoshCode.org with the text https://PoshCode.org and a green foreground color.
34+
35+
This use, without text (the `-Object` parameter) and with a highlight color, is the most compatible use, because if the terminal doesn't support links, at least the URL will be visible, and highlighted in color
36+
37+
### Example 2
38+
```
39+
PS C:\> "Please visit $(New-Hyperlink https://PoshCode.org PoshCode)"
40+
41+
Please visit `e]8;;https://PoshCode.org`aPoshCode`e]8;;`a
42+
```
43+
44+
Generates a hyperlink to https://PoshCode.org with the text "PoshCode". You should be careful of this syntax, where you don't include the full URL in the display, because terminals which don't support hyperlinks (like the default Windows console) will not display the Url, nor any indication that it should be a link.
45+
46+
## PARAMETERS
47+
48+
### -Uri
49+
Specifies the Uri to link to.
50+
51+
```yaml
52+
Type: String
53+
Parameter Sets: (All)
54+
Aliases:
55+
56+
Required: True
57+
Position: 0
58+
Default value: None
59+
Accept pipeline input: True (ByPropertyName, ByValue)
60+
Accept wildcard characters: False
61+
```
62+
63+
### -BackgroundColor
64+
The background color. You may specify it as CSS hex "#RRGGBB" (or just "RRGGBB") or as an XTerm index "xt123" (or just "123") or as a ConsoleColor like "Red" or "DarkRed"...
65+
66+
```yaml
67+
Type: RgbColor
68+
Parameter Sets: (All)
69+
Aliases: Bg
70+
71+
Required: False
72+
Position: Named
73+
Default value: None
74+
Accept pipeline input: False
75+
Accept wildcard characters: False
76+
```
77+
78+
### -ForegroundColor
79+
The foreground color. You may specify it as CSS hex "#RRGGBB" (or just "RRGGBB") or as an XTerm index "xt123" (or just "123") or as a ConsoleColor like "Red" or "DarkRed"...
80+
81+
```yaml
82+
Type: RgbColor
83+
Parameter Sets: (All)
84+
Aliases: Fg
85+
86+
Required: False
87+
Position: Named
88+
Default value: None
89+
Accept pipeline input: False
90+
Accept wildcard characters: False
91+
```
92+
93+
### -IgnoreEntities
94+
If set, don't render the HTML Entities to characters (i.e. leave "&hearts;" as "&hearts;" instead of as "♥")
95+
96+
```yaml
97+
Type: SwitchParameter
98+
Parameter Sets: (All)
99+
Aliases:
100+
101+
Required: False
102+
Position: Named
103+
Default value: None
104+
Accept pipeline input: False
105+
Accept wildcard characters: False
106+
```
107+
108+
### -LeaveColor
109+
If set, don't clear the colors at the end of the output.
110+
111+
```yaml
112+
Type: SwitchParameter
113+
Parameter Sets: (All)
114+
Aliases:
115+
116+
Required: False
117+
Position: Named
118+
Default value: None
119+
Accept pipeline input: False
120+
Accept wildcard characters: False
121+
```
122+
123+
### -Object
124+
Specifies objects to display as the text of the link.
125+
126+
```yaml
127+
Type: Object
128+
Parameter Sets: (All)
129+
Aliases:
130+
131+
Required: True
132+
Position: 0
133+
Default value: None
134+
Accept pipeline input: True (ByValue, FromRemainingArguments)
135+
Accept wildcard characters: False
136+
```
137+
138+
### -Separator
139+
Specifies a separator string to output between objects displayed on the console.
140+
141+
```yaml
142+
Type: Object
143+
Parameter Sets: (All)
144+
Aliases:
145+
146+
Required: False
147+
Position: Named
148+
Default value: None
149+
Accept pipeline input: False
150+
Accept wildcard characters: False
151+
```
152+
153+
### -Passthru
154+
If set, outputs a Text object, rather than simple string
155+
156+
```yaml
157+
Type: SwitchParameter
158+
Parameter Sets: (All)
159+
Aliases:
160+
161+
Required: False
162+
Position: Named
163+
Default value: None
164+
Accept pipeline input: False
165+
Accept wildcard characters: False
166+
```
167+
168+
## INPUTS
169+
170+
### System.Object
171+
172+
## OUTPUTS
173+
174+
### System.Object
175+
176+
## NOTES
177+
178+
## RELATED LINKS
179+

‎Docs/New-Text.md

+9-9
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
external help file: Pansies-help.xml
3-
online version:
3+
online version:
44
schema: 2.0.0
55
---
66

@@ -16,8 +16,8 @@ New-Text [-Object] <Object> [-BackgroundColor <RgbColor>] [-Separator <Object>]
1616
```
1717

1818
## DESCRIPTION
19-
Create a Text object with specified background and foreground colors, and rendering HTML-style entities.
20-
When this object is rendered to the host with .ToString(), it inserts ANSI Virtual Terminal escape sequences for the specified colors,
19+
Create a Text object with specified background and foreground colors, and rendering HTML-style entities.
20+
When this object is rendered to the host with .ToString(), it inserts ANSI Virtual Terminal escape sequences for the specified colors,
2121
and by default, outputs escape sequences to clear those colors after the text.
2222

2323
## EXAMPLES
@@ -81,7 +81,7 @@ If set, don't render the HTML Entities to characters (i.e. leave "&hearts;" as "
8181
```yaml
8282
Type: SwitchParameter
8383
Parameter Sets: (All)
84-
Aliases:
84+
Aliases:
8585

8686
Required: False
8787
Position: Named
@@ -96,7 +96,7 @@ If set, don't clear the colors at the end of the output.
9696
```yaml
9797
Type: SwitchParameter
9898
Parameter Sets: (All)
99-
Aliases:
99+
Aliases:
100100

101101
Required: False
102102
Position: Named
@@ -106,17 +106,17 @@ Accept wildcard characters: False
106106
```
107107
108108
### -Object
109-
Specifies objects to display in the console.
109+
Specifies objects to display in the host.
110110
111111
```yaml
112112
Type: Object
113113
Parameter Sets: (All)
114-
Aliases:
114+
Aliases:
115115

116116
Required: True
117117
Position: 0
118118
Default value: None
119-
Accept pipeline input: True (ByPropertyName, ByValue)
119+
Accept pipeline input: True (ByPropertyName, ByValue, FromRemainingArguments)
120120
Accept wildcard characters: False
121121
```
122122
@@ -126,7 +126,7 @@ Specifies a separator string to the output between objects displayed on the cons
126126
```yaml
127127
Type: Object
128128
Parameter Sets: (All)
129-
Aliases:
129+
Aliases:
130130

131131
Required: False
132132
Position: Named

‎README.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -47,12 +47,13 @@ Note: Because I'm including p2f as a submodule, you may need to update it with:
4747
git submodule update --init -recursive
4848
```
4949

50-
### Currently Pansies provides four commands:
50+
### Currently Pansies provides five commands:
5151

5252
Cmdlet | Description
5353
------ | -----------
5454
New-Text | Creates a `Text` object. Provides parameters for `BackgroundColor` and `ForegroundColor` properties, that renders in console
55-
Write-Host | Writes to host just like Write-Host, but with full RGBColor support
55+
New-Hyperlink | Takes a Uri and optional text and writes [a hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda#file-hyperlinks_in_terminal_emulators-md) supported by most terminals
56+
Write-Host | Writes to host just like Write-Host, but with full RGBColor support and a -PersistentColor option
5657
Get-Gradient | Get a range of colors between two colors
5758
Get-Complement | Gets the Hue complement of a color
5859

‎Source/Assembly/Commands/NewHyperlinkCommand.cs

+2-1
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ public class NewHyperlinkCommand : Cmdlet
1919
/// </summary>
2020
/// <value>A string</value>
2121
[Parameter(Mandatory = false, ValueFromPipelineByPropertyName = true, Position = 1)]
22+
[Alias("Text")]
2223
public object Object { get; set; }
2324

2425
/// <summary>
@@ -69,7 +70,7 @@ protected override void ProcessRecord()
6970
Separator = Separator,
7071
Object = Object,
7172
Clear = !LeaveColor,
72-
Entities = !IgnoreEntities,
73+
Entities = !IgnoreEntities
7374
};
7475

7576
if (Passthru) {

‎Source/Pansies.psd1

+5
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,11 @@ PrivateData = @{
7676

7777
# ReleaseNotes of this module
7878
ReleaseNotes = '
79+
2.1.0: Hyperlinks
80+
- Added New-Hyperlink (alias URL) now that Windows Terminal supports them.
81+
Note that Windows Console (conhost) _does not_ support hyperlinks, and any terminal which does not will ignore them.
82+
For compatibility, always use the Uri as the text (i.e. do not pass the object parameter).
83+
- Added -PersistentColor option to reset the Foreground and Background for each object output when outputting arrays.
7984
2.0.0: Breaking change for the library:
8085
- Merge the "Colormine" namespace into PoshCode.Pansies
8186
Originally, this was a 3rd party MIT licensed library by @THEJoeZack.

0 commit comments

Comments
 (0)