Support color ansi code sequences in custom help #2251
Draft
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull Request
Feedback welcome at this stage.
Problem
People would like to add color to the Help: #301 (opened 10 years ago!).
Part of the intent of #1365 was to allow adding colour, but due to interactions with padding and wrapping it was too hard.
Solution
Make it easy to add colour and styling. Treat ansi code sequences as zero width when padding and wrapping.
There is a new layer of
style
hooks which are just passed a string. There is not an assumption that only the style hooks do styling. So for example either ofoptionTerm()
orstyleOptionTerm()
could add styling.Build in support for common patterns for controlling colour (like
NO_COLOR
), and check output stream for color support.Strip escape sequences if necessary before displaying. So author does not need to check whether to use color when styling strings.
Refactor complex
wrap()
into more focusedformatItem()
andboxWrap()
.Now easy to do some previously messy help customisations (examples added):
util:styleText
to add color to helpChanges from previous implementation
Wrapping of a very long single "word" is now a soft wrap rather than a hard wrap. Simpler implementation, and probably rare.
Dropped the partial wrapping support for Zero Width Space (ZWSP) as not displayed as zero width in Mac Terminal (among others), not consistent with general treatment of ansi escape sequences in this PR, and unlikely to be used by authors. For interest, another similar special character is the the soft hyphen.
ToDo:
ChangeLog
Add
Help
usingCommand.configureHelp()
styleTitle()
styleUsage()
andstyleCommandText
styleItemDescription()
,styleCommandDescription
(), andstyleDescriptionText()
styleOptionTerm
(),styleSubcommandTerm()
, andstyleArgumentTerm()
styleOptionText()
,styleSubcommandText()
, andstyleArgumentText()
Help
class methods to support color and allow easier customisationminWidthToWrap
propertyprepareContext()
displayWidth()
boxWrap()
formatItem()
preformatted()
Command.configureOutput()
now includesgetOutHasColors()
,getErrHasColours()
, andstripAnsi()
Deleted
Help.wrap()
(refactored intoformatItem
andboxWrap
)