tartrazine/README.md

90 lines
2.7 KiB
Markdown
Raw Normal View History

2024-08-05 00:44:23 +00:00
# TARTRAZINE
2024-08-02 20:03:39 +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
[Crystal](https://crystal-lang.org/). Kind of.
2024-08-14 16:25:20 +00:00
The CLI tool can be used to highlight many things in many styles.
2024-08-04 23:36:35 +00:00
# A port of what? Why "kind of"?
2024-08-14 16:25:20 +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.
2024-08-04 23:36:35 +00:00
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*.
2024-08-05 00:44:23 +00:00
Currently the pass rate for tests in the supported languages
2024-08-05 00:38:00 +00:00
is `96.8%`, which is *not bad for a couple days hacking*.
2024-08-04 23:36:35 +00:00
This only covers the RegexLexers, which are the most common ones,
2024-08-05 00:44:23 +00:00
but it means the supported languages are a subset of Chroma's, which
2024-08-04 23:36:35 +00:00
is a subset of Pygments'.
2024-08-23 17:49:01 +00:00
Currently Tartrazine supports ... 248 languages.
2024-08-02 20:03:39 +00:00
2024-08-11 14:54:00 +00:00
It has 331 themes (63 from Chroma, the rest are base16 themes via
2024-08-06 21:31:29 +00:00
[Sixteen](https://github.com/ralsina/sixteen)
2024-08-02 20:03:39 +00:00
## Installation
2024-08-11 14:54:00 +00:00
From prebuilt binaries:
Each release provides statically-linked binaries that should
work on any Linux. Get them from the [releases page](https://github.com/ralsina/tartrazine/releases) and put them in your PATH.
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
Show a syntax highlighted version of a C source file in your terminal:
```shell
$ tartrazine whatever.c -l c -t catppuccin-macchiato --line-numbers -f terminal
```
2024-08-23 17:46:26 +00:00
Generate a standalone HTML file from a C source file with the syntax highlighted:
2024-08-16 17:03:05 +00:00
```shell
$ tartrazine whatever.c -l c -t catppuccin-macchiato --line-numbers \
--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