From f4788c0e9e139b7ac22e78fda970b5a11a85cb4e Mon Sep 17 00:00:00 2001 From: Alec Thomas Date: Mon, 5 Feb 2024 09:04:11 +1100 Subject: [PATCH] docs: add import to README --- README.md | 101 ++++++++++++++++++++---------------------------------- 1 file changed, 38 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 48965c4fa..775d3af2f 100644 --- a/README.md +++ b/README.md @@ -8,75 +8,72 @@ highlighted HTML, ANSI-coloured text, etc. Chroma is based heavily on [Pygments](http://pygments.org/), and includes translators for Pygments lexers and styles. - - ## Table of Contents -1. [Table of Contents](#table-of-contents) -2. [Supported languages](#supported-languages) -3. [Try it](#try-it) -4. [Using the library](#using-the-library) +1. [Supported languages](#supported-languages) +2. [Try it](#try-it) +3. [Using the library](#using-the-library) 1. [Quick start](#quick-start) 2. [Identifying the language](#identifying-the-language) 3. [Formatting the output](#formatting-the-output) 4. [The HTML formatter](#the-html-formatter) -5. [More detail](#more-detail) +4. [More detail](#more-detail) 1. [Lexers](#lexers) 2. [Formatters](#formatters) 3. [Styles](#styles) -6. [Command-line interface](#command-line-interface) -7. [Testing lexers](#testing-lexers) -8. [What's missing compared to Pygments?](#whats-missing-compared-to-pygments) +5. [Command-line interface](#command-line-interface) +6. [Testing lexers](#testing-lexers) +7. [What's missing compared to Pygments?](#whats-missing-compared-to-pygments) - - ## Supported languages -| Prefix | Language | -| :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| 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 | -| 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 | -| D | D, Dart, Dax, Desktop Entry, Diff, Django/Jinja, dns, Docker, DTD, Dylan | -| E | EBNF, Elixir, Elm, EmacsLisp, Erlang | -| F | Factor, Fennel, Fish, Forth, Fortran, FortranFixed, FSharp | -| G | GAS, GDScript, Genshi, Genshi HTML, Genshi Text, Gherkin, GLSL, Gnuplot, Go, Go HTML Template, Go Text Template, GraphQL, Groff, Groovy | -| H | Handlebars, Hare, Haskell, Haxe, HCL, Hexdump, HLB, HLSL, HolyC, HTML, HTTP, Hy | -| I | Idris, Igor, INI, Io, ISCdhcpd | -| J | J, Java, JavaScript, JSON, Julia, Jungle | -| K | Kotlin | -| L | Lighttpd configuration file, LLVM, Lua | -| M | Makefile, Mako, markdown, Mason, Materialize SQL dialect, Mathematica, Matlab, mcfunction, Meson, Metal, MiniZinc, MLIR, Modula-2, MonkeyC, MorrowindScript, Myghty, MySQL | -| N | NASM, Natural, Newspeak, Nginx configuration file, Nim, Nix | -| O | Objective-C, OCaml, Octave, Odin, OnesEnterprise, OpenEdge ABL, OpenSCAD, Org Mode | +| Prefix | Language | +| :----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 | +| 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 | +| D | D, Dart, Dax, Desktop Entry, Diff, Django/Jinja, dns, Docker, DTD, Dylan | +| E | EBNF, Elixir, Elm, EmacsLisp, Erlang | +| F | Factor, Fennel, Fish, Forth, Fortran, FortranFixed, FSharp | +| G | GAS, GDScript, Genshi, Genshi HTML, Genshi Text, Gherkin, GLSL, Gnuplot, Go, Go HTML Template, Go Text Template, GraphQL, Groff, Groovy | +| H | Handlebars, Hare, Haskell, Haxe, HCL, Hexdump, HLB, HLSL, HolyC, HTML, HTTP, Hy | +| I | Idris, Igor, INI, Io, ISCdhcpd | +| J | J, Java, JavaScript, JSON, Julia, Jungle | +| K | Kotlin | +| L | Lighttpd configuration file, LLVM, Lua | +| M | Makefile, Mako, markdown, Mason, Materialize SQL dialect, Mathematica, Matlab, mcfunction, Meson, Metal, MiniZinc, MLIR, Modula-2, MonkeyC, MorrowindScript, Myghty, MySQL | +| N | NASM, Natural, Newspeak, Nginx configuration file, Nim, Nix | +| O | Objective-C, OCaml, Octave, Odin, OnesEnterprise, OpenEdge ABL, OpenSCAD, Org Mode | | P | PacmanConf, Perl, PHP, PHTML, Pig, PkgConfig, PL/pgSQL, plaintext, Plutus Core, Pony, PostgreSQL SQL dialect, PostScript, POVRay, PowerQuery, PowerShell, Prolog, PromQL, Promela, properties, Protocol Buffer, PRQL, PSL, Puppet, Python, Python 2 | -| Q | QBasic, QML | +| Q | QBasic, QML | | R | R, Racket, Ragel, Raku, react, ReasonML, reg, Rego, reStructuredText, Rexx, RPMSpec, Ruby, Rust | -| S | SAS, Sass, Scala, Scheme, Scilab, SCSS, Sed, Sieve, Smali, Smalltalk, Smarty, Snobol, Solidity, SourcePawn, SPARQL, SQL, SquidConf, Standard ML, stas, Stylus, Svelte, Swift, SYSTEMD, systemverilog | -| T | TableGen, Tal, TASM, Tcl, Tcsh, Termcap, Terminfo, Terraform, TeX, Thrift, TOML, TradingView, Transact-SQL, Turing, Turtle, Twig, TypeScript, TypoScript, TypoScriptCssData, TypoScriptHtmlData | -| V | V, V shell, Vala, VB.net, verilog, VHDL, VHS, VimL, vue | -| W | WDTE, WebGPU Shading Language, Whiley | -| X | XML, Xorg | -| Y | YAML, YANG | -| Z | Z80 Assembly, Zed, Zig | +| S | SAS, Sass, Scala, Scheme, Scilab, SCSS, Sed, Sieve, Smali, Smalltalk, Smarty, Snobol, Solidity, SourcePawn, SPARQL, SQL, SquidConf, Standard ML, stas, Stylus, Svelte, Swift, SYSTEMD, systemverilog | +| T | TableGen, Tal, TASM, Tcl, Tcsh, Termcap, Terminfo, Terraform, TeX, Thrift, TOML, TradingView, Transact-SQL, Turing, Turtle, Twig, TypeScript, TypoScript, TypoScriptCssData, TypoScriptHtmlData | +| V | V, V shell, Vala, VB.net, verilog, VHDL, VHS, VimL, vue | +| W | WDTE, WebGPU Shading Language, Whiley | +| X | XML, Xorg | +| Y | YAML, YANG | +| Z | Z80 Assembly, Zed, Zig | _I will attempt to keep this section up to date, but an authoritative list can be displayed with `chroma --list`._ - - ## Try it Try out various languages and styles on the [Chroma Playground](https://swapoff.org/chroma/playground/). - - ## 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 [lexers](https://github.com/alecthomas/chroma/tree/master/lexers), [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` value in each respective package, which provides sane defaults. - - ### Quick start 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") ``` - - ### Identifying the language 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) ``` - - ### Formatting the output 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) ``` - - ### The HTML formatter 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) ``` - - ## More detail - - ### Lexers 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) for a list of lexers, and notes on some of the issues importing them. - - ### Formatters 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` formatter outputs raw tokens. The latter is useful for debugging lexers. - - ### Styles 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/). - - ## Command-line interface 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); for that setup the `chroma` executable can be just symlinked to `~/.lessfilter`. - - - - ## Testing lexers If you edit some lexers and want to try it, open a shell in `cmd/chromad` and run: