colorit

README

colorit

colorit is a tiny Go helper that adds optional syntax highlighting for your CLI tools output by calling existing external highlighter tools (e.g. bat, chroma, etc). It keeps your tool small - if no highlighter is available in working env it simply prints plain text.

Install

go get github.com/asciimoth/colorit

Quick example

package main

import (
	"os"

	"github.com/asciimoth/colorit"
)

const help = `...` // your help text

func main() {
	// text, syntax name, destination writer
	// If output is not a TTY or no highlighter is found, text is left unchanged.
	colorit.HighlightTo(help, "help", os.Stdout)
}

Behavior

• Attempts to highlight using available external highlighter CLI tools.
• If no configured highlighter is present or the output is not a terminal, the original text is written unchanged.
• Keeps highlighting optional - users only get colored output if they have a supported highlighter installed.

Configuration

Set GO_COLORIT env var to control which highlighters are tried and in which order. Use a semicolon-separated list, for example:

GO_COLORIT="chroma;rich;bat"

Set GO_COLORIT=disable to force no highlighting.

Supported tools

• bat
• pygmentize
• rich-cli
• chroma

Contributing

If you know other standalone highlighter CLI tools that could be integrated, please open an issue or PR.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Documentation

Overview

Package colorit implements syntax highlighting for text using external cli tools.

Index

• func Highlight(text, syntax string, highlighters []Highlighter) string
• func HighlightStr(text, syntax string) string
• func HighlightTo(text, syntax string, out io.Writer) error
• type BatHighlighter
  • func (p BatHighlighter) Highlight(text, syntax string) string
  • func (p BatHighlighter) Name() string
• type ChromaHighlighter
  • func (p ChromaHighlighter) Highlight(text, syntax string) string
  • func (p ChromaHighlighter) Name() string
• type Highlighter
  • func DefaultHighlighters() []Highlighter
  • func FilterHighliters(filter string, src []Highlighter) []Highlighter
• type PygmentsHighlighter
  • func (p PygmentsHighlighter) Highlight(text, syntax string) string
  • func (p PygmentsHighlighter) Name() string
• type RichHighlighter
  • func (p RichHighlighter) Highlight(text, syntax string) string
  • func (p RichHighlighter) Name() string

Functions

func Highlight

func Highlight(text, syntax string, highlighters []Highlighter) string

Highlight tries each of provided highlighters until one of them successfully, highlights provided text with provided syntax or just returns original text if there is no suitable highlighters.

func HighlightStr

func HighlightStr(text, syntax string) string

HighlightStr highlights text for syntax using default highlighters slice.

func HighlightTo

func HighlightTo(text, syntax string, out io.Writer) error

HighlightTo highlights text for syntax using default highlighters slice and writes it to out if out is a TTY else writes original text.

Types

type BatHighlighter

type BatHighlighter struct{}

BatHighlighter implement syntax highlighting with bat cli tool.

func (BatHighlighter) Highlight

func (p BatHighlighter) Highlight(text, syntax string) string

Highlight returns text highlighted for syntax or "" if faled.

func (BatHighlighter) Name

func (p BatHighlighter) Name() string

Name returns "bat".

type ChromaHighlighter

type ChromaHighlighter struct{}

ChromaHighlighter implement syntax highlighting with chroma cli tool.

func (ChromaHighlighter) Highlight

func (p ChromaHighlighter) Highlight(text, syntax string) string

Highlight returns text highlighted for syntax or "" if faled.

func (ChromaHighlighter) Name

func (p ChromaHighlighter) Name() string

Name returns "chroma".

type Highlighter

type Highlighter interface {
	// Name should not return ""
	Name() string
	// If Highlight returns same text or "" it means that
	// it cannot highlight it for given syntax
	Highlight(text, syntax string) string
}

Highlighter implementation provides logic for syntax highlighting with ANSI Escape codes.

func DefaultHighlighters

func DefaultHighlighters() []Highlighter

DefaultHighlighters returns slice of all builtin highlighters filtered with filter string from GO_COLORIT env var.

func FilterHighliters

func FilterHighliters(filter string, src []Highlighter) []Highlighter

FilterHighliters filters and reorders highliters against filter string that contains names of highlighters separated by ";": "a;b;c". If filter string is "", returns all highlighters from src. It returns new slice.

type PygmentsHighlighter

type PygmentsHighlighter struct{}

PygmentsHighlighter implement syntax highlighting with pygmentize cli tool.

func (PygmentsHighlighter) Highlight

func (p PygmentsHighlighter) Highlight(text, syntax string) string

Highlight returns text highlighted for syntax or "" if faled.

func (PygmentsHighlighter) Name

func (p PygmentsHighlighter) Name() string

Name returns "pygments".

type RichHighlighter

type RichHighlighter struct{}

RichHighlighter implement syntax highlighting with rich cli tool.

func (RichHighlighter) Highlight

func (p RichHighlighter) Highlight(text, syntax string) string

Highlight returns text highlighted for syntax or "" if faled.

func (RichHighlighter) Name

func (p RichHighlighter) Name() string

Name returns "rich".