-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
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.
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
Support color ansi code sequences in custom help #2251
base: develop
Are you sure you want to change the base?
Conversation
I added a whole bunch of simple style hooks (from #2262). Some notes on current state of play. I am not planning to add full JSDoc typing for all the style routines, keep the code compact. Most of them are one line of code. The implementation of It would reduce some boilerplate code if It is currently fine for authors to put color into the methods like The style routines get called even if color will ultimately be suppressed. The author does not need to know the rules. The current implementation strips colours later if color is not appropriate. |
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
)