Skip to content

Conversation

@pbrisbin
Copy link
Member

@pbrisbin pbrisbin commented Dec 8, 2025

This change removes the manual Text-building of our current terminal
formatter and instead uses Prettyprinter. This is a much better tool
for the job and produces very nice output in less code.

The actual resulting terminal output was improved in a few small ways:

  1. The colors of attributes is improved, because Prettyprinter's
    annotations system makes it easier to do fancier things
  2. Long messages that themselves span the breakpoint are wrapped in a
    hanging-indent style, since that too is easier to do with
    Prettyprinter.

It may have been possible to do this in a way opaque to end-users,
except for one thing: colors.

The best-practice way to ansi-escape Prettyprinter output is to use
its annotations feature. Elements within a Doc are annotated with the
bits that should be colored at render time. It's also a best-practice
to annotate your Doc, not directly with color escapes, but with
semantic annotations (see our Ann type). Those can then be mapped
centrally to color escapes, again as part of rendering (see our
annToAnsi function).

This approach comes with a number of nice properties for our use-case in
Blammo: it means the choice of colors-or-not, and what those colors are,
need not be known and passed around at the time log messages are
built. Rather, it is centralized at the place where the log messages
are rendered.

Therefore, I decided to lean into this and entirely replace our Color
module with the Terminal.Doc.Ann type. For example, there is no longer
a feature like getLoggerColors, which was meant to provide end-users
colors-or-not as appropriate. Instead, such users can use Ann all the
time and the colors-or-not concern is handled later.

Most users, those who are not actually building and pushing messages
directly to Logger, are not affected by this, but those that are will
require pretty big changes with this new version.

This change removes the manual `Text`-building of our current terminal
formatter and instead uses `Prettyprinter`. This is a much better tool
for the job and produces very nice output in less code.

The actual resulting terminal output was improved in a few small ways:

1. The colors of attributes is improved, because `Prettyprinter`'s
   annotations system makes it easier to do fancier things
2. Long messages that themselves span the breakpoint are wrapped in a
   hanging-indent style, since that too is easier to do with
   `Prettyprinter`.

It may have been possible to do this in a way opaque to end-users,
except for one thing: colors.

The best-practice way to ansi-escape `Prettyprinter` output is to use
its annotations feature. Elements within a `Doc` are annotated with the
bits that should be colored at render timer. It's also a best-practice
to annotate your `Doc`, not directly with color escapes, but with
semantic annotations (see our `Ann` type). Those can then be mapped
centrally to color escapes, again as part of rendering (see our
`annToAnsi` function).

This approach comes with a number of nice properties for our use-case in
Blammo: it means the choice of colors-or-not, and what those colors are,
need not be known and passed around at the time log messages are
_built_. Rather, it is centralized at the place where the log messages
are rendered.

Therefore, I decided to lean into this and entirely replace our `Color`
module with the `Terminal.Doc.Ann` type. For example, there is no longer
a feature like `getLoggerColors`, which was meant to provide end-users
colors-or-not as appropriate. Instead, such users can use `Ann` all the
time and the colors-or-not concern is handled later.

Most users, those who are not actually building and pushing messages
directly to `Logger`, are not affected by this, but those that are will
require pretty big changes with this new version.
getLoggerReformat = lReformat

setLoggerReformat
:: (LogSettings -> Colors -> LogLevel -> LoggedMessage -> ByteString)
Copy link
Member Author

@pbrisbin pbrisbin Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An example simplification: the "reformat" concern doesn't need the settings or colors because those are now only necessary for layout, which happens in the rendering step (where those things were already available).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants