termlib.js home | multiple terminals | parser | faq | documentation | samples
ANSI-Mapping Sample
 
> open terminal  
 
 
(c) mass:werk,
N. Landsteiner 2005-2010
http://www.masswerk.at

ANSI-Mapping Sample Page
 

With version 1.51 termlib.js comes with basic support of ANSI-escape sequences
This option might be especially usefull with output of any server-generated texts.

ANSI-escape sequences are of the form CSI parameter letter, where

  • CSI is a sequence of ESC (0x19) and "[" or the single char 0x9b
  • parameters a single number, a list of numbers separated by ";", or empty
  • letter a letter signifying the command (currently only "m" supported)

Supported is a subclass of SGR (Select Graphic Rendition) codes (letter "m"), all other sequences are deleted from output.

To enable ANSI-mapping for the write() method set the config-flag mapANSI to true.
As the the color code for black is rendered as the normal foreground color by default, you may also want to set the config-flag ANSItrueBlack to true in order to render code CSI 30 m (set foreground color to black) as truely black.

Example:

   var myterm = new Terminal(
      {
         mapANSI: true,       // enable ANSI mapping
         ANSItrueBlack: true  // force black in stead of renderung as fg color
      }
    );
 
    myterm.open();

You may also turn ANSI-mapping on and off on the fly by directly accessing the property mapANSI of your Terminal instance.

Example:

   myterm.mapANSI = true;
   myterm.write( ANSIencodedText, true ); // output text with "more"-option
   myterm.mapANSI = false; // resume to normal

Warning: As the method write() uses the percent sign (%) as an escape character, you would probably want to escape any "%" in any server-generated text with "%%" before output. You may use the method escapeMarkup() for this:

Example:

   escapedText = myterm.escapeMarkup( ANSIencodedText );
   myterm.write( escapedText, true ); // output text with "more"-option

See the example at the bottom of this page for a complete example of a remote text reader with aNSI-support and escaping of internal markup.

 

Supported SGR Codes:

code  effect  notes
0 Reset / Normal default rendition (implementation-defined), cancels the effect of any preceding occurrence of SGR [ECMA-48]
1 Intensity: Bold rendered as italics by default,
see note on style 16
3 Italics: on
4 Underline: Single
7 Negative Image reverse
9 Crossed-out characters still legible but marked as to be deleted
21 Underline: Double rendered as simple underline
22 Intensity: Normal not bold
23 Italics: off
24 Underline: off both single and double
27 Positive Image reverse off
29 not crossed out
30-39 Set foreground color,
normal intensity
3x, see color table
90-99 Set foreground color,
high intensity
9x, see color table

Color Table

code  name  internal color  notes
30 black 0 default foreground color, or
1 with option ANSItrueBlack = true
31 red 10
32 green 11
33 yellow 12
34 blue 13
35 magenta 14
36 cyan 15
37 white #999 effect: light grey
39 reset 0
90 bright black 9 effect: dark grey
91 bright red 2
92 bright green 3
93 bright yellow 4
94 bright blue 5
95 bright magenta 6
96 bright cyan 7
97 bright white 8
99 reset 0 (not a standard)

As most colors (but 93 "normal white", hard-coded to "#999") are internally matched to color-codes, you may configure the representation of ANSI-colors.

Example:

   // assign ANSI-code 93 (bright red) = internal color code 2:
   TermGlobals.setColor( "2", "#880000" );
   

Note on the Representation of "bold"

As bold is not sane for display on default, code 2 (bold) is matched to the internal style "b", style code 16 and rendered as italics by default.

To change the representation of this style you may use the static method TermGlobals.assignStyle() as in the following example:

   // overwrite default rendering by defining style #16 ('b'):

   TermGlobals.assignStyle(
      16,      // style code
      "b",     // markup character
      "<b>",   // html start string
      "</b>"   // html end string
   );
   

Be sure to have read the section on bold fonts and CSS-letter-spacing in the Style Settings Sample Page, when applying this.

 

All ANSI-code-to-markup-mapping is defined in the static object Terminal.prototype.globals.ANIS_SGR_codes (or short: TermGlobals.ANIS_SGR_codes).

 

Example: Remote Text Reader

Here is a complete example of how to receive a text from a server and display it using ANSI-sequences:

   // *** external file reader with ANSI support ***

   var myterm;
   
   var helpPage = [
      "*** Remote Page Sample ***",
      "type 'read <filename>' to load and display a file from the server.",
      "type 'exit' to quit.",
      " "
   ];

   function openTerminal() {
       if (!myterm || myterm.closed) {
          myterm = new Terminal(
             {
                mapANSI: true,
                handler: commandHandler,
                initHandler: initHandler
             }
          );
          myterm.open();
       }
   }

   function initHandler() {
      this.write( helpPage );
      this.prompt();
   }

   function commandHandler() {
      this.newLine();
      this.lineBuffer = this.lineBuffer.replace(/^\s+/, '');
      var argv = this.lineBuffer.split(/\s+/);
      var cmd = argv[0];
      switch (cmd) {
         case 'read':
            if (argv.length == 2) {
               // cmd 'read' with filename: load file from server
               // return without prompt, response handled in serverCallback
               var filename = argv[1];
               this.send(
                  {
                     url: filename,
                     method: 'get',
                     callback: serverCallback
                  }
               );
               return;
            }
            else {
               // wrong number of arguments
               this.type( 'Usage: read <filename>' );
            }
            break;
         case 'help':
            this.clear();
            this. write( helpPage );
            break;
         case 'exit':
            this.close();
            return;
         default:
            if (cmd) this.type( 'Unkmown command.' );
      }
      this.prompt;
   }

   function serverCallback() {
      var response=this.socket;
      if (response.success) {
         // escape any markup (%) and write it using the more-option
         // ANSI-translation is done automatically (see config-flag)
         // return without prompt, prompt is generated by write-more

         var escapedText = this.escapeMarkup( response.responseText );
         this.write( escapedText, true );
         return;
      }
      else if (response.status == 404) {
         this.write( 'No such file.' );
      }
      else {
         var message = 'Request failed: '
           + response.status + ' ' + response.statusText;
         if (response.errno) message +=  '\n' + response.errstring;
         this.write( message );
      }
      this.prompt();
   }

See also: Colors Sample Page, Socket Sample Page, Style Settings Sample Page.