terminal

README

Terminal is a Go library for converting arbitrary shell output (with ANSI) into beautifully rendered HTML. See http://en.wikipedia.org/wiki/ANSI_escape_code for more information about ANSI Terminal Control Escape Sequences.

It provides a single command, terminal-to-html, that can be used to convert terminal output via STDIN, as well as via a simple web server.

Usage

Piping in terminal output via the command line:

cat fixtures/pikachu.sh.raw | terminal-to-html -preview > out.html

Posting terminal content via HTTP:

terminal-to-html -http=:6060 &
curl --data-binary "@fixtures/pikachu.sh.raw" http://localhost:6060/terminal > out.html

For coloring you can use the sample terminal.css stylesheet and wrap the output in an element with class term-container (e.g. <div class="term-container"><!-- terminal output --></div>).

iTerm2 Image support

Terminal has basic support for iTerm2 inline images. Only control sequences with inline=1 will be rendered and preserveAspectRatio is not supported.

URL-based images

Terminal also provides a way to refer to images from the internet rather than transmitted via ANSI. The format is similar to iTerm2 inline images but uses the escape code 1338:

1338;url=http://imgur.com/foo.gif;width=100%;height=50px;alt=My Image

You can use the provided image.sh to produce this escape sequence.

Links

Terminal can also render hyperlinks:

1339;url=https://google.com;content=Google Search

You can use the provided link.sh to produce this escape sequence.

Links which contain semicolons can be surrounded by either single or double quotation marks:

1339;url='https://example.com/link-with;semicolon?argument=something';content=Example

Installation

If you have Go installed you can simply run the following command to install the terminal-to-html command into $GOPATH/bin:

$ go install github.com/buildkite/terminal-to-html/v3/cmd/terminal-to-html

You can also just download the standalone binary from https://github.com/buildkite/terminal-to-html/releases

Developing

To get a bash prompt with all the go cross-compilation tools set up for you already:

$ docker build -t terminal . && docker run -it --rm -v $(pwd):/go/src/github.com/buildkite/terminal-to-html terminal bash

Benchmarking

Run go test -bench . to see raw Go performance. The npm test is the focus: this best represents the kind of use cases the original code was developed against.

Contributing

1. Fork it
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

Licence

Copyright (c) 2019 Keith Pitt, Tim Lucas, Michael Pearson

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Overview

Package terminal converts ANSI input to HTML output.

The generated HTML needs to be used with the stylesheet at https://raw.githubusercontent.com/buildkite/terminal-to-html/main/assets/terminal.css and wrapped in a term-container div.

You can call this library from the command line with terminal-to-html: GO111MODULE=on go install github.com/buildkite/terminal-to-html/v3/cmd/terminal-to-html

Index

• Constants
• func Render(input []byte) []byte
• func Version() string
• type Screen
  • func (s *Screen) AsHTML() []byte
  • func (s *Screen) Parse(ansi []byte)

Constants

const (
	ELEMENT_ITERM_IMAGE = iota
	ELEMENT_IMAGE
	ELEMENT_LINK
)

const (
	MODE_NORMAL  = iota
	MODE_ESCAPE  = iota
	MODE_CONTROL = iota
	MODE_OSC     = iota
	MODE_CHARSET = iota
	MODE_APC     = iota
)

const (
	COLOR_NORMAL        = iota
	COLOR_GOT_38_NEED_5 = iota
	COLOR_GOT_48_NEED_5 = iota
	COLOR_GOT_38        = iota
	COLOR_GOT_48        = iota
)

Functions

func Render

func Render(input []byte) []byte

Render converts ANSI to HTML and returns the result.

func Version

func Version() string

Types

type Screen

type Screen struct {

	// Optional maximum amount of backscroll to retain in the buffer.
	// Setting to 0 or negative makes the screen buffer unlimited.
	MaxLines int

	// Optional callback. If not nil, as each line is scrolled out of the top of
	// the buffer, this func is called with the HTML.
	ScrollOutFunc func(lineHTML string)

	// Processing statistics
	LinesScrolledOut int // count of lines that scrolled off the top
	CursorUpOOB      int // count of times ESC [A or ESC [F tried to move y < 0
	CursorBackOOB    int // count of times ESC [D tried to move x < 0
	// contains filtered or unexported fields
}

A terminal 'screen'. Current cursor position, cursor style, and characters

func (*Screen) AsHTML

func (s *Screen) AsHTML() []byte

func (*Screen) Parse

func (s *Screen) Parse(ansi []byte)

Parse ANSI input, populate our screen buffer with nodes