Skip to content

Add documentation for e and u{}. #1407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JuanPablo Jofre (juanpablojofre) merged 1 commit into from
Jun 27, 2017
Merged

Add documentation for e and u{}. #1407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 31 additions & 4 deletions reference/6/About/about_Escape_Characters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,22 +119,49 @@ Escape Sequence | Special Character
`0 | Null
`a | Alert
`b | Backspace
`e | Escape
`f | Form feed
`n | New line
`r | Carriage return
`t | Horizontal tab
`u{x} | Unicode escape sequence for characters with hex value x (up to xxxxxx)
`v | Vertical tab

For example:
This next example uses new line and tab characters to format the string:

```powershell
"12345678123456781`nCol1`tColumn2`tCol3"
"12345678123456781`nCol1`tColumn2`tCol3`u{2195}"
```

```output
# 12345678123456781
12345678123456781

Col1 Column2 Col3↕
```

This next example uses the escape character to specify a virtual
terminal sequence to output text with the foreground color of Orange.
This example requires Windows 10 Anniversary Update or a Linux or
macOS terminal that supports 24-bit color.

Col1 Column2 Col3
```powershell

@mklement0 Michael Klement (mklement0) Jun 27, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps choose a simpler example and one that also works in the stock macOS terminal? Something along the lines of:

$fgColor = 32 # green - see http://en.wikipedia.org/wiki/ANSI_escape_code
"It ain't easy being `e[${fgColor}mgreen`e[0m."

@rkeithhill Keith Hill (rkeithhill) Jun 27, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought I might be overreaching a little on this example. :-) I'll revert back to a simpler (non-24 bit) sequence.

$r,$g,$b = 0xff,0x66,0x00
"`e[38;2;$r;$g;${b}mOrange text`e[0m"
```

```output
Orange text
```

This next example uses a Unicode escape sequence to display the
character '↕'.

```powershell
"`u{2195}"
```

```output
↕
```

For more information, type:
Expand Down
35 changes: 35 additions & 0 deletions reference/6/About/about_Special_Characters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,12 @@ The following special characters are recognized by Windows PowerShell:
`0 Null
`a Alert
`b Backspace
`e Escape
`f Form feed
`n New line
`r Carriage return
`t Horizontal tab
`u{x} Unicode escape sequence
`v Vertical tab
--% Stop parsing

Expand Down Expand Up @@ -66,6 +68,25 @@ The output from this command is as follows:

back out

ESCAPE (`e)
The escape character is most commonly used to specify virtual terminal
sequences to modify the color of text in addition to other text attributes

@mklement0 Michael Klement (mklement0) Jun 27, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps identify them more accurately as ANSI escape codes?

@rkeithhill Keith Hill (rkeithhill) Jun 27, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given this PowerShell property $host.UI.SupportsVirtualTerminal and the MSDN docs, I'm inclined to leave this as-is. However I did start with ANSI escape sequences. :-)

@mklement0 Michael Klement (mklement0) Jun 27, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can't we have both? E.g., "virtual terminal sequences (ANSI escape sequences)"? My only concern is that "virtual terminal sequence" is a lesser-known term that seems to be primarily used in the Windows world - personally, I only recognized it because of the context here.

@rkeithhill Keith Hill (rkeithhill) Jun 27, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that seems like a reasonable compromise. Thanks.

such as bolding and underlining as well as moving the cursor. The PowerShell
host must support virtual terminal sequences. Windows 10 v1511 and higher,
as well as most Linux and macOS terminals support virtual terminal sequences.

The following command outputs Orange text. This requires a host capable
of 24-bit color such as Windows 10 Anniversary Update or higher:

$r,$g,$b = 0xff,0x66,0x00

"`e[38;2;$r;$g;${b}mOrange text`e[0m"

The output from this command is the following text with a foreground color
of Orange:

Orange text

FORM FEED (`f)
The form feed character (`f) is a print instruction that ejects the
current page and continues printing on the next page. This character
Expand Down Expand Up @@ -112,6 +133,20 @@ The output from this command is:

Column1 Column2 Column3

UNICODE CHARACTER (`u{x})
The Unicode escape sequence allows you to specify any Unicode character

@mklement0 Michael Klement (mklement0) Jun 27, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps append "by the hexadecimal representation of its code point"?

@rkeithhill Keith Hill (rkeithhill) Jun 27, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like that. I'll wait a bit, for any other updates, and submit a new PR. Thanks.

including Unicode surrogate characters often used for Emoji e.g. `u{1F44D}.

@mklement0 Michael Klement (mklement0) Jun 27, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps just say "including symbol characters used for emoji, e.g. `u{1F44D}."? (either way, "emoji" should be lowercase) (U+1F44D is not a surrogate character, it is a character that happens to be outside the BMP (a code point > 0xFFFF); its code-point type is Graphic, and its category is [so] (Symbol, other). In fact, there is no such thing as a surrogate character, only surrogate code points that in pairs form an assigned character.

@rkeithhill Keith Hill (rkeithhill) Jun 27, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check on lower case emoji. RE surrogate character issue, that's probably too much detail. How about something like this?

specify any Unicode character including those above the Basic Multilingual Plane (> 0xFFFF) which includes emoji characters e.g. ...

@mklement0 Michael Klement (mklement0) Jun 27, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keith Hill (@rkeithhill): Sounds great.

The Unicode escape sequence requires at least one hex digit and supports
up to six hex digits. The maximum hex value is 0x10FFFF.

@mklement0 Michael Klement (mklement0) Jun 27, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps say "The maximum value is `u{10FFFF}.", so as to avoid a potential distraction by 0x?


The following command outputs the character '↕':

"`u{2195}"

The output from this command is:

↕

VERTICAL TAB (`v)
The horizontal tab character (`t) advances to the next vertical tab stop
and writes all subsequent output beginning at that point. This character
Expand Down