starred/terminal
1
0
Fork 0
mirror of https://github.com/microsoft/terminal.git synced 2026-02-03 21:25:34 +00:00
Code Issues 19.0k Packages Projects Releases 20 Wiki Activity

Command Shell Script to generate and display all combinations of SGR properties which can be applied as ANSI Escape Sequence control characters to text #8982

New Issue
Closed
opened 2026-01-31 01:42:56 +00:00 by claunia · 4 comments
claunia commented 2026-01-31 01:42:56 +00:00
Owner
Copy Link

Originally created by @rbeesley on GitHub (Jun 12, 2020).

Description of the new feature/enhancement

Inspired by Daniel Crisman's BASH script from http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html. The proposed .cmd script tool echoes a bunch of color codes to the terminal to demonstrate what's available. The end of the file defines the table layout and allows the user to configure whatever matrix of ANSI Escape Sequence control characters they wish. It accomplishes this with no required external dependencies. Of the optional dependencies, the first is on PowerShell to generate the 0x1b ESC, but this can be implemented using an unprintable character, and the only recommended dependency is on %SystemRoot%\system32\chcp.com when the rendered content contains Unicode code points, used to both preserve the code page before the script was ran, switch to code page 65001, and to restore the original when complete.

Proposed technical implementation details (optional)

The .cmd script uses a "Data Segment" in the file, a section of the script blocked from execution by a guards, and it describes the configuration of the table to be displayed. You provide the text you want to display, a list of column SGR properties, and a list of row SGR properties. These properties are written to the box header and the stub header to indicate what the intersection of properties will be, for example Background for columns and Foreground for rows, it left, center, or right justifies the output for improved readability, and each cell renders a sample text string proceeded by these column and row SGR properties and terminated by a reset. These rendered rows are written to a table array variable.

Because the processing time for doing text alignment in a .cmd script is an expensive operation, there is an animated spinner, which can be disabled, which indicates to the user that the script is processing. Drawing the animation takes some time, so the user has a choice of waiting while the processing is happening in the background with no indication that the script is still running, or they can incur a slight increase in the amount of time it takes to run but have an animated indicator that the script is working. Once the table has been completely built, a routine will quickly dump the entire fully rendered view to the terminal window, allowing the user to see the application of all of the properties applied to the sample text string.

The entire script is fully customizable just by modifying the data segment which describes the table and/or by configuring a few environment variables at the top of the script. One of these variables replaces the 0x1b escape with the Unicode ␛ character. This makes it very easy to see in printable characters what is being rendered with applied SGR properties. Because this character is Unicode, this is where the optional dependency upon chcp.com comes from, but it was latter recognized that this is necessary if the sample text contains Unicode, so it is recommended that it is left on by default, but if not needed and the user doesn't want any external dependencies, it can be switched off.

Functions which tend to be expensive operations, such as figuring out the length of a string, the maximum value between two values, text alignment operations, repeating a string a number of times, and drawing the processing spinner animation, these have been written as macros to improve the script performance. The script is documented where and how it can be documented. This makes it useful for those writing color schemes for Windows Terminal to see how their colors will be shown, can assist in identifying and debugging when applied SGR properties aren't being shown correctly, and demonstrates and uses advanced techniques writing batch files so that these techniques can be used by others. All of this is self-contained in a single .cmd script. If other SGR properties become supported, adding them will be trivial.

In #6176, zadjii said in a comment that he'd welcome this PR. As someone who has contributed on several color scheme related check ins, this is the product of lot's of manhours of work over a few years, producing a tool that I think is ready for more general consumption, with a minimum requirement of running under cmd.exe, and I believe it showcases a lot of valuable techniques for writing .cmd scripts which haven't really been coalesced before. Adding it as a tool to Terminal seems like an appropriate match providing value to those who can use it. It is the Windows equivalent of Daniel Crisman's BASH script with more features and capabilities than the original.

Preliminary script in action:
ansi-color cmd

Originally created by @rbeesley on GitHub (Jun 12, 2020). <!-- 🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨 I ACKNOWLEDGE THE FOLLOWING BEFORE PROCEEDING: 1. If I delete this entire template and go my own path, the core team may close my issue without further explanation or engagement. 2. If I list multiple bugs/concerns in this one issue, the core team may close my issue without further explanation or engagement. 3. If I write an issue that has many duplicates, the core team may close my issue without further explanation or engagement (and without necessarily spending time to find the exact duplicate ID number). 4. If I leave the title incomplete when filing the issue, the core team may close my issue without further explanation or engagement. 5. If I file something completely blank in the body, the core team may close my issue without further explanation or engagement. All good? Then proceed! --> # Description of the new feature/enhancement Inspired by Daniel Crisman's BASH script from http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html. The proposed `.cmd` script tool echoes a bunch of color codes to the terminal to demonstrate what's available. The end of the file defines the table layout and allows the user to configure whatever matrix of ANSI Escape Sequence control characters they wish. It accomplishes this with no required external dependencies. Of the optional dependencies, the first is on PowerShell to generate the `0x1b` ESC, but this can be implemented using an unprintable character, and the only recommended dependency is on `%SystemRoot%\system32\chcp.com` when the rendered content contains Unicode code points, used to both preserve the code page before the script was ran, switch to code page 65001, and to restore the original when complete. <!-- A clear and concise description of what the problem is that the new feature would solve. Describe why and how a user would use this new functionality (if applicable). --> # Proposed technical implementation details (optional) The `.cmd` script uses a "Data Segment" in the file, a section of the script blocked from execution by a guards, and it describes the configuration of the table to be displayed. You provide the text you want to display, a list of column SGR properties, and a list of row SGR properties. These properties are written to the box header and the stub header to indicate what the intersection of properties will be, for example Background for columns and Foreground for rows, it left, center, or right justifies the output for improved readability, and each cell renders a sample text string proceeded by these column and row SGR properties and terminated by a reset. These rendered rows are written to a table array variable. Because the processing time for doing text alignment in a `.cmd` script is an expensive operation, there is an animated spinner, which can be disabled, which indicates to the user that the script is processing. Drawing the animation takes some time, so the user has a choice of waiting while the processing is happening in the background with no indication that the script is still running, or they can incur a slight increase in the amount of time it takes to run but have an animated indicator that the script is working. Once the table has been completely built, a routine will quickly dump the entire fully rendered view to the terminal window, allowing the user to see the application of all of the properties applied to the sample text string. The entire script is fully customizable just by modifying the data segment which describes the table and/or by configuring a few environment variables at the top of the script. One of these variables replaces the `0x1b` escape with the Unicode `␛` character. This makes it very easy to see in printable characters what is being rendered with applied SGR properties. Because this character is Unicode, this is where the optional dependency upon chcp.com comes from, but it was latter recognized that this is necessary if the sample text contains Unicode, so it is recommended that it is left on by default, but if not needed and the user doesn't want any external dependencies, it can be switched off. Functions which tend to be expensive operations, such as figuring out the length of a string, the maximum value between two values, text alignment operations, repeating a string a number of times, and drawing the processing spinner animation, these have been written as macros to improve the script performance. The script is documented where and how it can be documented. This makes it useful for those writing color schemes for Windows Terminal to see how their colors will be shown, can assist in identifying and debugging when applied SGR properties aren't being shown correctly, and demonstrates and uses advanced techniques writing batch files so that these techniques can be used by others. All of this is self-contained in a single `.cmd` script. If other SGR properties become supported, adding them will be trivial. <!-- A clear and concise description of what you want to happen. --> In #6176, zadjii said in a [comment](https://github.com/microsoft/terminal/issues/6176#issuecomment-642582689) that he'd welcome this PR. As someone who has contributed on several color scheme related check ins, this is the product of lot's of manhours of work over a few years, producing a tool that I think is ready for more general consumption, with a minimum requirement of running under cmd.exe, and I believe it showcases a lot of valuable techniques for writing `.cmd` scripts which haven't really been coalesced before. Adding it as a tool to Terminal seems like an appropriate match providing value to those who can use it. It is the Windows equivalent of Daniel Crisman's BASH script with more features and capabilities than the original. Preliminary script in action: ![ansi-color cmd](https://user-images.githubusercontent.com/3703112/84450328-a4072600-ac04-11ea-8868-8d8a97d187c2.gif)
claunia commented 2026-01-31 01:42:58 +00:00
Author
Owner
Copy Link

@DHowett commented on GitHub (Jun 12, 2020):

👍

@DHowett commented on GitHub (Jun 12, 2020): :+1:
claunia commented 2026-01-31 01:42:58 +00:00
Author
Owner
Copy Link

@zadjii-msft commented on GitHub (Dec 9, 2021):

@rbeesley did you plan on submitting a PR for this?

@zadjii-msft commented on GitHub (Dec 9, 2021): @rbeesley did you plan on submitting a PR for this?
claunia commented 2026-01-31 01:42:58 +00:00
Author
Owner
Copy Link

@rbeesley commented on GitHub (Dec 9, 2021):

I can. I have it ready and can prepare it today.

@rbeesley commented on GitHub (Dec 9, 2021): I can. I have it ready and can prepare it today.
claunia commented 2026-01-31 01:42:59 +00:00
Author
Owner
Copy Link

@ghost commented on GitHub (Feb 3, 2022):

:tada:This issue was addressed in #11932, which has now been successfully released as Windows Terminal Preview v1.13.10336.0.🎉

Handy links:

@ghost commented on GitHub (Feb 3, 2022): :tada:This issue was addressed in #11932, which has now been successfully released as `Windows Terminal Preview v1.13.10336.0`.:tada: Handy links: * [Release Notes](https://github.com/microsoft/terminal/releases/tag/v1.13.10336.0) * [Store Download](https://www.microsoft.com/store/apps/9n8g5rfz9xk3?cid=storebadge&ocid=badge)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
⛺ Reserved
A11yCO
A11yMAS
A11ySev1
A11ySev2
A11ySev3
A11yTTValidated
A11yUsable
A11yVoiceAccess
A11yWCAG
Area-Accessibility
Area-AtlasEngine
Area-AzureShell
Area-Build
Area-Build
Area-Chat
Area-CmdPal
Area-CodeHealth
Area-Commandline
Area-CookedRead
Area-DefApp
Area-Extensibility
Area-Fonts
Area-GroupPolicy
Area-i18n
Area-Input
Area-Interaction
Area-Interop
Area-Localization
Area-Output
Area-Performance
Area-Portable
Area-Quality
Area-Remoting
Area-Rendering
Area-Schema
Area-Server
Area-Settings
Area-SettingsUI
Area-ShellExtension
Area-ShellExtension
Area-ShellExtension
Area-Suggestions
Area-Suggestions
Area-TerminalConnection
Area-TerminalControl
Area-Theming
Area-UserInterface
Area-VT
Area-Windowing
Area-WPFControl
AutoMerge
Blocking-Ingestion
Culprit-Centennial
Culprit-WinUI
Disability-All
Disability-Blind
Disability-LowVision
Disability-Mobility
External-Blocked-WinUI3
Fixed
Gathering-Data
good first issue
HCL-E+D
HCL-WindowsTerminal
Help Wanted
Impact-Compatibility
Impact-Compliance
Impact-Correctness
Impact-Visual
In-PR
InclusionBacklog
InclusionBacklog-Windows TerminalWin32
InclusionCommitted-202206
Issue-Bug
Issue-Docs
Issue-Feature
Issue-Feature
Issue-Question
Issue-Samples
Issue-Scenario
Issue-Task
Needs-Attention
Needs-Author-Feedback
Needs-Bisect
Needs-Discussion
Needs-Repro
Needs-Tag-Fix
Needs-Tag-Fix
Needs-Triage
No-Recent-Activity
Priority-0
Priority-1
Priority-2
Priority-3
Product-Cmd.exe
Product-Colortool
Product-Colortool
Product-Colortool
Product-Conhost
Product-Conpty
Product-Meta
Product-Powershell
Product-Terminal
Product-WSL
pull-request
Mirrored from GitHub Pull Request
 Resolution-Answered
Resolution-By-Design
Resolution-Duplicate
Resolution-External
Resolution-Fix-Available
Resolution-Fix-Committed
Resolution-No-Repro
Resolution-Won't-Fix
Severity-Blocking
Severity-Crash
Severity-DataLoss
spam
this-will-be-a-breaking-change
Tracking-External
WindowsTerminal_Win32
Work-Item
zAskModeBug
zInbox-Bug
No Label Area-CodeHealth Help Wanted Issue-Feature Product-Meta Resolution-Fix-Committed
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claunia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/terminal#8982
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?