Support color ansi code sequences in custom help

[shadowspawn]

Pull Request

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 of optionTerm() or styleOptionTerm() 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 focused formatItem() and boxWrap().

Now easy to do some previously messy help customisations (examples added):

• man-style help with item descriptions on new lines
• use util:styleText to add color to help
• use Chalk for color and padding and wrapping support and completely replace default implementation

Changes 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.

ChangeLog

Add

• support for adding custom color and style to Help output
• simple hooks for styling Help using Command.configureHelp()
  • styleTitle()
  • styleUsage() and styleCommandText
  • styleItemDescription(), styleCommandDescription(), and styleDescriptionText()
  • styleOptionTerm(), styleSubcommandTerm(), and styleArgumentTerm()
  • styleOptionText(), styleSubcommandText(), and styleArgumentText()
• new Help class methods to support color and allow easier customisation
  • minWidthToWrap property
  • prepareContext()
  • displayWidth()
  • boxWrap()
  • formatItem()
  • preformatted()
• Command.configureOutput() now includes getOutHasColors(), getErrHasColours(), and stripColor()

Deleted

• Help.wrap() (refactored into formatItem and boxWrap)

[shadowspawn]

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 styleUsage is not super robust. But it does allow author to have matching colours for options and subcommands and arguments in the usage and the relevant section in help with just 3 simple style hooks.

It would reduce some boilerplate code if optionTerm called styleOptionTerm (and all the other similar pairs!), but I currently prefer the clean separation.

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.

[manuel3108]

Is there a way we can try this out and provide early feedback? i,e. a preview release or something?

Edit: This is great work, and seems to be moving in the right direction!

[shadowspawn]

There isn't an npm prerelease, but you can install it using git protocol (with npm).

For example, to install from the current code on this pull request:

npm install git+https://github.com:tj/commander.js#pull/2251

[manuel3108]

There isn't an npm prerelease, but you can install it using git protocol (with npm).

Thanks, this is the actual url, in case anybody want's to give it a try.

npm install git+https://github.com:shadowspawn/commander.js#feature/colour-help

Overall this works very well, nice job.