NPM release of Version 4 - Escaped URL support

Readme.md

@@ -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:
 
@@ -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.
@@ -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.

ansi_up.js

@@ -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;
@@ -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;

ansi_up.ts

@@ -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) != ';') )
                 {

dist/ansi_up.js.include

@@ -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;
@@ -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;