go/chroma
1
0
Fork 0
mirror of https://github.com/alecthomas/chroma.git synced 2025-04-23 12:08:58 +02:00
Code Issues Releases Activity

docs: add import to README

Browse Source
This commit is contained in:
Alec Thomas 2024-02-05 09:04:11 +11:00
parent 39115ebe5c
commit f4788c0e9e
1 changed files with 38 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
README.md
View File

@ -8,36 +8,31 @@ highlighted HTML, ANSI-coloured text, etc.
Chroma is based heavily on [Pygments](http://pygments.org/), and includes Chroma is based heavily on [Pygments](http://pygments.org/), and includes
translators for Pygments lexers and styles. translators for Pygments lexers and styles.
<a id="markdown-table-of-contents" name="table-of-contents"></a>
## Table of Contents ## Table of Contents
<!-- TOC --> <!-- TOC -->
1. [Table of Contents](#table-of-contents) 1. [Supported languages](#supported-languages)
2. [Supported languages](#supported-languages) 2. [Try it](#try-it)
3. [Try it](#try-it) 3. [Using the library](#using-the-library)
4. [Using the library](#using-the-library)
1. [Quick start](#quick-start) 1. [Quick start](#quick-start)
2. [Identifying the language](#identifying-the-language) 2. [Identifying the language](#identifying-the-language)
3. [Formatting the output](#formatting-the-output) 3. [Formatting the output](#formatting-the-output)
4. [The HTML formatter](#the-html-formatter) 4. [The HTML formatter](#the-html-formatter)
5. [More detail](#more-detail) 4. [More detail](#more-detail)
1. [Lexers](#lexers) 1. [Lexers](#lexers)
2. [Formatters](#formatters) 2. [Formatters](#formatters)
3. [Styles](#styles) 3. [Styles](#styles)
6. [Command-line interface](#command-line-interface) 5. [Command-line interface](#command-line-interface)
7. [Testing lexers](#testing-lexers) 6. [Testing lexers](#testing-lexers)
8. [What's missing compared to Pygments?](#whats-missing-compared-to-pygments) 7. [What's missing compared to Pygments?](#whats-missing-compared-to-pygments)
<!-- /TOC --> <!-- /TOC -->
<a id="markdown-supported-languages" name="supported-languages"></a>
## Supported languages ## Supported languages
| Prefix | Language | | Prefix | Language |
| :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | :----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A | ABAP, ABNF, ActionScript, ActionScript 3, Ada, Agda, AL, Alloy, Angular2, ANTLR, ApacheConf, APL, AppleScript, ArangoDB AQL, Arduino, ArmAsm, AutoHotkey, AutoIt, Awk | | A | ABAP, ABNF, ActionScript, ActionScript 3, Ada, Agda, AL, Alloy, Angular2, ANTLR, ApacheConf, APL, AppleScript, ArangoDB AQL, Arduino, ArmAsm, AutoHotkey, AutoIt, Awk |
| B | Ballerina, Bash, Bash Session, Batchfile, BibTeX, Bicep, BlitzBasic, BNF, BQN, Brainfuck | | B | Ballerina, Bash, Bash Session, Batchfile, BibTeX, Bicep, BlitzBasic, BNF, BQN, Brainfuck |
| C | C, C#, C++, Caddyfile, Caddyfile Directives, Cap'n Proto, Cassandra CQL, Ceylon, CFEngine3, cfstatement, ChaiScript, Chapel, Cheetah, Clojure, CMake, COBOL, CoffeeScript, Common Lisp, Coq, Crystal, CSS, Cython | | C | C, C#, C++, Caddyfile, Caddyfile Directives, Cap'n Proto, Cassandra CQL, Ceylon, CFEngine3, cfstatement, ChaiScript, Chapel, Cheetah, Clojure, CMake, COBOL, CoffeeScript, Common Lisp, Coq, Crystal, CSS, Cython |
@ -67,16 +62,18 @@ translators for Pygments lexers and styles.
_I will attempt to keep this section up to date, but an authoritative list can be _I will attempt to keep this section up to date, but an authoritative list can be
displayed with `chroma --list`._ displayed with `chroma --list`._
<a id="markdown-try-it" name="try-it"></a>
## Try it ## Try it
Try out various languages and styles on the [Chroma Playground](https://swapoff.org/chroma/playground/). Try out various languages and styles on the [Chroma Playground](https://swapoff.org/chroma/playground/).
<a id="markdown-using-the-library" name="using-the-library"></a>
## Using the library ## Using the library
This is version 2 of Chroma, use the import path:
```go
import "github.com/alecthomas/chroma/v2"
```
Chroma, like Pygments, has the concepts of Chroma, like Pygments, has the concepts of
[lexers](https://github.com/alecthomas/chroma/tree/master/lexers), [lexers](https://github.com/alecthomas/chroma/tree/master/lexers),
[formatters](https://github.com/alecthomas/chroma/tree/master/formatters) and [formatters](https://github.com/alecthomas/chroma/tree/master/formatters) and
@ -95,8 +92,6 @@ In all cases, if a lexer, formatter or style can not be determined, `nil` will
be returned. In this situation you may want to default to the `Fallback` be returned. In this situation you may want to default to the `Fallback`
value in each respective package, which provides sane defaults. value in each respective package, which provides sane defaults.
<a id="markdown-quick-start" name="quick-start"></a>
### Quick start ### Quick start
A convenience function exists that can be used to simply format some source A convenience function exists that can be used to simply format some source
@ -106,8 +101,6 @@ text, without any effort:
err := quick.Highlight(os.Stdout, someSourceCode, "go", "html", "monokai") err := quick.Highlight(os.Stdout, someSourceCode, "go", "html", "monokai")
``` ```
<a id="markdown-identifying-the-language" name="identifying-the-language"></a>
### Identifying the language ### Identifying the language
To highlight code, you'll first have to identify what language the code is To highlight code, you'll first have to identify what language the code is
@ -147,8 +140,6 @@ token types into a single token:
lexer = chroma.Coalesce(lexer) lexer = chroma.Coalesce(lexer)
``` ```
<a id="markdown-formatting-the-output" name="formatting-the-output"></a>
### Formatting the output ### Formatting the output
Once a language is identified you will need to pick a formatter and a style (theme). Once a language is identified you will need to pick a formatter and a style (theme).
@ -177,8 +168,6 @@ And finally, format the tokens from the iterator:
err := formatter.Format(w, style, iterator) err := formatter.Format(w, style, iterator)
``` ```
<a id="markdown-the-html-formatter" name="the-html-formatter"></a>
### The HTML formatter ### The HTML formatter
By default the `html` registered formatter generates standalone HTML with By default the `html` registered formatter generates standalone HTML with
@ -203,12 +192,8 @@ formatter := html.New(html.WithClasses(true))
err := formatter.WriteCSS(w, style) err := formatter.WriteCSS(w, style)
``` ```
<a id="markdown-more-detail" name="more-detail"></a>
## More detail ## More detail
<a id="markdown-lexers" name="lexers"></a>
### Lexers ### Lexers
See the [Pygments documentation](http://pygments.org/docs/lexerdevelopment/) See the [Pygments documentation](http://pygments.org/docs/lexerdevelopment/)
@ -228,8 +213,6 @@ python3 _tools/pygments2chroma_xml.py \
See notes in [pygments-lexers.txt](https://github.com/alecthomas/chroma/blob/master/pygments-lexers.txt) See notes in [pygments-lexers.txt](https://github.com/alecthomas/chroma/blob/master/pygments-lexers.txt)
for a list of lexers, and notes on some of the issues importing them. for a list of lexers, and notes on some of the issues importing them.
<a id="markdown-formatters" name="formatters"></a>
### Formatters ### Formatters
Chroma supports HTML output, as well as terminal output in 8 colour, 256 colour, and true-colour. Chroma supports HTML output, as well as terminal output in 8 colour, 256 colour, and true-colour.
@ -237,8 +220,6 @@ Chroma supports HTML output, as well as terminal output in 8 colour, 256 colour,
A `noop` formatter is included that outputs the token text only, and a `tokens` A `noop` formatter is included that outputs the token text only, and a `tokens`
formatter outputs raw tokens. The latter is useful for debugging lexers. formatter outputs raw tokens. The latter is useful for debugging lexers.
<a id="markdown-styles" name="styles"></a>
### Styles ### Styles
Chroma styles are defined in XML. The style entries use the Chroma styles are defined in XML. The style entries use the
@ -262,8 +243,6 @@ Also, token types in a style file are hierarchical. For instance, when `CommentS
For a quick overview of the available styles and how they look, check out the [Chroma Style Gallery](https://xyproto.github.io/splash/docs/). For a quick overview of the available styles and how they look, check out the [Chroma Style Gallery](https://xyproto.github.io/splash/docs/).
<a id="markdown-command-line-interface" name="command-line-interface"></a>
## Command-line interface ## Command-line interface
A command-line interface to Chroma is included. A command-line interface to Chroma is included.
@ -288,10 +267,6 @@ on under the hood for easy integration with [lesspipe shipping with
Debian and derivatives](https://manpages.debian.org/lesspipe#USER_DEFINED_FILTERS); Debian and derivatives](https://manpages.debian.org/lesspipe#USER_DEFINED_FILTERS);
for that setup the `chroma` executable can be just symlinked to `~/.lessfilter`. for that setup the `chroma` executable can be just symlinked to `~/.lessfilter`.
<a id="markdown-whats-missing-compared-to-pygments" name="whats-missing-compared-to-pygments"></a>
<a id="markdown-testing-lexers" name="testing-lexers"></a>
## Testing lexers ## Testing lexers
If you edit some lexers and want to try it, open a shell in `cmd/chromad` and run: If you edit some lexers and want to try it, open a shell in `cmd/chromad` and run: