2024-08-05 00:44:23 +00:00
|
|
|
# TARTRAZINE
|
2024-08-02 20:03:39 +00:00
|
|
|
|
2024-09-04 14:42:48 +00:00
|
|
|
[![Tests](https://github.com/ralsina/tartrazine/actions/workflows/ci.yml/badge.svg)](https://github.com/ralsina/tartrazine/actions/workflows/ci.yml)
|
2024-09-04 14:44:33 +00:00
|
|
|
[![codecov](https://codecov.io/gh/ralsina/tartrazine/branch/main/graph/badge.svg?token=52XBPNL99F)](https://codecov.io/gh/ralsina/tartrazine)
|
2024-09-04 14:42:48 +00:00
|
|
|
|
2024-08-05 00:44:23 +00:00
|
|
|
Tartrazine is a library to syntax-highlight code. It is
|
2024-08-04 23:36:35 +00:00
|
|
|
a port of [Pygments](https://pygments.org/) to
|
2024-08-25 01:33:24 +00:00
|
|
|
[Crystal](https://crystal-lang.org/).
|
2024-08-04 23:36:35 +00:00
|
|
|
|
2024-08-25 01:33:24 +00:00
|
|
|
It also provides a CLI tool which can be used to highlight many things in many styles.
|
2024-08-04 23:36:35 +00:00
|
|
|
|
2024-08-26 23:18:28 +00:00
|
|
|
Currently Tartrazine supports 247 languages and has 331 themes (63 from Chroma,
|
|
|
|
the rest are base16 themes via [Sixteen](https://github.com/ralsina/sixteen)
|
2024-08-06 21:31:29 +00:00
|
|
|
|
2024-08-02 20:03:39 +00:00
|
|
|
## Installation
|
|
|
|
|
2024-08-26 23:30:37 +00:00
|
|
|
If you are using Arch: Use yay or your favourite AUR helper, package name is `tartrazine`.
|
|
|
|
|
2024-08-11 14:54:00 +00:00
|
|
|
From prebuilt binaries:
|
|
|
|
|
|
|
|
Each release provides statically-linked binaries that should
|
2024-08-26 23:18:28 +00:00
|
|
|
work on any Linux. Get them from the [releases page](https://github.com/ralsina/tartrazine/releases)
|
|
|
|
and put them in your PATH.
|
2024-08-11 14:54:00 +00:00
|
|
|
|
|
|
|
To build from source:
|
|
|
|
|
|
|
|
1. Clone this repo
|
|
|
|
2. Run `make` to build the `tartrazine` binary
|
|
|
|
3. Copy the binary somewhere in your PATH.
|
2024-08-02 20:03:39 +00:00
|
|
|
|
2024-08-16 17:03:05 +00:00
|
|
|
## Usage as a CLI tool
|
|
|
|
|
2024-08-23 16:30:14 +00:00
|
|
|
Show a syntax highlighted version of a C source file in your terminal:
|
|
|
|
|
|
|
|
```shell
|
2024-08-26 23:18:28 +00:00
|
|
|
tartrazine whatever.c -l c -t catppuccin-macchiato --line-numbers -f terminal
|
2024-08-23 16:30:14 +00:00
|
|
|
```
|
|
|
|
|
2024-08-23 17:46:26 +00:00
|
|
|
Generate a standalone HTML file from a C source file with the syntax highlighted:
|
2024-08-23 16:30:14 +00:00
|
|
|
|
2024-08-16 17:03:05 +00:00
|
|
|
```shell
|
2024-08-25 01:33:24 +00:00
|
|
|
$ tartrazine whatever.c -t catppuccin-macchiato --line-numbers \
|
2024-08-26 23:18:28 +00:00
|
|
|
--standalone -f html -o whatever.html
|
2024-08-16 17:03:05 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## Usage as a Library
|
2024-08-02 20:03:39 +00:00
|
|
|
|
2024-08-06 20:01:14 +00:00
|
|
|
This works:
|
2024-08-02 20:03:39 +00:00
|
|
|
|
2024-08-06 20:01:14 +00:00
|
|
|
```crystal
|
|
|
|
require "tartrazine"
|
2024-08-02 20:03:39 +00:00
|
|
|
|
2024-08-06 20:01:14 +00:00
|
|
|
lexer = Tartrazine.lexer("crystal")
|
|
|
|
theme = Tartrazine.theme("catppuccin-macchiato")
|
2024-08-19 15:58:02 +00:00
|
|
|
formatter = Tartrazine::Html.new
|
|
|
|
formatter.theme = theme
|
|
|
|
puts formatter.format(File.read(ARGV[0]), lexer)
|
2024-08-06 20:01:14 +00:00
|
|
|
```
|
2024-08-02 20:03:39 +00:00
|
|
|
|
|
|
|
## Contributing
|
|
|
|
|
2024-08-04 23:36:35 +00:00
|
|
|
1. Fork it (<https://github.com/ralsina/tartrazine/fork>)
|
2024-08-02 20:03:39 +00:00
|
|
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
|
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
|
|
|
4. Push to the branch (`git push origin my-new-feature`)
|
|
|
|
5. Create a new Pull Request
|
|
|
|
|
|
|
|
## Contributors
|
|
|
|
|
2024-08-19 15:58:02 +00:00
|
|
|
- [Roberto Alsina](https://github.com/ralsina) - creator and maintainer
|
2024-08-25 01:33:24 +00:00
|
|
|
|
2024-08-26 23:18:28 +00:00
|
|
|
## A port of what, and why "kind of"
|
2024-08-25 01:33:24 +00:00
|
|
|
|
|
|
|
Pygments is a staple of the Python ecosystem, and it's great.
|
|
|
|
It lets you highlight code in many languages, and it has many
|
|
|
|
themes. Chroma is "Pygments for Go", it's actually a port of
|
|
|
|
Pygments to Go, and it's great too.
|
|
|
|
|
|
|
|
I wanted that in Crystal, so I started this project. But I did
|
|
|
|
not read much of the Pygments code. Or much of Chroma's.
|
|
|
|
|
|
|
|
Chroma has taken most of the Pygments lexers and turned them into
|
|
|
|
XML descriptions. What I did was take those XML files from Chroma
|
|
|
|
and a pile of test cases from Pygments, and I slapped them together
|
|
|
|
until the tests passed and my code produced the same output as
|
|
|
|
Chroma. Think of it as [*extreme TDD*](https://ralsina.me/weblog/posts/tartrazine-reimplementing-pygments.html)
|
|
|
|
|
|
|
|
Currently the pass rate for tests in the supported languages
|
|
|
|
is `96.8%`, which is *not bad for a couple days hacking*.
|
|
|
|
|
|
|
|
This only covers the RegexLexers, which are the most common ones,
|
|
|
|
but it means the supported languages are a subset of Chroma's, which
|
|
|
|
is a subset of Pygments' and DelegatingLexers (useful for things like template languages)
|
|
|
|
|
2024-08-26 23:18:28 +00:00
|
|
|
Then performance was bad, so I hacked and hacked and made it significantly
|
|
|
|
[faster than chroma](https://ralsina.me/weblog/posts/a-tale-of-optimization.html)
|
|
|
|
which is fun.
|