From 043d6ebfe865dc5140104f6ded7368402c3f9d9a Mon Sep 17 00:00:00 2001 From: MartinGC94 Date: Tue, 24 Jan 2023 00:03:38 +0100 Subject: [PATCH 1/3] Add Update here-string syntax RFC --- .../RFCNNNN-Update here-string syntax.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 Draft-Accepted/RFCNNNN-Update here-string syntax.md diff --git a/Draft-Accepted/RFCNNNN-Update here-string syntax.md b/Draft-Accepted/RFCNNNN-Update here-string syntax.md new file mode 100644 index 00000000..994d92b4 --- /dev/null +++ b/Draft-Accepted/RFCNNNN-Update here-string syntax.md @@ -0,0 +1,97 @@ +--- +RFC: +Author: MartinGC94 +Status: Draft +SupercededBy: +Version: 1.0 +Area: Language +Comments Due: 23-02-2023 +Plan to implement: Yes +--- + +# Update here-string syntax + +The here-string syntax should be updated to support the following 3 requests: +1. Allow single line here-strings like `Write-Host @'It's nice being able to use contractions'@` so the user doesn't have to worry about escaping quote characters. +2. Allow a variable number of delimiter characters like `Write-Host @@'@'Nested here string'@'@@` so users can create nested here-strings. +3. Allow indentation of the end delimiter of here-strings so the indentation level stays consistent like in this example: + +``` +function MyFunction +{ + Write-Host @@' + This here-string spans multiple lines + Isn't it cool? + '@@ +} +``` + +See also this related PR: https://github.com/PowerShell/PowerShell/pull/17483 and these related issues: https://github.com/PowerShell/PowerShell/issues/2337 https://github.com/PowerShell/PowerShell/issues/13204 + + +## Motivation + + As a user, + I can write/paste strings with quote characters without having to escape them, + which makes the shell easier to use. + + As a developer, + I can generate strings meant for PowerShell consumption (tab completion, code snippets, etc.) without having to escape special characters. + + As a developer, + I can move code with here-strings into a function and indent it without manually removing the indentation for the string terminator. + +## User Experience + +Example of user experience with example code/script. +Include example of input and output. + +```powershell +@'It's a beautiful day'@ +``` + +```output +It's a beautiful day +``` + +```powershell +@'It's a +beautiful day +'@ +``` + +```output +Parser error +``` + +```powershell +@@' + ^Line starts at '^' + This line has 4 leading whitespaces + '@@ +``` + +```output +^Line starts at '^' + This line has 4 leading whitespaces +``` + +## Specification +Here-strings start with a variable amount of `@` characters, followed by either a double or single quote character to signify if it's expandable or not. +Single line here-strings start immediately after the chosen quote character. +Multi line here-strings start on the line that follows the starting sequence. Whitespace characters on the same line as the starting sequence are ignored, non-whitespace characters produce a syntax error. + +Single line here-strings end when a matching quote character is found if it's also followed by the same amount of `@` characters that the string started with. +Multi line here-strings follow the same ending rules as single line here-strings, except they also require the line with the string terminator characters to be empty, or only consist of whitespace. +For backwards compatibility, multi line here-strings that start with a single `@` character cannot have whitespace before the string terminator characters. + +Multi line here-strings that start with 2 or more `@` characters can be indented, when this is done each line will be trimmed for leading whitespaces. The amount of whitespaces removed depends on the lowest indentation level used in the here-string. For example, if line 1 is indented by 5 spaces and line 2 is indented by 4 spaces then the parsed string will include one whitespace on line 1 and no whitespaces on line 2. + +## Alternate Proposals and Considerations +Instead of using multiple `@` it could use multiple quote characters instead. There are 3 reasons why I think `@` is the better choice: +1. It's easier to tell at a glance how many characters there are with @@@@@' VS @''''' especially when you also consider double quotes and all the different single/double quote variants that exist. +2. If you decide to swap between a single quote and double quote here-string it's easier to just change 1 character in each end instead of multiple characters in each end. +3. In the case of single line strings it allows the string to start with any character. It quotes were used you wouldn't be able to start the string with a quote character because it would be counted as part of the "header" section of the here-string. + +The special backwards compatibility behavior when using a single `@` could be removed to make it easier for new users to learn the syntax and to simplify the code. +Unfortunately it was declined the last time a PR was made: https://github.com/PowerShell/PowerShell/issues/2337#issuecomment-452380310 \ No newline at end of file From 0905e316778ce4a473ec41e4742aa15c1f7b27b9 Mon Sep 17 00:00:00 2001 From: MartinGC94 <42123497+MartinGC94@users.noreply.github.com> Date: Sat, 12 Aug 2023 01:37:03 +0200 Subject: [PATCH 2/3] Update RFCNNNN-Update here-string syntax.md --- .../RFCNNNN-Update here-string syntax.md | 58 ++++++++----------- 1 file changed, 25 insertions(+), 33 deletions(-) diff --git a/Draft-Accepted/RFCNNNN-Update here-string syntax.md b/Draft-Accepted/RFCNNNN-Update here-string syntax.md index 994d92b4..cbd43ae6 100644 --- a/Draft-Accepted/RFCNNNN-Update here-string syntax.md +++ b/Draft-Accepted/RFCNNNN-Update here-string syntax.md @@ -11,10 +11,9 @@ Plan to implement: Yes # Update here-string syntax -The here-string syntax should be updated to support the following 3 requests: -1. Allow single line here-strings like `Write-Host @'It's nice being able to use contractions'@` so the user doesn't have to worry about escaping quote characters. -2. Allow a variable number of delimiter characters like `Write-Host @@'@'Nested here string'@'@@` so users can create nested here-strings. -3. Allow indentation of the end delimiter of here-strings so the indentation level stays consistent like in this example: +The here-string syntax should be updated to support the following 2 requests: +1. Allow a variable number of delimiter characters like `Write-Host @''@'Nested here string'@'@'` so users can create nested here-strings. +2. Allow indentation of the end delimiter of here-strings so the indentation level stays consistent like in this example: ``` function MyFunction @@ -26,18 +25,11 @@ function MyFunction } ``` -See also this related PR: https://github.com/PowerShell/PowerShell/pull/17483 and these related issues: https://github.com/PowerShell/PowerShell/issues/2337 https://github.com/PowerShell/PowerShell/issues/13204 +See also this related PR: https://github.com/PowerShell/PowerShell/pull/17483 and these related issues: https://github.com/PowerShell/PowerShell/issues/2337 ## Motivation - As a user, - I can write/paste strings with quote characters without having to escape them, - which makes the shell easier to use. - - As a developer, - I can generate strings meant for PowerShell consumption (tab completion, code snippets, etc.) without having to escape special characters. - As a developer, I can move code with here-strings into a function and indent it without manually removing the indentation for the string terminator. @@ -46,14 +38,6 @@ See also this related PR: https://github.com/PowerShell/PowerShell/pull/17483 an Example of user experience with example code/script. Include example of input and output. -```powershell -@'It's a beautiful day'@ -``` - -```output -It's a beautiful day -``` - ```powershell @'It's a beautiful day @@ -61,37 +45,45 @@ beautiful day ``` ```output -Parser error +Parser error due to the characters after the header. ``` ```powershell @@' - ^Line starts at '^' + ^This line starts at '^' This line has 4 leading whitespaces '@@ ``` ```output -^Line starts at '^' +^This line starts at '^' This line has 4 leading whitespaces ``` ## Specification -Here-strings start with a variable amount of `@` characters, followed by either a double or single quote character to signify if it's expandable or not. -Single line here-strings start immediately after the chosen quote character. -Multi line here-strings start on the line that follows the starting sequence. Whitespace characters on the same line as the starting sequence are ignored, non-whitespace characters produce a syntax error. +Here-strings start with a "header" that consists of an `@` symbol, followed by a variable amount of single/double quote characters. +White space characters are allowed after the header, but they are not included in the actual content. Any non-whitespace characters after the header will cause a parser error. +Double quoted strings are expandable, while single quoted strings are literal. +Expansion/escape rules are the same as the standard double/single quoted strings, except quote characters don't need to be escaped. -Single line here-strings end when a matching quote character is found if it's also followed by the same amount of `@` characters that the string started with. -Multi line here-strings follow the same ending rules as single line here-strings, except they also require the line with the string terminator characters to be empty, or only consist of whitespace. -For backwards compatibility, multi line here-strings that start with a single `@` character cannot have whitespace before the string terminator characters. -Multi line here-strings that start with 2 or more `@` characters can be indented, when this is done each line will be trimmed for leading whitespaces. The amount of whitespaces removed depends on the lowest indentation level used in the here-string. For example, if line 1 is indented by 5 spaces and line 2 is indented by 4 spaces then the parsed string will include one whitespace on line 1 and no whitespaces on line 2. +Here-strings end with a "footer" line that consists of a matching amount (and kind) of single/double quote characters as the header, followed by an `@` symbol. +If there is more than one single/double quote character in the header, the footer can be indented with whitespaces (this requirement exists to preserve backwards compatibility with the old here-string syntax which did not allow any characters before the footer). +Any non-whitespace characters before the footer will cause a parser error. + +The content of a here-string consists of everything between the header and footer lines. +If the footer is indented, then the amount of whitespaces it's indented with determines how many whitespaces to trim from the beginning of each line in the here-string. +Lines with less whitespace indentation than the footer will cause a parser error unless they are empty or only consists of whitespace characters. +Lines that are empty or only consists of whitespaces that have less than or equal to the amount of whitespaces as the footer are trimmed so they only consist of the line break character(s). +If the whitespace indentation of a line is greater than the footer then the additional whitespaces will be included as is in the content. ## Alternate Proposals and Considerations -Instead of using multiple `@` it could use multiple quote characters instead. There are 3 reasons why I think `@` is the better choice: +Instead of using multiple quote characters it could use multiple `@` characters instead. `@` has the following 3 advantages: 1. It's easier to tell at a glance how many characters there are with @@@@@' VS @''''' especially when you also consider double quotes and all the different single/double quote variants that exist. 2. If you decide to swap between a single quote and double quote here-string it's easier to just change 1 character in each end instead of multiple characters in each end. -3. In the case of single line strings it allows the string to start with any character. It quotes were used you wouldn't be able to start the string with a quote character because it would be counted as part of the "header" section of the here-string. +3. If single line here-strings are ever added it will allow the string to start with any character. Quotes will not allow you to start the string with a quote character because it would be counted as part of the "header" section of the here-string. + +Despite these advantages, the use of multiple quote characters were choosen due to familiarity with the raw string literals in C#. The special backwards compatibility behavior when using a single `@` could be removed to make it easier for new users to learn the syntax and to simplify the code. -Unfortunately it was declined the last time a PR was made: https://github.com/PowerShell/PowerShell/issues/2337#issuecomment-452380310 \ No newline at end of file +However it was declined the last time a PR was made: https://github.com/PowerShell/PowerShell/issues/2337#issuecomment-452380310 From 851d4f44919a6345b501601a15f14420bdab7c73 Mon Sep 17 00:00:00 2001 From: MartinGC94 <42123497+MartinGC94@users.noreply.github.com> Date: Sat, 12 Aug 2023 01:41:00 +0200 Subject: [PATCH 3/3] Update RFCNNNN-Update here-string syntax.md --- Draft-Accepted/RFCNNNN-Update here-string syntax.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Draft-Accepted/RFCNNNN-Update here-string syntax.md b/Draft-Accepted/RFCNNNN-Update here-string syntax.md index cbd43ae6..b8e968bf 100644 --- a/Draft-Accepted/RFCNNNN-Update here-string syntax.md +++ b/Draft-Accepted/RFCNNNN-Update here-string syntax.md @@ -87,3 +87,5 @@ Despite these advantages, the use of multiple quote characters were choosen due The special backwards compatibility behavior when using a single `@` could be removed to make it easier for new users to learn the syntax and to simplify the code. However it was declined the last time a PR was made: https://github.com/PowerShell/PowerShell/issues/2337#issuecomment-452380310 + +Another update for the here-string syntax could be to allow it for single lines, like: `Write-Host @'Hello'@` this would enable users to type out strings without having to think about escaping quote characters. It would also enable tab completion providers to simplify the escaping logic for completion values. This can be added at a later point.