mrz1988 commented 5 years ago

Background

Over the last five years, after lilies work began, stopped, and was set on the shelf for more important doings, the landscape for colored text command line tools changed greatly. The initial work on lilies was meant to provide 16 colors of text to as many different command line utilities as possible, and strive for compatibility. Over the years, newer technologies have been more thoroughly adopted, allowing better support for 256 color and 24-bit color text in lots of terminal environments. Additionally, I realized that it was probably important to make sure that lilies can remain flexible, and be backward compatible to both old and new terminal environments, rounding off colors to some good approximation. This would allow developers to continue to use whatever colors they wanted, and the colors would mainly "just work" in as many terminals as humanly possible.

Windows 10 now also supports a much wider array of colors, and can support real ANSI character sequences to draw them. This means that colorama is now only necessary for older windows versions, and will likely hinder some use of ANSI codes on newer Windows versions. This means trying to find a way to support coloring on windows in all environments as seamlessly as possible.

Onto features...

New colors

This patch completely rebuilds the coloring and styling engine internal to lilies. While we used to only support 16 colors across as many operating system configurations as possible, we can now support all of the following configurations:

4-bit ANSI 8 color terminals
4-bit ANSI 16 color terminals using the "bright" character
4-bit ANSI 16 color terminals using the extended "bright" sequences
8-bit ANSI 256 color terminals
24-bit ANSI true color terminals
WIN32-based coloring on Windows via colorama
ANSI-based Windows terminal coloring, triggered by setting a registry flag

These colors can be selected for use using the same grow command integral to the API, using an all-new style parsing engine (more below). rgb and hsl functions were also added to help select an even more diverse set of colors.

Styles

In addition to a ton of new color configurations, lilies now also allows styling text with bold, italic, underlined, or blinking fonts (in supported terminals). Styles can be applied the same way that colors always have. Because of this change, a lilies Style object now includes foreground and background colors, so all of them can be applied to text together. This has resulted in a few changes to nomenclature in the API, and callers will notice that some color parameters or names have been shifted to adopt the word style in more places.

New parsing engine

All new colors and styles need a more powerful way to represent them in text. When coloring text in lilies, the new format allows styles, foreground, and background colors to all be specified in a single style string to grow(). This looks something like this:

bold, italic red on lime: ugly, but you get the picture. on blue: a simple background change. green: as always, a convenient way to only specify the foreground color.

All new color names are also really fucking diverse, since we've adopted all of the XTerm names for the 256 standard ANSI colors. To help programmers decide how they want to implement them, color names can be represented as:

camelCase snake_case PascalCase SHOUTY_CASE or even just fucking spaces

in aNY wEiRd FORm_at that you want. Go wild if you have to, but try not to hurt anyone's eyes.

All new compiler

All new colors and styles across a wide range of terminals requires a better compiler. The new compiler is diff-based rather than based on explicit styles, so the ANSI reset code isn't abused as much. This also allows lilies to communicate the same style changes to the terminal in fewer characters. Truth be told, I'm sure this doesn't matter much, but it allows the engine to do things like make one word bold without having to turn off/on the colors.

High quality terminal control

If you don't know what type of terminal you have, lilies will do its best to pick the right runtime for you, without you needing to know. However, if you needed to target a different behavior in the middle of your program, like shut off colors, or simulate how output might look in a different terminal, lilies can swap out terminals for you quickly. For Windows terminals, this also means making sure that colorama is disabled when asked, and the virtual terminal settings are cleaned up back to the way lilies found them. This may be because you switched out behavior to a non-windows terminal, or just because program execution has finished, and it's better to be safe by not polluting output of other programs.

General code improvements

I'll be real, some of my old code wasn't great. Some of my new code isn't great either. This PR gets us a little bit closer to good, testable code, and a nice, clean API. This will only continue to improve as we near a real 1.0 release.

codecov-io commented 5 years ago

Codecov Report

Merging #42 into master will increase coverage by 2.26%. The diff coverage is 87.91%.

@@            Coverage Diff             @@
##           master      #42      +/-   ##
==========================================
+ Coverage      83%   85.26%   +2.26%     
==========================================
  Files          16       31      +15     
  Lines        1106     1629     +523     
  Branches      189      261      +72     
==========================================
+ Hits          918     1389     +471     
- Misses        161      207      +46     
- Partials       27       33       +6

Impacted Files	Coverage Δ
lilies/style/palette.py	`100% <100%> (ø)`
lilies/terminal/ansi8open.py	`100% <100%> (ø)`
lilies/manage.py	`100% <100%> (ø)`	:arrow_up:
lilies/terminal/ansicodes.py	`100% <100%> (ø)`	:arrow_up:
lilies/grow.py	`100% <100%> (+13.33%)`	:arrow_up:
lilies/style/parse.py	`96.72% <100%> (+0.29%)`	:arrow_up:
lilies/terminal/__init__.py	`100% <100%> (ø)`
lilies/compiler/__init__.py	`100% <100%> (ø)`
lilies/style/colors.py	`100% <100%> (+9.75%)`	:arrow_up:
lilies/style/styles.py	`100% <100%> (ø)`	:arrow_up:
... and 34 more

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update f228c69...14210c3. Read the comment docs.