From 63c2e0f1e59076945bc9ef8f2043c639439bc70b Mon Sep 17 00:00:00 2001 From: Christopher Silva Date: Tue, 15 Feb 2022 13:16:36 -0600 Subject: [PATCH 1/9] add rfc for adding ansi escape codes --- text/0000-add-ansi-escape-codes.md | 59 ++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 text/0000-add-ansi-escape-codes.md diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md new file mode 100644 index 00000000..3c121d4a --- /dev/null +++ b/text/0000-add-ansi-escape-codes.md @@ -0,0 +1,59 @@ +- Feature Name: add_ansi_escape_codes +- Start Date: 2022-02-14 +- RFC PR: (leave this empty) +- Pony Issue: (leave this empty) + +# Summary + +This RFC proposes the addition of more escape code functions to the ANSI primitive of the term package and the consolodation of the thirty-two existing color functions into four functions. + +# Motivation + +The purpose of these additional methods is to cover more of the standard ANSI escape codes within the stdlib. + +# Detailed design + +- Add escape codes for 3-bit, 4-bit, 8-bit, and 24-bit colors for the foreground and background. +The naming scheme of the color functions would be `{fg,bg}_{3,4,8,24}bit`. +The 3-bit, 4-bit, and 8-bit versions would take a U8 specifying the color. +The 24-bit versions would take three U8s specifying the r, g, and b values. +- Remove the thirty-two named color functions in favor of the 3-bit and 4-bit functions. +- Add escape codes for enter and leave alternate screen buffer. +- Add escape code for the bell alert. +- Change `clear` and `erase` functions to take a U8 specifying what part of the screen/line to clear. +The default for the escape codes if a value isn't given is zero. +The action these functions currently take is three for `clear` and one for `erase`. +I would like to have the default value in these functions be zero. +- Add escape codes for scroll up/down. +- Add escape codes for next/previous line. +- Add escape code for cursor horizontal position (moves the cursor to column n in the current line). + +If a value passed to any of the functions is invalid, such as 200 being passed to `fg_3bit`, an empty string would be returned. + +# How We Teach This + +The added functions would be documented as the existing functions on the `ANSI` primitive are and an example of usage would be added to `ANSI`. + +# How We Test This + +I could not find existing testing for the `ANSI` primitive. +If there are existing tests for these functions, additional tests in the same format would be added to ensure that the new functions return the correct escape codes. +Most of these functions are just directly returning a string of the escape code without any parameters so they're pretty straightforward. + +# Drawbacks + +The removal of the existing color functions and the change to the `clear` and `erase` functions (if the default of zero is used) are breaking changes. + +# Alternatives + +## Alternative to the rfc as a whole +These escape codes can simply be printed independently of whatever is supported by functions on `ANSI`. +Having them available on `ANSI` simply makes it so that users do not need to look the codes up themselves. + +## Alternative to the breaking changes +The existing color functions could remain and the 3-bit and 4-bit color functions could exist alongside them or not be implemented. +The `clear` and `erase` functions could have default values that match their existing behavior. + +# Unresolved questions + +Should the breaking changes be made to simplify the interface? From 673734d42e84ed57fea15cdfdcfae28d1cea5d0f Mon Sep 17 00:00:00 2001 From: csos95 Date: Tue, 15 Feb 2022 16:42:01 -0600 Subject: [PATCH 2/9] add item for show/hide cursor --- text/0000-add-ansi-escape-codes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md index 3c121d4a..c9f3c65f 100644 --- a/text/0000-add-ansi-escape-codes.md +++ b/text/0000-add-ansi-escape-codes.md @@ -27,6 +27,7 @@ I would like to have the default value in these functions be zero. - Add escape codes for scroll up/down. - Add escape codes for next/previous line. - Add escape code for cursor horizontal position (moves the cursor to column n in the current line). +- Add escape codes for hide/show cursor. If a value passed to any of the functions is invalid, such as 200 being passed to `fg_3bit`, an empty string would be returned. From d6ca849f3a6424a3d3e4bdfb6e617ccc63802781 Mon Sep 17 00:00:00 2001 From: csos95 Date: Tue, 15 Feb 2022 17:19:09 -0600 Subject: [PATCH 3/9] add items for more text styles and cursor stuff --- text/0000-add-ansi-escape-codes.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md index c9f3c65f..fe95163d 100644 --- a/text/0000-add-ansi-escape-codes.md +++ b/text/0000-add-ansi-escape-codes.md @@ -28,6 +28,9 @@ I would like to have the default value in these functions be zero. - Add escape codes for next/previous line. - Add escape code for cursor horizontal position (moves the cursor to column n in the current line). - Add escape codes for hide/show cursor. +- Add escape codes for save/restore cursor position. +- Add escape code for get cursor position (it is sent to stdin). +- Add escape codes for various text styles: italic, strike, conceal, faint. If a value passed to any of the functions is invalid, such as 200 being passed to `fg_3bit`, an empty string would be returned. From 80926b38040328ab5c694bf7e6ede6563fcb1e0c Mon Sep 17 00:00:00 2001 From: Christopher Silva Date: Wed, 16 Feb 2022 11:28:55 -0600 Subject: [PATCH 4/9] Update text/0000-add-ansi-escape-codes.md Co-authored-by: Sean T Allen --- text/0000-add-ansi-escape-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md index fe95163d..8ea0a740 100644 --- a/text/0000-add-ansi-escape-codes.md +++ b/text/0000-add-ansi-escape-codes.md @@ -5,7 +5,7 @@ # Summary -This RFC proposes the addition of more escape code functions to the ANSI primitive of the term package and the consolodation of the thirty-two existing color functions into four functions. +This RFC proposes the addition of more escape code functions to the ANSI primitive of the term package and the consolidation of the thirty-two existing color functions into four functions. # Motivation From 3fd41f9e2a924436bd200a3f02c1a0ee750ccef0 Mon Sep 17 00:00:00 2001 From: csos95 Date: Tue, 22 Feb 2022 12:44:54 -0600 Subject: [PATCH 5/9] update rfc to only include additions --- text/0000-add-ansi-escape-codes.md | 95 +++++++++++++++++++----------- 1 file changed, 60 insertions(+), 35 deletions(-) diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md index 8ea0a740..f0a729ac 100644 --- a/text/0000-add-ansi-escape-codes.md +++ b/text/0000-add-ansi-escape-codes.md @@ -5,59 +5,84 @@ # Summary -This RFC proposes the addition of more escape code functions to the ANSI primitive of the term package and the consolidation of the thirty-two existing color functions into four functions. +This RFC proposes the addition of more escape code functions to the ANSI +primitive of the term package. # Motivation -The purpose of these additional methods is to cover more of the standard ANSI escape codes within the stdlib. +The purpose of these additional methods is to cover more of the standard ANSI +escape codes within the stdlib. # Detailed design -- Add escape codes for 3-bit, 4-bit, 8-bit, and 24-bit colors for the foreground and background. -The naming scheme of the color functions would be `{fg,bg}_{3,4,8,24}bit`. -The 3-bit, 4-bit, and 8-bit versions would take a U8 specifying the color. -The 24-bit versions would take three U8s specifying the r, g, and b values. -- Remove the thirty-two named color functions in favor of the 3-bit and 4-bit functions. -- Add escape codes for enter and leave alternate screen buffer. -- Add escape code for the bell alert. -- Change `clear` and `erase` functions to take a U8 specifying what part of the screen/line to clear. -The default for the escape codes if a value isn't given is zero. -The action these functions currently take is three for `clear` and one for `erase`. -I would like to have the default value in these functions be zero. -- Add escape codes for scroll up/down. -- Add escape codes for next/previous line. -- Add escape code for cursor horizontal position (moves the cursor to column n in the current line). -- Add escape codes for hide/show cursor. -- Add escape codes for save/restore cursor position. -- Add escape code for get cursor position (it is sent to stdin). -- Add escape codes for various text styles: italic, strike, conceal, faint. - -If a value passed to any of the functions is invalid, such as 200 being passed to `fg_3bit`, an empty string would be returned. +## Added Escape Codes + +- 8-bit forground `\x1B[38;5;nm` and background `\x1B[48;5;nm` colors +- 24-bit foreground `\x1B[38;2;r;g;bm` and background `\x1B[48;2;r;g;bm` colors +- enter alternate screen buffer `\x1B[?1049h` and leave alternate screen buffer `\x1B[?1049l` +- bell alert `\x7` +- scroll up `\x1B[nS` and scroll down `\x1B[nT` +- next line `\x1B[nE` and previous line `\x1B[nF` +- cursor horizontal absolute `\x1B[nG` +- hide cursor `\x1B[?25l` and show cursor `\x1B[?25h` +- save cursor position `\x1B[s` and restore cursor position `\x1B[u` +- device status report `\x1B[6n` (sends cursor position to stdin) +- faint `\x1B[2m`, italic `\x1B[3m`, conceal `\x1B[8m`, and strike `\x1B[9m` text +- erase in display `\x1B[nJ` +- erase in line `\x1B[nK` + + +## Erase In Display/Line + +There are currently two similar functions, but they have a couple of issues: +- Neither of them expose the parameter that the escape codes take. +- The `clear` function moves the cursor to the top left and then clears the screen. +This may have been done to create the same result that this escape code gave on DOS. + +Unlike the other added escape codes, these two only have a few valid values +for the parameters. +To enforce the safety of these functions using the type system, four primitives +and two type unions would be defined to be used as the parameters for these +two functions. + +```pony +primitive EraseAfter +primitive EraseBefore +primitive EraseAll +primitive EraseBuffer + +type EraseDisplay is (EraseAfter | EraseBefore | EraseAll | EraseBuffer) +type EraseLine is (EraseAfter | EraseBefore | EraseAll) +``` + # How We Teach This -The added functions would be documented as the existing functions on the `ANSI` primitive are and an example of usage would be added to `ANSI`. +The added functions would be documented as the existing functions on the `ANSI` +primitive are and an example of usage would be added to `ANSI`. # How We Test This -I could not find existing testing for the `ANSI` primitive. -If there are existing tests for these functions, additional tests in the same format would be added to ensure that the new functions return the correct escape codes. -Most of these functions are just directly returning a string of the escape code without any parameters so they're pretty straightforward. +The functions that have parameters would have tests added to ensure that they +return the correct escape code for the given parameters. + +The functions that would have parameters and would be tested are: +- 8-bit and 24-bit colors for the foreground and background +- scroll up and scroll down +- next line and previous line +- cursor horizontal absolute +- erase_display +- erase_line # Drawbacks -The removal of the existing color functions and the change to the `clear` and `erase` functions (if the default of zero is used) are breaking changes. +Some escape codes may not work on all terminals. # Alternatives -## Alternative to the rfc as a whole -These escape codes can simply be printed independently of whatever is supported by functions on `ANSI`. -Having them available on `ANSI` simply makes it so that users do not need to look the codes up themselves. - -## Alternative to the breaking changes -The existing color functions could remain and the 3-bit and 4-bit color functions could exist alongside them or not be implemented. -The `clear` and `erase` functions could have default values that match their existing behavior. +Don't add these escape code functions and have users look up and print the +escape codes they want. # Unresolved questions -Should the breaking changes be made to simplify the interface? +None From 15f6665004a455fade2d04855ae1fc6925234be0 Mon Sep 17 00:00:00 2001 From: Christopher Silva Date: Tue, 22 Feb 2022 13:10:01 -0600 Subject: [PATCH 6/9] fix spelling Co-authored-by: Borja o'Cook --- text/0000-add-ansi-escape-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md index f0a729ac..d53fa0f9 100644 --- a/text/0000-add-ansi-escape-codes.md +++ b/text/0000-add-ansi-escape-codes.md @@ -17,7 +17,7 @@ escape codes within the stdlib. ## Added Escape Codes -- 8-bit forground `\x1B[38;5;nm` and background `\x1B[48;5;nm` colors +- 8-bit foreground `\x1B[38;5;nm` and background `\x1B[48;5;nm` colors - 24-bit foreground `\x1B[38;2;r;g;bm` and background `\x1B[48;2;r;g;bm` colors - enter alternate screen buffer `\x1B[?1049h` and leave alternate screen buffer `\x1B[?1049l` - bell alert `\x7` From 3a95040181cc4759857e16c305190b68f6fbb473 Mon Sep 17 00:00:00 2001 From: Christopher Silva Date: Tue, 22 Feb 2022 13:11:37 -0600 Subject: [PATCH 7/9] Update text/0000-add-ansi-escape-codes.md Co-authored-by: Sean T Allen --- text/0000-add-ansi-escape-codes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md index d53fa0f9..f1ec6b49 100644 --- a/text/0000-add-ansi-escape-codes.md +++ b/text/0000-add-ansi-escape-codes.md @@ -67,6 +67,7 @@ The functions that have parameters would have tests added to ensure that they return the correct escape code for the given parameters. The functions that would have parameters and would be tested are: + - 8-bit and 24-bit colors for the foreground and background - scroll up and scroll down - next line and previous line From 6eb358b1d2f29a1fd9e9f1daeedfa1e91eacb337 Mon Sep 17 00:00:00 2001 From: Christopher Silva Date: Tue, 22 Feb 2022 13:12:43 -0600 Subject: [PATCH 8/9] Update text/0000-add-ansi-escape-codes.md Co-authored-by: Sean T Allen --- text/0000-add-ansi-escape-codes.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md index f1ec6b49..21d5cc98 100644 --- a/text/0000-add-ansi-escape-codes.md +++ b/text/0000-add-ansi-escape-codes.md @@ -54,8 +54,6 @@ primitive EraseBuffer type EraseDisplay is (EraseAfter | EraseBefore | EraseAll | EraseBuffer) type EraseLine is (EraseAfter | EraseBefore | EraseAll) ``` - - # How We Teach This The added functions would be documented as the existing functions on the `ANSI` From 575812b1d15079e90d81e7e34a9dfd233992ba4c Mon Sep 17 00:00:00 2001 From: Christopher Silva Date: Tue, 22 Feb 2022 13:16:56 -0600 Subject: [PATCH 9/9] Update text/0000-add-ansi-escape-codes.md Co-authored-by: Sean T Allen --- text/0000-add-ansi-escape-codes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0000-add-ansi-escape-codes.md b/text/0000-add-ansi-escape-codes.md index 21d5cc98..adb59b3b 100644 --- a/text/0000-add-ansi-escape-codes.md +++ b/text/0000-add-ansi-escape-codes.md @@ -35,6 +35,7 @@ escape codes within the stdlib. ## Erase In Display/Line There are currently two similar functions, but they have a couple of issues: + - Neither of them expose the parameter that the escape codes take. - The `clear` function moves the cursor to the top left and then clears the screen. This may have been done to create the same result that this escape code gave on DOS.