Mark version 0.30

Introduce bufferred attaching to websocket

README.md

@@ -1,14 +1,19 @@
-# xterm.js
+# xterm.js — xterm, in the browser
 
-xterm, in the browser.
+Xterm.js is a full xterm clone, written completely in JavaScript.
+
+Xterm.js supplies a modular, event-based interface that lets developers build addons and themes that augment  the experience of running a fully-featured terminal inside the browser.
+
+Xterm.js serves as foundation for the terminal found at www.sourcelair.com.
+
+![xterm.js screenshot](docs/screenshot.png)
 
 ### Contribution and License Agreement
 
-If you contribute code to this project, you are implicitly allowing your code
-to be distributed under the MIT license. You are also implicitly verifying that
-all code is your original work.
+If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license. You are also implicitly verifying that all code is your original work.
 
 ## License
 
-Copyright (c) 2014, sourceLair Limited (www.sourcelair.com) (MIT License)
+Copyright (c) 2014-2015, SourceLair, Ltd (www.sourcelair.com) (MIT License)
+
 Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)

addons/attach/attach.js

@@ -1,23 +1,95 @@
 /*
  * Implements the attach method, that
  * attaches the terminal to a WebSocket stream.
- * 
+ *
  * The bidirectional argument indicates, whether the terminal should
  * send data to the socket as well and is true, by default.
  */
-Terminal.prototype.attach = function (socket, bidirectional) {
-  var term = this;
-  
-  bidirectional = (typeof bidirectional == 'undefined') ? true : bidirectional;
-  this.socket = socket;
-  
-  socket.addEventListener('message', function (ev) {
-    term.write(ev.data);
-  });
-  
-  if (bidirectional) {
-    this.on('data', function (data) {
-      socket.send(data);
-    });
-  }
-}
+
+(function (attach) {
+    if (typeof define == 'function') {
+        /*
+         * Require.js is available
+         */
+        define(['../../src/xterm'], attach);
+    } else {
+        /*
+         * Plain browser environment
+         */
+        attach(this.Xterm);
+    }
+})(function (Xterm) {
+    /**
+     * Attaches the current terminal to the given socket
+     *
+     * @param {WebSocket} socket - The socket to attach the current terminal
+     * @param {boolean} bidirectional - Whether the terminal should send data
+     *                                  to the socket as well
+     * @param {boolean} buffered - Whether the rendering of incoming data
+     *                             should happen instantly or at a maximum
+     *                             frequency of 1 rendering per 10ms
+     */
+    Xterm.prototype.attach = function (socket, bidirectional, buffered) {
+        var term = this;
+
+        bidirectional = (typeof bidirectional == 'undefined') ? true : bidirectional;
+        this.socket = socket;
+
+        term._flushBuffer = function () {
+            term.write(term._attachSocketBuffer);
+            term._attachSocketBuffer = null;
+            clearTimeout(term._attachSocketBufferTimer);
+            term._attachSocketBufferTimer = null;
+        };
+
+        term._pushToBuffer = function (data) {
+            if (term._attachSocketBuffer) {
+                term._attachSocketBuffer += data;
+            } else {
+                term._attachSocketBuffer = data;
+                setTimeout(term._flushBuffer, 10);
+            }
+        };
+
+        term._getMessage = function (ev) {
+            if (buffered) {
+                term._pushToBuffer(ev.data);
+            } else {
+                term.write(ev.data);
+            }
+        };
+
+        term._sendData = function (data) {
+            socket.send(data);
+        };
+
+        socket.addEventListener('message', term._getMessage);
+
+        if (bidirectional) {
+            this.on('data', term._sendData);
+        }
+
+        socket.addEventListener('close', term.detach.bind(term, socket));
+        socket.addEventListener('error', term.detach.bind(term, socket));
+    };
+
+    /**
+     * Detaches the current terminal from the given socket
+     *
+     * @param {WebSocket} socket - The socket from which to detach the current
+     *                             terminal
+     */
+    Xterm.prototype.detach = function (socket) {
+        var term = this;
+
+        term.off('data', term._sendData);
+
+        socket = (typeof socket == 'undefined') ? term.socket : socket;
+
+        if (socket) {
+            socket.removeEventListener('message', term._getMessage);
+        }
+
+        delete term.socket;
+    };
+});

addons/attach/index.html

@@ -5,8 +5,61 @@
     <link rel="stylesheet" href="../../demo/style.css" />
     <script src="../../src/xterm.js"></script>
     <script src="attach.js"></script>
+    <style>
+        body {
+            color: #111;
+        }
+        
+        h1, h2 {
+            color: #444;
+            border-bottom: 1px solid #ddd;
+            text-align: left;
+        }
+        
+        form {
+            margin-bottom: 32px;
+        }
+        
+        input, button {
+            line-height: 22px;
+            font-size: 16px;
+            display: inline-block;
+            border-radius: 2px;
+            border: 1px solid #ccc;
+        }
+        
+        input {
+            height: 22px;
+            padding-left: 4px;
+            padding-right: 4px;
+        }
+        
+        button {
+            height: 28px;
+            background-color: #ccc;
+            cursor: pointer;
+            color: #333;
+        }
+        
+        .container {
+            max-width: 900px;
+            margin: 0 auto;
+        }
+    </style>
   </head>
   <body>
+      <div class="container">
+          
+    <h1>
+        xterm.js: socket attach
+    </h1>
+          <p>
+              Attach the terminal to a WebSocket terminal stream with ease. Perfect for attaching to your
+              Docker containers.
+          </p>
+          <h2>
+              Socket information
+          </h2>
     <form id="socket-form">
       <input id="socket-url"
              type="text"
@@ -17,6 +70,8 @@
       </button>
     </form>
     <div id="terminal-container"></div>
+          
+      </div>
     <script>
       var term = new Terminal(),
           container = document.getElementById('terminal-container'),

addons/fit/fit.js

@@ -0,0 +1,74 @@
+/*
+ *  Fit terminal columns and rows to the dimensions of its
+ *  DOM element.
+ *
+ *  Approach:
+ *    - Rows: Truncate the division of the terminal parent element height
+ *            by the terminal row height
+ *
+ *    - Columns: Truncate the division of the terminal parent element width by
+ *               the terminal character width (apply display: inline at the
+ *               terminal row and truncate its width with the current number
+ *               of columns)
+ */
+(function (fit) {
+    if (typeof define == 'function') {
+        /*
+         * Require.js is available
+         */
+        define(['../../src/xterm'], fit);
+    } else {
+        /*
+         * Plain browser environment
+         */ 
+        fit(this.Xterm);
+    }
+})(function (Xterm) {
+    Xterm.prototype.proposeGeometry = function () {
+        var parentElementStyle = window.getComputedStyle(this.element.parentElement),
+            parentElementHeight = parseInt(parentElementStyle.getPropertyValue('height')),
+            parentElementWidth = parseInt(parentElementStyle.getPropertyValue('width')),
+            elementStyle = window.getComputedStyle(this.element),
+            elementPaddingVer = parseInt(elementStyle.getPropertyValue('padding-top')) + parseInt(elementStyle.getPropertyValue('padding-bottom')),
+            elementPaddingHor = parseInt(elementStyle.getPropertyValue('padding-right')) + parseInt(elementStyle.getPropertyValue('padding-left')),
+            availableHeight = parentElementHeight - elementPaddingVer,
+            availableWidth = parentElementWidth - elementPaddingHor,
+            container = this.rowContainer,
+            subjectRow = this.rowContainer.firstElementChild,
+            contentBuffer = subjectRow.innerHTML,
+            characterHeight,
+            rows,
+            characterWidth,
+            cols,
+            geometry;
+
+        subjectRow.style.display = 'inline';
+        subjectRow.innerHTML = 'W'; // Common character for measuring width, although on monospace
+        characterWidth = parseInt(subjectRow.offsetWidth);
+        subjectRow.style.display = ''; // Revert style before calculating height, since they differ.
+        characterHeight = parseInt(subjectRow.offsetHeight);
+        subjectRow.innerHTML = contentBuffer;
+
+        rows = parseInt(availableHeight / characterHeight);
+        /*
+         * The following hack takes place in order to get "fit" work properly
+         * in Mozilla Firefox.
+         * Most probably, because of a dimension calculation bug, Firefox
+         * calculates the width to be 1px less than it is actually drawn on
+         * screen.
+         */
+        if (navigator.userAgent.match(/Firefox/)) {
+            characterWidth++;
+        }
+        cols = parseInt(availableWidth / characterWidth);
+
+        geometry = {cols: cols, rows: rows};
+        return geometry;
+    };
+
+    Xterm.prototype.fit = function () {
+        var geometry = this.proposeGeometry();
+
+        this.resize(geometry.cols, geometry.rows);
+    };
+});

addons/fullscreen/fullscreen.js

@@ -10,16 +10,30 @@
  * If the `fullscreen` argument has not been supplied, the
  * fullscreen mode is being toggled.
  */
-Terminal.prototype.toggleFullscreen = function (fullscreen) {
-  var fn;
-  
-  if (typeof fullscreen == 'undefined') {
-    fn = (this.element.classList.contains('fullscreen')) ? 'remove' : 'add';
-  } else if (!fullscreen) {
-    fn = 'remove';
-  } else {
-    fn = 'add';
-  }
-  
-  this.element.classList[fn]('fullscreen');
-}
+(function (fullscreen) {
+    if (typeof define == 'function') {
+        /*
+         * Require.js is available
+         */
+        define(['../../src/xterm'], fullscreen);
+    } else {
+        /*
+         * Plain browser environment
+         */ 
+        fullscreen(this.Xterm);
+    }
+})(function (Xterm) {
+    Xterm.prototype.toggleFullscreen = function (fullscreen) {
+      var fn;
+
+      if (typeof fullscreen == 'undefined') {
+        fn = (this.element.classList.contains('fullscreen')) ? 'remove' : 'add';
+      } else if (!fullscreen) {
+        fn = 'remove';
+      } else {
+        fn = 'add';
+      }
+
+      this.element.classList[fn]('fullscreen');
+    };
+});

addons/linkify/index.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<html>
+    <head>
+        <link rel="stylesheet" href="../../src/xterm.css" />
+        <link rel="stylesheet" href="../../demo/style.css" />
+        <script src="../../src/xterm.js"></script>
+        <script src="linkify.js"></script>
+        <style>
+            body {
+                color: #111;
+            }
+
+            #terminal-container {
+                max-width: 900px;
+                margin: 0 auto;
+            }
+
+            #terminal-container a {
+				color: #fff;
+            }
+        </style>
+    </head>
+    <body>
+        <div id="terminal-container"></div>
+        <script>
+            var term = new Terminal(),
+                container = document.getElementById('terminal-container');
+
+            term.open(container);
+            term.writeln('Hello, welcome to xterm.js');
+            term.writeln('');
+            term.writeln('Check it out at github.com/sourcelair/xterm.js');
+            term.linkify();
+        </script>
+    </body>
+</html>

addons/linkify/linkify.js

@@ -0,0 +1,165 @@
+(function (linkify) {
+    if (typeof define == 'function') {
+        /*
+         * Require.js is available
+         */
+        define(['../../src/xterm'], linkify);
+    } else {
+        /*
+         * Plain browser environment
+         */ 
+        linkify(this.Xterm);
+    }
+})(function (Xterm) {
+	'use strict';
+
+    /**
+     * This module provides methods for convertings valid URL substrings 
+     * into HTML anchor elements (links), inside a terminal view.
+     *
+     * @module xterm/addons/linkify/linkify
+     */
+    var exports = {},
+        protocolClause = '(https?:\\/\\/)',
+        domainCharacterSet = '[\\da-z\\.-]+',
+        negatedDomainCharacterSet = '[^\\da-z\\.-]+',
+        domainBodyClause = '(' + domainCharacterSet + ')',
+        tldClause = '([a-z\\.]{2,6})',
+        hostClause = domainBodyClause + '\\.' + tldClause,
+        pathClause = '([\\/\\w\\.-]*)*\\/?',
+        negatedPathCharacterSet = '[^\\/\\w\\.-]+',
+        bodyClause = hostClause + pathClause,
+        start = '(?:^|' + negatedDomainCharacterSet + ')(',
+        end = ')($|' + negatedPathCharacterSet + ')',
+        urlClause = start + protocolClause + '?' + bodyClause + end,
+        urlRegex = new RegExp(urlClause);
+
+    /**
+     * Converts all valid URLs found in the given terminal line into
+     * hyperlinks. The terminal line can be either the HTML element itself
+     * or the index of the termina line in the children of the terminal
+     * rows container.
+     *
+     * @param {Xterm} terminal - The terminal that owns the given line.
+     * @param {number|HTMLDivElement} line - The terminal line that should get
+     *								  		 "linkified".
+     * @emits linkify
+     * @emits linkify:line
+     */
+    exports.linkifyTerminalLine = function (terminal, line) {
+        if (typeof line == 'number') {
+            line = terminal.rowContainer.children[line];
+        } else if (! (line instanceof HTMLDivElement)) {
+            var message = 'The "line" argument should be either a number';
+            message += ' or an HTMLDivElement';
+
+            throw new TypeError(message);
+        }
+
+        var buffer = document.createElement('span'),
+            nodes = line.childNodes;
+
+        for (var j=0; j<nodes.length; j++) {
+            var node = nodes[j];
+
+            /*
+             * Since we cannot access the TextNode's HTML representation
+             * from the instance itself, we assign its data as textContent
+             * to a dummy buffer span, in order to retrieve the TextNode's
+             * HTML representation from the buffer's innerHTML.
+             */
+            buffer.textContent = node.data;
+
+            var nodeHTML = buffer.innerHTML;
+
+            /*
+             * Apply function only on TextNodes
+             */
+            if (node.nodeType != node.TEXT_NODE) {
+                continue;
+            }
+
+            
+            var match = node.data.match(urlRegex);
+
+            /*
+             * If no URL was found in the current text, return.
+             */
+            if (!match) {
+                continue;
+            }
+
+            var url = match[1],
+                startsWithProtocol = new RegExp('^' + protocolClause),
+                urlHasProtocol = url.match(startsWithProtocol),
+                href = (urlHasProtocol) ? url : 'http://' + url,
+                link = '<a href="' +  href + '" >' + url + '</a>',
+                newHTML = nodeHTML.replace(url, link);
+
+            line.innerHTML = line.innerHTML.replace(nodeHTML, newHTML);
+        }
+
+        /**
+         * This event gets emitted when conversion of all URL susbtrings
+         * to HTML anchor elements (links) has finished, for a specific
+         * line of the current Xterm instance.
+         *
+         * @event linkify:line
+         */
+        terminal.emit('linkify:line', line);
+    };
+
+
+    /**
+     * Converts all valid URLs found in the terminal view into hyperlinks.
+     *
+     * @param {Xterm} terminal - The terminal that should get "linkified".
+     * @emits linkify
+     * @emits linkify:line
+     */
+    exports.linkify = function (terminal) {
+        var rows = terminal.rowContainer.children;
+
+        for (var i=0; i<rows.length; i++) {
+            var line = rows[i];
+
+			exports.linkifyTerminalLine(terminal, line);
+        }
+        
+        /**
+         * This event gets emitted when conversion of  all URL substrings to
+         * HTML anchor elements (links) has finished for the current Xterm
+         * instance's view.
+         *
+         * @event linkify
+         */
+        terminal.emit('linkify');
+    };
+
+    /*
+     * Extend Xterm prototype.
+     */
+
+   /**
+     * Converts all valid URLs found in the current terminal linte into
+     * hyperlinks.
+     *
+     * @memberof Xterm
+     * @param {number|HTMLDivElement} line - The terminal line that should get
+     *								  		 "linkified".
+     */   
+    Xterm.prototype.linkifyTerminalLine = function (line) {
+        return exports.linkifyTerminalLine(this, line);
+    };
+
+   /**
+     * Converts all valid URLs found in the current terminal into hyperlinks.
+     *
+     * @memberof Xterm
+     */   
+    Xterm.prototype.linkify = function () {
+        return exports.linkify(this);
+    };
+
+    return exports;
+});

bower.json

@@ -1,5 +1,5 @@
 {
   "name": "xterm.js",
-  "version": "0.8",
+  "version": "0.30",
   "ignore": ["demo", "docs", "test", ".gitignore"]
 }

demo/index.html

@@ -3,11 +3,12 @@
     <head>
         <title>xterm.js demo</title>
         <link rel="stylesheet" href="../src/xterm.css" />
-        <link rel="stylesheet" href="../addon/fullscreen/fullscreen.css" />
+        <link rel="stylesheet" href="../addons/fullscreen/fullscreen.css" />
         <link rel="stylesheet" href="style.css" />
-        <script src="../src/xterm.js"></script>
-        <script src="../addon/fullscreen/fullscreen.js"></script>
-        <script src="main.js" defer></script>
+        <script src="../src/xterm.js" ></script>
+        <script src="../addons/fit/fit.js" ></script>
+        <script src="../addons/fullscreen/fullscreen.js" ></script>
+        <script src="main.js" defer ></script>
     </head>
     <body>
         <h1>

demo/main.js

@@ -1,12 +1,13 @@
 var terminalContainer = document.getElementById('terminal-container'),
-    term = new Terminal();
+    term = new Terminal(),
+    prompt = '> ';
 
 term.open(terminalContainer);
 term.fit();
 
 term.prompt = function () {
-  term.write('\r\n> ');
-}
+  term.write('\r\n' + prompt);
+};
 
 term.writeln('Welcome to xterm.js');
 term.writeln('Just type some keys in the prompt below.');
@@ -16,10 +17,15 @@ term.prompt();
 term.on('key', function (key, ev) {
   var printable = (!ev.altKey && !ev.altGraphKey && !ev.ctrlKey && !ev.metaKey);
 
-  if (ev.keyIdentifier == 'Enter') {
+  if (ev.keyCode == 13) {
     term.prompt();
   } else if (ev.keyCode == 8) {
-    term.write('\b \b');
+    /*
+     * Do not delete the prompt
+     */
+    if (term.x > 2) {
+      term.write('\b \b');
+    }
   } else if (printable) {
     term.write(key);
   }

docs/conf.py

@@ -44,16 +44,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'xterm.js'
-copyright = u'2014, sourceLair Limited'
+copyright = u'2015, SourceLair Limited'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1a'
+version = '0.30'
 # The full version, including alpha/beta/rc tags.
-release = '0.1a'
+release = '0.30 Alpha'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/events.rst

@@ -0,0 +1,43 @@
+------
+Events
+------
+
+focus
+^^^^^
+This event is fired, when the Terminal gets focus.
+
+blur
+^^^^
+This event is fired, when the Terminal loses focus.
+
+open
+^^^^
+This event is fired, when the Terminal gets opened into a DOM Element.
+
+keydown
+^^^^^^^
+This event is fired, when the `keydown` DOM Event gets triggered on the Terminal.
+
+keypress
+^^^^^^^^
+This event is fired, when the `keypress` DOM Event gets triggered on the Terminal.
+
+key
+^^^
+This event is fired, when a key is being handled by the Terminal.
+
+resize
+^^^^^^
+This event is being fired, when the Terminal view gets resized by the `resize` method.
+
+data
+^^^^
+This event is being fired, when a chunk of input data gets handled by the terminal.
+
+copy
+^^^^
+This event is fired, when the `copy` DOM Event gets triggered on the Terminal.
+
+paste
+^^^^^
+This event is fired, when the `paste` DOM Event gets triggered on the Terminal.

docs/index.rst

@@ -6,17 +6,40 @@
 Welcome to xterm.js's documentation!
 ====================================
 
-Contents:
+This is the documentation for xterm.js. Xterm.js is a full xterm clone, written completely in JavaScript.
+
+Xterm.js supplies a modular, event-based interface that lets developers build addons and themes that augment 
+the experience of running a fully-feature terminal inside the browser.
+
+Xterm.js serves as the foundation for the terminal found at www.sourcelair.com.
+
+.. image:: screenshot.png
+
+Getting started
+^^^^^^^^^^^^^^^
+
+.. code-block:: javascript
+    
+   var term = new Terminal(),
+       url = 'ws://docker/containers/mycontainer/attach/ws/?stdin=1&stdout=1&stderr=1&logs=1',
+       socket = new WebSocket(url);
+  
+   term.open(document.body);
+   term.on('data', function (data) {
+       socket.send(data);
+   });
+   socket.onmessage = function (e) {
+       term.write(e.data);
+   }
+    
+
+Contents
+^^^^^^^^
+The standard way to create a terminal-based application with xterm.js is to work with its events and
+methods, that let you manipulate input, output, state and size of the terminal.
 
 .. toctree::
-   :maxdepth: 2
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   :maxdepth: 1
+   
+   methods
+   events

docs/methods.rst

@@ -0,0 +1,47 @@
+-------
+Methods
+-------
+
+focus()
+^^^^^^^
+Sends focus to the terminal
+
+blur()
+^^^^^^
+Blurs the Terminal
+
+open(element)
+^^^^
+Open the Xterm terminal, inside the given element.
+
+resize(x, y)
+^^^^^^^^^^^^
+Resize the terminal, according to the given columns and rows.
+
+insertRow(row)
+^^^^^^^^^^^^^^
+Insert the given row in the terminal.
+
+on(event, callback)
+^^^^^^^^^^^^^^^^^^^
+Hook the given callback, to the given event.
+
+off(event, callback)
+^^^^^^^^^^^^^^^^^^^
+Remove the Hook of the given callback, from the given event.
+
+once(event, callback)
+^^^^^^^^^^^^^^^^^^^
+Hook the given callback to the given event, for just a single invocation.
+
+write(data)
+^^^^^^^^^^^
+Write the given data to the terminal.
+
+writeln(data)
+^^^^^^^^^^^^^
+Write the given data to the terminal, followed by a carriage return and a new line.
+
+handler(data)
+^^^^^^^^^^^^^
+Fire the data event, for the given data.

src/xterm.css

@@ -32,21 +32,31 @@
  */
 
 /*
-*  Default style for xterm.js
-*/
+ *  Default style for xterm.js
+ */
 
-.xterm {
+.terminal {
     background-color: #000;
     color: #fff;
-    outline: none;
     font-family: courier-new, courier, monospace;
+    position: relative;
 }
 
-.xterm .terminal-cursor {
+.terminal:focus {
+    outline: none;
+}
+
+.terminal .terminal-cursor {
     background-color: #fff;
+    color: #000;
 }
 
-.xterm .xterm-helper-textarea {
+.terminal .xterm-helpers {
+  position: absolute;
+  top: 0;
+}
+
+.terminal .xterm-helper-textarea {
     opacity: 0;
     width: 0;
     height: 0;
@@ -54,8 +64,8 @@
 }
 
 /*
-*  Determine default colors for xterm.js
-*/
+ *  Determine default colors for xterm.js
+ */
 .terminal .xterm-bold {
     font-weight: bold;
 }