AnsiHtmlFormatter and ANSI-aware shell-like lexers

[kdeldycke]

After a year of usage in my Click Extra project and lots of pain trying to integrate it with Click, Sphinx and Furo, I finally reached a point where my stack of monkey-patch work as intended and validates my efforts.

So now I'm wondering if there are some stuff worth contributing back to pygments-ansi-color. Namely:

• AnsiHtmlFormatter: which automatically patch the user-provided style with custom style so you do not have to perform the color_tokens dance.

• A collection of shell-like lexers capable of rendering ANSI codes in Generic.Output.

[chriskuehl]

Thanks for the contributions!

The AnsiHtmlFormatter looks good to me. If I understand correctly, users would be able to change something like

# current code
from pygments.formatters import HtmlFormatter
from pygments_ansi_color import ExtendedColorHtmlFormatterMixin


class MyFormatter(ExtendedColorHtmlFormatterMixin, HtmlFormatter):
    pass

_my_formatter = MyFormatter(
    noclasses=False,
    linespans='line',
    style=MY_STYLE,
)

to simply

# new code
from pygments_ansi_color import AnsiHtmlFormatter

_my_formatter = AnsiHtmlFormatter(
    noclasses=False,
    linespans='line',
    style=MY_STYLE,
)

Is that right?

The additional lexers feel like they may be too tied to your specific use-case and not the best fit here, although maybe I'm not fully understanding their purpose.

[kdeldycke]

to simply

# new code
from pygments_ansi_color import AnsiHtmlFormatter

_my_formatter = AnsiHtmlFormatter(
    noclasses=False,
    linespans='line',
    style=MY_STYLE,
)

Is that right?

Yes.

But even better, you wouldn't have to defined you own style, and just pass one of Pygments' default:

import pygments

from pygments_ansi_color import AnsiHtmlFormatter
 
_my_formatter = AnsiHtmlFormatter(
    noclasses=False,
    linespans='line',
    style="xcode",
)

The magic of AnsiHtmlFormatter is that it would patch on-the-fly the style passed with the style= parameters. So you do not have to do the color_tokens dance. AnsiHtmlFormatter will do it for you magiccaly! :)

[kdeldycke]

As for the additional lexers, yes, they're a little bit cumbersome and hard to maintain. I can understand they're not fit for the pygments-ansi-color project if you want to keep it light.

The reason for these lexers is that some default lexers available in Pygments allow a mix of command lines and terminal output. That is the case of pycon, shell-session, console, julia-repl and so on.

What I propose with my new custom lexers are an ANSI-capable variant, which are the same exact copy of the original from Pygments. But parse the sections that are supposed to be console output (i.e. encapsulated by Generic.Output tokens), and renders the ANSI codes found there with pygments-ansi-color.

I've implemented a working exemple in my Click Extra project: https://kdeldycke.github.io/click-extra/pygments.html#lexers . See there how the Python console >>> print(art) prompt renders ║▌█║ ANSI Art ▌│║▌ with all its color? That's my custom ansi-pycon lexer that I want to contribute back to pygments-ansi-color! :)

[chriskuehl]

As for the additional lexers, yes, they're a little bit cumbersome and hard to maintain. I can understand they're not fit for the pygments-ansi-color project if you want to keep it light.

Yeah, I think this is more than I'd like to include in this package, I would like to keep this mainly to the existing lexer.

Happy to merge the AnsiHtmlFormatter change though if you'd like to make a PR for it.

[kdeldycke]

Yeah, I think this is more than I'd like to include in this package, I would like to keep this mainly to the existing lexer.

Yeah, makes sense. I'll keep my extra ANSI-capable language lexers in my own project then.

BTW, do you mind if I had a little explanation at the end of the read me of pygments-ansi-color to point to them?

Happy to merge the AnsiHtmlFormatter change though if you'd like to make a PR for it.

OK, working on an PR then.