Skip to content

Commit

Permalink
NPM release of Version 4 - Escaped URL support
Browse files Browse the repository at this point in the history
  • Loading branch information
drudru committed Feb 11, 2019
1 parent 6f5a1b8 commit a22b0d8
Show file tree
Hide file tree
Showing 6 changed files with 71 additions and 72 deletions.
121 changes: 53 additions & 68 deletions Readme.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# ansi_up.js

__ansi_up__ is a simple, easy to use library that provides a streaming API to
transform text containing
[ANSI color escape codes](http://en.wikipedia.org/wiki/ANSI_escape_code#Colors) into proper HTML.
It can also transform any text that looks like a URL into an HTML anchor tag.
__ansi_up__ is an easy to use library that transforms text containing
[ANSI color escape codes](http://en.wikipedia.org/wiki/ANSI_escape_code#Colors) into HTML.

This module is a single Javascript file with no dependencies. It is a UMD style module so it
can be utilized in a browser, in node.js (CommonJS), or with AMD (require.js). The source code
was compiled from TypeScript and its type description ships with the NPM. This code has been used in production since 2011 and is actively maintained.
This module is a single Javascript file with no dependencies.
It is "isomorphic" javascript. This is just another way of saying that
the ansi_up.js file will work in both the browser or node.js.
The js library is compiled from TypeScript and its type description ships with the NPM.
This code has been used in production since 2011 and is actively maintained.

For example, turn this terminal output:

Expand Down Expand Up @@ -74,7 +74,7 @@ More examples are in the 'examples' directory in the repo.

## Versions

* Version 4.0 - Re-architect code to support terminal linkify escapes.
* Version 4.0 - Re-architect code to support [https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda](terminal URL codes).
* Version 3.0 - now treats ANSI bold sequences as CSS font-weight:bold
* Version 2.0 - moved to a stateful, streaming version of the API
* Version 1.3 - was the last of the older, deprecated API.
Expand All @@ -83,109 +83,94 @@ More examples are in the 'examples' directory in the repo.

1. Use whatever module system to import the _ansi_up_ module.
2. Instantiate the object.
3. For every piece of input that arrives, call **ansi_to_html**.
3. For every piece of ansi escaped text string, call **ansi_to_html**.
4. Append the emitted HTML to the previous HTML already emitted.
5. DONE


## API Methods
## API Methods and Recommended Settings

In order to use _ansi_up_, you must Instantiate an object using your given module
system.
You only need the ansi_to_html method. The other properties listed below allow you to
override some of the escaping behaviour. You probably don't need to change these
from their default values.

#### ansi_to_html (txt)

This replaces ANSI terminal escape codes/sequences with SPAN tags that wrap the content.

This function only interprets ANSI SGR (Select Graphic Rendition) codes that can be represented in HTML. For example, cursor movement codes are ignored and hidden from output.
It is recommended that the HTML container that holds the span tags is styled with a monospace font.
A PRE tag would work just fine for this.
It is also recommended that the HTML container is styled with a black background.
See the examples, for more CSS theming.

The default style uses colors that are very close to the prescribed standard. The standard assumes that the text will have a black background. These colors are set as inline styles on the SPAN tags. Another option is to set 'use_classes: true' in the options argument. This will instead set classes on the spans so the colors can be set via CSS. The class names used are of the format ````ansi-*-fg/bg```` and ````ansi-bright-*-fg/bg```` where * is the colour name, i.e black/red/green/yellow/blue/magenta/cyan/white. See the examples directory for a complete CSS theme for these classes.

#### ansi_to_text (txt) DEPRECATED
#### ansi_to_html (txt)

This simply removes the ANSI escape codes from the stream.
No escaping is done.
This transforms ANSI terminal escape codes/sequences into SPAN tags that wrap and style the content.

#### linkify(txt) DEPRECATED
This method only interprets ANSI SGR (Select Graphic Rendition) codes or escaped URL codes.
For example, cursor movement codes are ignored and hidden from output.

** DEPRECATED ** - it turns out that this makes the code much more difficult to achieve while providing
a streaming API. I should do a write-up on this at some point. For now, I leave this documentation here.
If the developer knows what they are doing and want this functionality, they can find the code to do this
in the history of this repo.
This method also safely escapes any unsafe HTML characters.

This replaces any links in the text with anchor tags that display the link.
Only strings starting with 'http' or 'https', and surrounded by whitespace are
considered valid patterns.
You should only call this method if you can guarantee that the full URL
will be passed into ansi_to_html(). If the URL is split along a buffer
boundary, then the wrong URL will be 'linkified'.
The default style uses colors that are very close to the prescribed standard.
The standard assumes that the text will have a black background.
These colors are set as inline styles on the SPAN tags.
Another option is to set the 'use_classes' property to true'.
This will instead set classes on the spans so the colors can be set via CSS.
The class names used are of the format ````ansi-*-fg/bg```` and ````ansi-bright-*-fg/bg```` where * is the colour name, i.e black/red/green/yellow/blue/magenta/cyan/white.
See the examples directory for a complete CSS theme for these classes.

## Properties

#### escape_for_html
(default: true)

This does the minimum escaping of text to make it compliant with HTML.
In particular, the '&','<', and '>' characters are escaped.

In particular, the '&','<', and '>' characters are escaped. It is
** highly ** recommended that you do not set this to false. It will open
the door security vulnerabilities.

#### use_classes
(default: false)

This causes the SPAN tags to use class names for the color style instead
This causes the SPAN tags to use classes to style the SPAN tags instead
of specified RGB values.

## API Overview
#### url_whitelist
(default: { 'http':1, 'https':1 };

On a high level, _ansi_up_ takes a stream of text and transforms it proper HTML with colors.
It does this by buffering the data and performing multiple passes over the
stream. Each time it consumes data, it may or may not emit HTML. This HTML will always be
proper HTML.
This mapping is a whitelist of URI schemes that will be allowed to render HTML anchor tags.

Because this process requires buffering (ie. stateful), you must insantiate an _ansi_up_ object
in order to begin. Also, text may be received later that is styled by a previous.
## Buffering

The first pass converts characters that are unsafe for HTML into their equivalents. It will only
convert '&', '<', and '>' characters. This pass is optional, and is on by default.
In general, the ansi_to_html *should* emit HTML when invoked with a non-empty string.
The only exceptions are an incomplete ESC sequence or an incomplete escaped URL.
For those cases, the library will buffer the escape or the sequence for the escaped URL.

The second pass converts any ANSI color sequences to HTML spans. It does this by recognizing
what is termed as ANSI **SGR** codes. All ANSI sequences (SGR and non-SGR) are removed from the
output stream. The SGR codes create HTML **SPAN** tags to surround text that is styled by those
codes. If the ANSI sequence is incomplete, it will be held in _ansi_up_'s internal buffer
until new data is received to complete it.
The library is also stateful. If a color is set in a prior invocation, then it will
continue to emit that color in further invocations until the color/SGR attribute is changed.

The third and final pass transforms URLs to HTML anchors. This will also buffer output until a non URL
character is received. This pass is optional, and is off by default.
### Example of a Use Case

I have used this library to 'tail' a file.

### Recommended Style of Use
On a remote machine, I had process generating a log file.
I had a web server running on the same machine.
The server hosted a simple HTML page that used AJAX to poll an object with a range query.
Specifically I used an HTTP/1.1 GET request with RFC 7233 Range query.
The first range query would start at 0, but then progressively move forward after
new data was received.

There are two ways to stream this data to a web page. A push model or a pull model.

I have personally used a pull model to 'tail' a file.

In my 'pull' model, I had a process generating a log file on a remote machine.
I had a web server running on the same machine. I developed a simple page
that used AJAX to poll the web server periodically. Specifically I used an
HTTP/1.1 GET request with RFC 7233 Range query. The server would return
either range response.

I would then process each chunk received with _ansi_up_, and append the new
For each new chunk of data received, I would transform the data with _ansi_up_, and append the new
spans to the innerHTML of a PRE tag.


### UTF8 note

One last important note, _ansi_up_ takes its input in the form of a Javascript string.
These strings are UTF8. When you take the output of some program and send it to
Javascript, there will be buffering. Be sure to not send incomplete UTF8 sequences or
Javascript, there will be buffering. Be sure that you do not send incomplete UTF8 sequences.
Javascript will ignore or drop the sequence from the stream when it converts it to a
string.


_ansi_up_ should be called via the functions defined on the module. It is recommended that the HTML is rendered with a monospace font and black background. See the examples, for a basic theme as a CSS definition.
At the same, it also properly escapes HTML unsafe characters (&,<,>,etc.) into their proper HTML representation.


## Building

To build, a simple Makefile handles it all.
Expand Down
6 changes: 5 additions & 1 deletion ansi_up.js
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ var PacketKind;
})(PacketKind || (PacketKind = {}));
var AnsiUp = (function () {
function AnsiUp() {
this.VERSION = "4.0.1";
this.VERSION = "4.0.2";
this.setup_palettes();
this._use_classes = false;
this._escape_for_html = true;
Expand Down Expand Up @@ -192,6 +192,10 @@ var AnsiUp = (function () {
return pkt;
}
if (next_char == ']') {
if (len < 4) {
pkt.kind = PacketKind.Incomplete;
return pkt;
}
if ((this._buffer.charAt(2) != '8')
|| (this._buffer.charAt(3) != ';')) {
pkt.kind = PacketKind.ESC;
Expand Down
6 changes: 6 additions & 0 deletions ansi_up.ts
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,12 @@ class AnsiUp
// OSC CHECK
if (next_char == ']')
{
if (len < 4)
{
pkt.kind = PacketKind.Incomplete;
return pkt;
}

if ( (this._buffer.charAt(2) != '8')
|| (this._buffer.charAt(3) != ';') )
{
Expand Down
6 changes: 5 additions & 1 deletion dist/ansi_up.js.include
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ var PacketKind;
})(PacketKind || (PacketKind = {}));
var AnsiUp = (function () {
function AnsiUp() {
this.VERSION = "4.0.1";
this.VERSION = "4.0.2";
this.setup_palettes();
this._use_classes = false;
this._escape_for_html = true;
Expand Down Expand Up @@ -173,6 +173,10 @@ var AnsiUp = (function () {
return pkt;
}
if (next_char == ']') {
if (len < 4) {
pkt.kind = PacketKind.Incomplete;
return pkt;
}
if ((this._buffer.charAt(2) != '8')
|| (this._buffer.charAt(3) != ';')) {
pkt.kind = PacketKind.ESC;
Expand Down
Loading

0 comments on commit a22b0d8

Please sign in to comment.