**** mass:werk termlib.js - JS-WebTerminal Object v1.07 ****
(c) Norbert Landsteiner 2003-2005
mass:werk - media environments
<http://www.masswerk.at>
Contents:
1 About
2 Creating a new Terminal Instance
2.1 Configuration Values
3 Using the Terminal
3.1 The Default Handler
3.2 Input Modes
3.2.1 Normal Line Input (Command Line Mode)
3.2.1.2 Special Keys (ctrlHandler)
3.2.2 Raw Mode
3.2.3 Character Mode
3.3 Other Handlers
3.3.1 initHandler
3.3.2 exitHandler
3.4 Flags for Behaviour Control
4 Output Methods
4.1 Terminal.type()
4.2 Terminal.write()
4.3 Terminal.typeAt()
4.4 Terminal.setChar()
4.5 Terminal.newLine()
4.6 Terminal.clear()
4.7 Terminal.statusLine()
4.8 Terminal.printRowFromString()
4.9 Terminal.redraw()
5 Cursor Methods and Editing
5.1 Terminal.cursorOn()
5.2 Terminal.cursorOff()
5.3 Terminal.cursorSet()
5.4 Terminal.cursorLeft()
5.5 Terminal.cursorRight()
5.6 Terminal.backspace()
5.7 Terminal.fwdDelete()
5.8 Terminal.isPrintable()
6 Other Methods of the Terminal Object
6.1 Terminal.prompt()
6.2 Terminal.reset()
6.3 Terminal.open()
6.4 Terminal.close()
6.5 Terminal.focus()
6.6 Terminal.moveTo()
6.7 Terminal.resizeTo()
6.8 Terminal.getDimensions()
6.9 Terminal.rebuild()
7 Global Static Methods (TermGlobals)
7.1 TermGlobals.setFocus()
7.2 TermGlobals.keylock (Global Locking Flag)
7.3 TermGlobalsText Methods
7.3.1 TermGlobals.normalize()
7.3.2 TermGlobals.fillLeft()
7.3.3 TermGlobals.center()
7.3.4 TermGlobals.stringReplace()
8 Localization
9 Cross Browser Functions
10 Architecture, Internals
10.1 Global Entities
10.2 I/O Architecture
10.3 Compatibility
11 History
12 Example for a Command Line Parser
13 License
14 Disclaimer
15 References
1 About
The Terminal library "termlib.js" provides an object oriented constructor and control
methods for a terminal-like DHTML interface.
"termlib.js" features direct keyboard input and powerful output methods for multiple
instances of the `Terminal' object (including focus control).
The library was written with the aim of simple usage and a maximum of compatibility with
minimal foot print in the global namespace.
A simple example:
// creating a terminal and using it
var term = new Terminal( {handler: termHandler} );
term.open();
function termHandler() {
var line = this.lineBuffer;
this.newLine();
if (line == "help") {
this.write(helpPage)
}
else if (line == "exit") {
this.close();
return;
}
else if (line != "") {
this.write("You typed: "+line);
}
this.prompt();
}
var helpPage = [
"This is the monstrous help page for my groovy terminal.",
"Commands available:",
" help ... print this monstrous help page",
" exit ... leave this groovy terminal",
" ",
"Have fun!"
];
You should provide CSS font definitions for the classes ".term" (normal video) and
".termReverse" (reverse video) in a monospaced font.
A sample stylesheet "term_styles.css" comes with this library.
See the sample application "multiterm_test.html" for a demo of multiple terminals.
v.1.01: If you configure to use another font class (see 2.1 Configuration Values),
you must provide a subclass ".termReverse" for reversed video.
p.e.: .myFontClass .termReverse {
/* your definitions for reverse video here */
}
With the addition of `conf.fontClass' you can now create multiple
instances with independend appearences.
2 Creating a new Terminal Instance
Use the `new' constructor to create a new instance of the Terminal object. You will want
to supply a configuration object as an argument to the constructor. If the `new'
constructor is called without an object as its first argument, default values are used.
p.e.:
// creating a new instance of Terminal
var conf= {
x: 100,
y: 100,
cols: 80,
rows: 24
}
var term = new Term(conf);
term.open();
`Terminal.open()' initializes the terminal and makes it visible to the user.
This is handled in by separate method to allow the re-initilization of instances
previously closed.
NOTE:
The division element (or NS-layer) that holds the terminal must be present when calling
`Terminal.open()'. So you must not call this method from the header of a HTML-document at
compile time.
2.1 Configuration Values
Set any of these values in your configuration object to override:
LABEL DEFAULT VALUE COMMENT
x 100 terminal's position x in px
y 100 terminal's position y in px
divDiv 'termDiv' id of terminals CSS division
bgColor '#181818' background color (HTML hex value)
frameColor '#555555' frame color (HTML hex value)
frameWidth 1 frame border width in px
fontClass 'term' class name of CSS font definition to use
cols 80 number of cols per row
rows 24 number of rows
rowHeight 15 a row's line-height in px
blinkDelay 500 delay for cursor blinking in milliseconds
crsrBlinkMode false true for blinking cursor
crsrBlockMode true true for block-cursor else underscore
DELisBS false handle <DEL> as <BACKSPACE>
printTab true handle <TAB> as printable (prints as space)
printEuro true handle unicode 0x20AC (Euro sign) as printable
catchCtrlH true handle ^H as <BACKSPACE>
closeOnESC true close terminal on <ESC>
historyUnique false prevent consecutive and identical entries in history
id 0 terminal id
ps '>' prompt string
greeting '%+r Terminal ready. %-r' string for greeting if no initHandler is used
handler termDefaultHandler reference to handler for command interpretation
ctrlHandler null reference to handler called on uncatched special keys
initHandler null reference to handler called at end of init()
exitHandler null reference to handler called on close()
At least you will want to specify `handler' to implement your own command parser.
Note: While `id' is not used by the Termninal object, it provides an easy way to identify
multiple terminals by the use of "this.id". (e.g.: "if (this.id == 1) startupterm = true;")
p.e.:
// creating two individual Terminal instances
var term1 = new Terminal(
{
id: 1,
x: 200,
y: 10,
cols: 80,
rows: 12,
greeting: "*** This is Terminal 1 ***",
handler: myTerminalHandler
}
);
term1.open();
var term2 = new Terminal(
{
id: 2,
x, 200,
y: 220,
cols: 80
rows: 12,
greeting: "*** This is Terminal 2 ***",
handler: myTerminalHandler
}
);
term2.open();
3 Using the Terminal
There are 4 different handlers that are called by a Terminal instance to process input and
some flags to control the input mode and behaviour.
3.1 The Default Handler (a simlple example for input handling)
If no handlers are defined in the configuration object, a default handler is called to
handle a line of user input. The default command line handler `termDefaultHandler' just
closes the command line with a new line and echos the input back to the user:
function termDefaultHandler() {
this.newLine();
if (this.lineBuffer != '') {
this.type('You typed: '+this.lineBuffer);
this.newLine();
}
this.prompt();
}
First you may note that the instance is refered to as `this'. So you need not worry about
which Terminal instance is calling your handler. As the handler is entered, the terminal
is locked for user input and the cursor is off. The current input is available as a string
value in `this.lineBuffer'.
The method `type(<text>)' just does what it says and types a string at the current cursor
position to the terminal screen.
`newLine()' moves the cursor to a new line.
The method `prompt()' adds a new line if the cursor isn't at the start of a line, outputs
the prompt string (as specified in the configuration), activates the cursor, and unlocks
the terminal for further input. While you're doing normal command line processing, always
call `prompt()' when leaving your handler.
In fact this is all you need to create your own terminal application. Please see at least
the method `write()' for a more powerful output method.
Below we will refer to all methods of the Terminal object as `Terminal.<method>()'.
You can call them as `this.<method>()' in a handler or as methods of your named instance
in other context (e.g.: "myTerminal.close()").
[In technical terms these methods are methods of the Terminal's prototype object, while
the properties are properties of a Termninal instance. Since this doesn't make any
difference to your script, we'll refer to both as `Terminal.<method-or-property>'.]
3.2 Input Modes
3.2.1 Normal Line Input (Command Line Mode)
By default the terminal is in normal input mode. Any printable characters in the range of
ASCII 0x20 - 0xff are echoed to the terminal and may be edited with the use of the cursor
keys and the <BACKSPACE> key.
The cursor keys UP and DOWN let the user browse in the command line history (the list of
all commands issued previously in this Terminal instance).
If the user presses <CR> or <ENTER>, the line is read from the terminal buffer, converted
to a string, and placed in `Terminal.lineBuffer' (-> `this.lineBuffer') for further use.
The terminal is then locked for further input and the specified handler
(`Terminal.handler') is called.
3.2.1.2 Special Keys (ctrlHandler)
If a special character (ASCII<0x20) or an according combination of <CTRL> and a key is
pressed, which is not caught for editing or "enter", and a handler for `ctrlHandler' is
specified, this handler is called.
The ASCII value of the special character is available in `Terminal.inputChar'. Please note
that the terminal is neither locked, nor is the cursor off - all further actions have to
be controlled by `ctrlHandler'. (The tracking of <CTRL>-<key> combinations as "^C" usually
works but cannot be taken for granted.)
A named reference of the special control values in POSIX form (as well as the values of
the cursor keys [LEFT, RIGHT, UP, DOWN]) is available in the `termKey' object.
p.e.:
// a simple ctrlHandler
function myCtrlHandler() {
if (this.inputChar == termKey.ETX) {
// exit on ^C (^C == ASCII 0x03 == <ETX>)
this.close();
}
}
If no `ctrlHandler' is specified, control keys are ignored (default).
3.2.2 Raw Mode
If the flag `Terminal.rawMode' is set to a value evaluating to `true', no special keys are
tracked but <CR> and <ENTER> (and <ESC>, if the flag `Terminal.closeOnESC' is set).
The input is NOT echoed to the terminal. All printable key values [0x20-0xff] are
transformed to characters and added to `Terminal.lineBuffer' sequentially. The command
line input is NOT added to the history.
This mode is especially suitable for password input.
p.e.:
// using raw mode for password input
function myTermHandler() {
this.newLine();
// we stored a flag in Terminal.env to track the status
if (this.env.getpassword) {
// leave raw mode
this.rawMode = false;
if (passwords[this.env.user] == this.lineBuffer) {
// matched
this.type('Welcome '+this.env.user);
this.env.loggedin = true;
}
else {
this.type('Sorry.');
}
this.env.getpassword = false;
}
else {
// simple parsing
var args = this.lineBuffer.split(' ');
var cmd = args[0];
if (cmd == 'login') {
var user = args[1];
if (!user) {
this.type('usage: login <username>');
}
else {
this.env.user = user;
this.env.getpassword = true;
this.type('password? ');
// enter raw mode
this.rawMode = true;
// leave without prompt so we must unlock first
this.lock = false;
return;
}
}
/*
other actions ...
*/
}
this.prompt();
}
In this example a handler is set up to process the command "login <username>" and ask for
a password for the given user name in raw mode. Note the use of the object `Terminal.env'
which is just an empty object set up at the creation of the Terminal instance. Its only
purpose is to provide an individual namespace for private data to be stored by a Terminal
instance.
NOTE: The flag `Terminal.lock' is used to control the keyboard locking. If we would not
set this to `false' before leaving in raw mode, we would be caught in dead-lock, since no
input could be entered and our handler wouldn't be called again. - A dreadful end of our
terminal session.
NOTE: Raw mode utilizes the property `Terminal.lastLine' to collect the input string.
This is normally emty, when a handler is called. This is not the case if your script left
the input process on a call of ctrlHandler. You should clear `Terminal.lastLine' in such
a case, if you're going to enter raw mode immediatly after this.
3.2.3 Character Mode
If the flag `Terminal.charMode' is set to a value evaluating to `true', the terminal is in
character mode. In this mode the numeric ASCII value of the next key typed is stored in
`Terminal.inputChar'. The input is NOT echoed to the terminal. NO locking or cursor
control is performed and left to the handler.
You can use this mode to implement your editor or a console game.
`Terminal.charMode' takes precedence over `Terminal.rawMode'.
p.e.:
// using char mode
function myTermHandler() {
// this is the normal handler
this.newLine();
// simple parsing
var args = this.lineBuffer.split(' ');
var cmd = args[0];
if (cmd == 'edit') {
// init the editor
myEditor(this);
// redirect the handler to editor
this.handler = myEditor;
// leave in char mode
this.charMode = true;
// show cursor
this.cursorOn();
// don't forget unlocking
this.lock = false;
return;
}
/*
other actions ...
*/
this.prompt();
}
function myEditor(initterm) {
// our dummy editor (featuring modal behaviour)
if (initterm) {
// perform initialization tasks
initterm.clear();
initterm.write('this is a simple test editor; leave with <ESC> then "q"%n%n');
initterm.env.mode = '';
// store a reference of the calling handler
initterm.env.handler = initterm.handler;
return;
}
// called as handler -> lock first
this.lock=true;
// hide cursor
this.cursorOff();
var key = this.inputChar;
if (this.env.mode == 'ctrl') {
// control mode
if (key == 113) {
// "q" => quit
// leave charMode and reset the handler to normal
this.charMode = false;
this.handler = this.env.handler;
// clear the screen
this.clear();
// prompt and return
this.prompt();
return;
}
else {
// leave control mode
this.env.mode = '';
}
}
else {
// edit mode
if (key == termKey.ESC) {
// enter control mode
// we'd better indicate this in a status line ...
this.env.mode = 'ctrl';
}
else if (key == termKey.LEFT) {
// cursor left
}
else if (key == termKey.RIGHT) {
// cursor right
}
if (key == termKey.UP) {
// cursor up
}
else if (key == termKey.DOWN) {
// cursor down
}
else if (key == termKey.CR) {
// cr or enter
}
else if (key == termKey.BS) {
// backspace
}
else if (key == termKey.DEL) {
// fwd delete
// conf.DELisBS is not evaluated in charMode!
}
else if (this.isPrintable(key)) {
// printable char - just type it
var ch = String.fromCharCode(key);
this.type(ch);
}
}
// leave unlocked with cursor
this.lock = false;
this.cursorOn();
}
Note the redirecting of the input handler to replace the command line handler by the
editor. The method `Terminal.clear()' clears the terminal.
`Terminal.cursorOn()' and `Terminal.cursorOff()' are used to show and hide the cursor.
3.3 Other Handlers
There are two more handlers that can be specified in the configuration object:
3.3.1 initHandler
`initHandler' is called at the end of the initialization triggered by `Terminal.open()'.
The default action - if no `initHandler' is specified - is:
// default initilization
this.write(this.conf.greeting);
this.newLine();
this.prompt();
Use `initHandler' to perform your own start up tasks (e.g. show a start up screen). Keep
in mind that you should unlock the terminal and possibly show a cursor to give the
impression of a usable terminal.
3.3.2 exitHandler
`exitHandler' is called by `Terminal.close()' just before hiding the terminal. You can use
this handler to implement any tasks to be performed on exit. Note that this handler is
called even if the terminal is closed on <ESC> outside of your inputHandlers control.
See the file "multiterm_test.html" for an example.
3.4 Overview: Flags for Behaviour Control
These falgs are accessible as `Terminal.<flag>' at runtime. If not stated else, the
initial value may be specified in the configuration object.
The configuration object and its properties are accessible at runtime via `Terminal.conf'.
NAME DEFAULT VALUE MEANING
blink_delay 500 delay for cursor blinking in milliseconds.
crsrBlinkMode false true for blinking cursor.
if false, cursor is static.
crsrBlockMode true true for block-cursor else underscore.
DELisBS false handle <DEL> as <BACKSPACE>.
printTab true handle <TAB> as printable (prints as space)
if false <TAB> is handled as a control character
printEuro true handle the euro sign as valid input char.
if false char 0x20AC is printed, but not accepted
in the command line
catchCtrlH true handle ^H as <BACKSPACE>.
if false, ^H must be tracked by a custom
ctrlHandler.
closeOnESC true close terminal on <ESC>.
if true, <ESC> is not available for ctrHandler.
historyUnique false unique history entries.
if true, entries that are identical to the last
entry in the user history will not be added.
charMode false terminal in character mode (tracks next key-code).
(runtime only)
rawMode false terminal in raw mode (no echo, no editing).
(runtime only)
Not exactly a flag but useful:
ps '>' prompt string.
4 Output Methods
Please note that any output to the terminal implies an advance of the cursor. This means,
that if your output reaches the last column of your terminal, the cursor is advanced and
a new line is opened automatically. This procedure may include scrolling to make room for
the new line. While this is not of much interest for most purposes, please note that, if
you output a string of length 80 to a 80-columns-terminal, and a new line, and another
string, this will result in an empty line between the two strings.
4.1 Terminal.type( <text> [,<stylevector>] )
Types the string <text> at the current cursor position to the terminal. Long lines are
broken where the last column of the terminal is reached and continued in the next line.
`Terminal.write()' does not support any kind of arbitrary line breaks. (This is just a
basic output routine. See `Terminal.write()' for a more powerful output method.)
A bitvector may be supplied as an optional second argument to represent a style or a
combination of styles. The meanings of the bits set are interpreted as follows:
<stylevector>:
1 ... reverse (2 power 0)
2 ... underline (2 power 1)
4 ... italics (2 power 2)
8 ... strike (2 power 3)
So "Terminal.type( 'text', 5 )" types "text" in italics and reverse video.
Note:
There is no bold, for most monospaced fonts (including Courier) tend to render wider in
bold. Since this would bring the terminal's layout out of balance, we just can't use bold
as a style. - Sorry.
The HTML-representation of this styles are defined in "TermGlobals.termStyleOpen" and
"TermGlobals.termStyleClose".
4.2 Terminal.write( <text> [,<usemore>] )
Writes a text with markup to the terminal. If an optional second argument evaluates to
true, a UN*X-style utility like `more' is used to page the text. The text may be supplied
as a single string (with newline character "\n") or as an array of lines. Any other input
is transformed to a string value before output.
4.2.1 Mark-up:
`Terminal.write()' employs a simple mark-up with the following syntax:
<markup>: %([+|-]<style>|n|CS|%)
where "+" and '-' are used to switch on and off a style, where
<style>:
"i" ... italics
"r" ... reverse
"s" ... strike
"u" ... underline
"p" ... reset to plain ("%+p" == "%-p")
styles may be combined and may overlap. (e.g. "This is %+rREVERSE%-r, %+uUNDER%+iSCORE%-u%-i.")
"%n" represents a new line (in fact "\n" is translated to "%n" before processing)
"%CS" clears the terminal screen
"%%" represents the percent character ('%')
4.2.2 Buffering:
`Terminal.write()' writes via buffered output to the terminal. This means that the
provided text is rendered to a buffer first and then only the visible parts are transfered
to the terminal display buffers. This avoids scrolling delays for long output.
4.2.3 UseMore Mode:
The buffering of `Terminal.write()' allows for pagewise output, which may be specified by
a second boolean argument. If <usemore> evaluates to `true' and the output exceeds the
range of empty rows on the terminal screen, `Terminal.write()' performs like the UN*X
utility `more'. The next page may be accessed by hitting <SPACE> while <q> terminates
paging and returns with the prompt (-> `Terminal.prompt()').
To use this facillity make sure to return immediatly after calling `Terminal.write()' in
order to allow the more-routine to track the user input.
The terminal is set to "charMode == false" afterwards.
p.e.:
// using Terminal.write as a pager
function myTermHandler() {
this.newLine();
var args = this.lineBuffer.split(' ');
var cmd = args[0];
if (cmd == 'more') {
var page = args[1];
if (myPages[page]) {
// Terminal.write as a pager
this.write(myPages[page], true);
return;
}
else {
// Terminal.write for simple output
this.write('no such page.');
}
}
/*
other actions ...
*/
this.prompt();
}
4.3 Terminal.typeAt( <r>, <c>, <text> [,<stylevector>] )
Output the string <text> at row <r>, col <c>.
For <stylevector> see `Terminal.type()'.
`Terminal.typeAt()' does not move the cursor.
4.4 Terminal.setChar( <charcode>, <r>, <c> [,<stylevector>] )
Output a single character represented by the ASCII value of <charcode> at row <r>, col <c>.
For <stylevector> see `Terminal.type()'.
4.5 Terminal.newLine()
Moves the cursor to the first column of the next line and performs scrolling, if needed.
4.6 Terminal.clear()
Clears the terminal screen. (Returns with cursor off.)
4.7 Terminal.statusLine( <text> [,<stylevector> [,<lineoffset>]] )
All output acts on a logical screen with the origin at row 0 / col 0. While the origin is
fixed, the logical width and height of the terminal are defined by `Terminal.maxCols' and
`Terminal.maxLines'. These are set to the configuration dimensions at initilization and by
`Terminal.reset()', but may be altered at any moment. Please note that there are no bounds
checked, so make sure that `Terminal.maxCols' and `Terminal.maxLines' are less or equal
to the configuration dimensions.
You may want to decrement `Terminal.maxLines' to keep space for a reserved status line.
`Terminal.statusLine( <text>, <style> )' offers a simple way to type a text to the last
line of the screen as defined by the configuration dimensions.
// using statusLine()
function myHandler() {
// ...
// reserve last line
this.maxLines = term.conf.rows-1;
// print to status line in reverse video
this.statusLine("Status: <none>", 1);
// ...
}
For multiple status lines the optional argument <lineoffset> specifies the addressed row,
where 1 is the line closest to the bottom, 2 the second line from the bottom and so on.
(default: 1)
4.8 Terminal.printRowFromString( <r> , <text> [,<stylevector>] )
Outputs the string <text> to row <r> in the style of an optional <stylevector>.
If the string's length exceeds the length of the row (up to `Terminal.conf.cols'), extra
characteres are ignored, else any extra space is filled with character code 0 (prints as
<SPACE>).
The valid range for <row> is: 0 >= <row> < `Terminal.maxLines'.
`Terminal.printRowFromString()' does not set the cursor.
You could, for example, use this method to output a line of a text editor's buffer.
p.e.:
// page refresh function of a text editor
function myEditorRefresh(termref, topline) {
// termref: reference to Terminal instance
// topline: index of first line to print
// lines of text are stored in termref.env.lines
for (var r=0; r<termref.maxLines; r++) {
var i = topline + r;
if (i < termref.env.lines.length) {
// output stored line
termref.printRowFromString(r, termref.env.lines[i]);
}
else {
// output <tilde> for empty line
termref.printRowFromString(r, '~');
}
}
// set cursor to origin
termref.r = termref.c = 0; // same as termref.cursorSet(0, 0);
}
4.9 Terminal.redraw( <row> )
Basic function to redraw a terminal row <row> according to screen buffer values.
For hackers only. (e.g.: for a console game, hack screen buffers first and redraw all
changed rows at once.)
5 Cursor Methods and Editing
5.1 Terminal.cursorOn()
Show the cursor.
5.2 Terminal.cursorOff()
Hide the cursor.
5.3 Terminal.cursorSet( <r>, <c> )
Set the cursor position to row <r> column <c>.
`Terminal.cursorSet()' preserves the cursor's active state (on/off).
5.4 Terminal.cursorLeft()
Move the cursor left. (Movement is restricted to the logical input line.)
`Terminal.cursorLeft()' preserves the cursor's active state (on/off).
5.5 Terminal.cursorRight()
Move the cursor right. (Movement is restricted to the logical input line.)
`Terminal.cursorRight()' preserves the cursor's active state (on/off).
5.6 Terminal.backspace()
Delete the character left from the cursor, if the cursor is not in first position of the
logical input line.
`Terminal.backspace()' preserves the cursor's active state (on/off).
5.7 Terminal.fwdDelete()
Delete the character under the cursor.
`Terminal.fwdDelete()' preserves the cursor's active state (on/off).
5.8 Terminal.isPrintable( <key code> [,<unicode page 1 only>] )
Returns `true' if the character represented by <key code> is printable with the current
settings. An optional second argument <unicode page 1 only> limits the range of valid
values to 255 with the exception of the Euro sign, if the flag `Terminal.printEuro' is set.
(This second flag is used for input methods but not for output methods. So you may only
enter portable characters, but you may print others to the terminals screen.)
6 Other Methods of the Terminal Object
6.1 Terminal.prompt()
Performes the following actions:
* advance the cursor to a new line, if the cursor is not at 1st column
* type the prompt string (as specified in the configuaration object)
* show the cursor
* unlock the terminal
(The value of the prompt string can be accessed and changed in `Terminal.ps'.)
6.2 Terminal.reset()
Resets the terminal to sane values and clears the terminal screen.
6.3 Terminal.open()
Opens the terminal. If this is a fresh instance, the HTML code for the terminal is
generated. On re-entry the terminal's visibility is set to `true'. Initialization tasks
are performed and the optional initHandler called. If no initHandler is specified in the
configuration object, the greeting (configuration or default value) is shown and the user
is prompted for input.
v.1.01: `Terminal.open()' now checks for the existence of the DHTML element as defined in
`Terminal.conf.termDiv' and returns success.
6.4 Terminal.close()
Closes the terminal and hides its visibility. An optional exitHandler (specified in the
configuration object) is called, and finally the flag `Terminal.closed' is set to true. So
you can check for existing terminal instances as you would check for a `window' object
created by `window.open()'.
p.e.:
// check for a terminals state
// let array "term" hold references to terminals
if (term[n]) {
if (term[n].closed) {
// terminal exists and is closed
// re-enter via "term[n].open()"
}
else {
// terminal exists and is currently open
}
}
else {
// no such terminal
// create it via "term[n] = new Terminal()"
}
6.5 Terminal.focus()
Set the keyboard focus to this instance of Terminal. (As `window.focus()'.)
6.6 Terminal.moveTo( <x>, <y> )
Move the terminal to position <x>/<y> in px.
(As `window.moveTo()', but inside the HTML page.)
6.7 Terminal.resizeTo( <x>, <y> )
Resize the terminal to dimensions <x> cols and <y> rows.
<x> must be at least 4, <y> at least 2.
`Terminal.resizeTo()' resets `Terminal.conf.rows', `Terminal.conf.cols',
`Terminal.maxLines', and `Terminal.maxCols' to <y> and <x>, but leaves the instance' state
else unchanged. Clears the terminal's screen and returns success.
(A bit like `window.resizeTo()', but with rows and cols instead of px.)
6.8 Terminal.getDimensions()
Returns an object with properties "width" and "height" with numeric values for the
terminal's outer dimensions in px. Values are zero (0) if the element is not present or
if the method fails otherwise.
6.9 Terminal.rebuild()
Rebuilds the Terminal object's GUI preserving its state and content.
Use this to change the color theme on the fly.
p.e.:
// change color settings on the fly
// here: set bgColor to white and font style to "termWhite"
// method rebuild() updates the GUI without side effects
term.conf.bgColor = '#ffffff';
term.conf.fontClass = 'termWhite';
term.rebuild();
7 Global Static Methods (TermGlobals)
7.1 TermGlobals.setFocus( <termref> )
Sets the keyboard focus to the instance referenced by <termref>.
The focus is controlled by `TermGlobals.activeTerm' which may be accessed directly.
See also: `Terminal.focus()'
7.2 TermGlobals.keylock (Global Locking Flag)
The global flag `TermGlobals.keylock' allows temporary keyboard locking without any
other change of state. Use this to free the keyboard for any other resources.
(added in v.1.03)
7.3 TermGlobals Text Methods
There is a small set of methods for common terminal related string tasks:
7.3.1 TermGlobals.normalize( <n>, <fieldlength> )
Converts a number to a string, which is filled at its left with zeros ("0") to the total
length of <filedlength>. (e.g.: "TermGlobals.normalize(1, 2)" => "01")
7.3.2 TermGlobals.fillLeft( <value>, <fieldlength> )
Converts a value to a string and fills it to the left with blanks to <fieldlength>.
7.3.3 TermGlobals.center( <text>, <length> )
Adds blanks at the left of the string <text> until the text would be centered at a line
of length <length>. (No blanks are added to the the right.)
7.3.4 TermGlobals.stringReplace( <string1>, <string2>, <text> )
Replaces all occurences of the string <string1> in <text> with <string2>.
This is just a tiny work around for browsers with no support of RegExp.
8 Localization
The strings and key-codes used by the more utility of `Terminal.write()' are the only
properties of "termlib.js" that may need localization. These properties are defined in
`TermGlobals'. You may override them as needed:
PROPERTY STANDARD VALUE COMMENT
TermGlobals.lcMorePrompt1 ' -- MORE -- ' 1st string
TermGlobals.lcMorePromtp1Style 1 reverse
TermGlobals.lcMorePrompt2 ' (Type: space to continue, \'q\' to quit)' appended string
TermGlobals.lcMorePrompt2Style 0 plain
TermGlobals.lcMoreKeyAbort 113 (key-code: q)
TermGlobals.lcMoreKeyContinue 32 (key-code <SPACE>)
As "TermGlobals.lcMorePrompt2" is appended to "TermGlobals.lcMorePrompt1" make sure that
the length of the combined strings does not exceed `Terminal.conf.cols'.
9 Cross Browser Functions
For DHTML rendering some methods - as needed by the Terminal library - are provided.
These may also be accessed for other purposes.
9.1 TermGlobals.writeElement( <element id>, <text> [,<NS4 parent document>] )
Writes <text> to the DHTML element with id/name <element id>.
<NS4 parent document> is used for NS4 only and specifies an optional reference to a parent
document (default `window.document').
9.2 TermGlobals.setElementXY( <element id>, <x>, <y> )
Sets the DHTML element with id/name <element id> to position <x>/<y>.
For NS4 works only with children of the top document (window.document).
9.3 TermGlobals.setVisible( <element id>, <value> )
If <value> evaluates to `true' show DHTML element with id/name <element id> else hide it.
For NS4 works only with children of the top document (window.document).
9.4 Custom Fixes for Missing String Methods
Although `String.fromCharCode' and `String.prototype.charCodeAt' are defined by ECMA-262-2
specifications, a few number of browsers lack them in their JavaScript implementation. At
compile time custom methods are installed to fix this. Please note that they work only
with ASCII characters and values in the range of [0x20-0xff].
9.5 TermGlobals.setDisplay( <element id>, <value> )
Sets the style.display property of the element with id/name <element id> to the given
<value>. (added with v. 1.06)
10 Architecture, Internals
10.1 Global Entities
The library is designed to leave only a small foot print in the namespace while providing
suitable usability:
Globals defined in this library:
Terminal (Terminal object, `new' constructor and prototype methods)
TerminalDefaults (default configuration, static object)
termDefaultHandler (default command line handler, static function)
TermGlobals (common vars and code for all instances, static object and methods)
termKey (named mappings for special keys, static object)
termDomKeyRef (special key mapping for DOM key constants, static object)
Globals defined for fixing String methods, if missing
(String.fromCharCode, String.prototype.charCodeAt):
termString_keyref, termString_keycoderef, termString_makeKeyref
Required CSS classes for font definitions: ".term", ".termReverse".
10.2 I/O Architecture
The Terminal object renders keyboard input from keyCodes to a line buffer and/or to a
special keyCode buffer. In normal input mode printable input is echoed to the screen
buffers. Special characters like <LEFT>, <RIGHT>, <BACKSPACE> are processed for command
line editing by the internal key-handler `TermGlobals.keyHandler' and act directly on the
screen buffers. On <CR> or <ENTER> the start and end positions of the current line are
evaluated (terminated by ASCII 0x01 at the beginning which separates the prompt from the
user input, and any value less than ASCII 0x20 (<SPACE>) at the right end). Then the
character representation for the buffer values in this range are evaluated and
concatenated to a string stored in `Terminal.lineBuffer'. As this involves some
ASCII-to-String-transformations, the range of valid printable input characters is limited
to the first page of unicode characters (0x0020-0x00ff).
There are two screen buffers for output, one for character codes (ASCII values) and one
for style codes. Style codes represent combination of styles as a bitvector (see
`Terminal.type' for bit values.) The method `Terminal.redraw(<row>)' finally renders the
buffers values to a string of HTML code, which is written to the HTML entity holding the
according terminal row. The character buffer is a 2 dimensional array
`Terminal.charBuf[<row>][<col>]' with ranges for <row> from 0 to less than
`Terminal.conf.rows' and for <col> from 0 to less than `Terminal.conf.cols'. The style
buffer is a 2 dimensional array `Terminal.styleBuf[<row>][<col>]' with according ranges.
So every single character is represented by a ASCII code in `Terminal.charBuf' and a
style-vector in `Terminal.styleBuf'. The range of printable character codes is unlimitted
but should be kept to the first page of unicode characters (0x0020-0x00ff) for
compatibility purpose. (c.f. 8.4)
Keyboard input is first handled on the `KEYDOWN' event by the handler `TermGlobals.keyFix'
to remap the keyCodes of cursor keys to consistent values. (To make them distinctable from
any other possibly printable values, the values of POSIX <IS4> to <IS1> where chosen.)
The mapping of the cursor keys is stored in the properties LEFT, RIGHT, UP, and DOWN of
the global static object `termKey'.
The main keyboard handler `TermGlobals.keyHandler' (invoked on `KEYPRESS' or by
`TermGlobals.keyFix') does some final mapping first. Then the input is evaluated as
controlled by the flags `Terminal.rawMode' and `Terminal.charMode' with precedence of the
latter. In dependancy of the mode defined and the handlers currently defined, the input
either is ignored, or is internally processed for command line editing, or one of the
handlers is called.
In the case of the simultanous presecence of two instances of Terminal, the keyboard focus
is controlled via a reference stored in `TermGlobals.activeTerm'. This reference is also
used to evaluate the `this'-context of the key handlers which are methods of the static
Object `TermGlobals'.
A terminal's screen consists of a HTML-table element residing in the HTML/CSS division
spcified in `Terminal.conf.termDiv'. Any output is handled on a per row bases. The
individual rows are either nested sub-divisions of the main divisions (used for NS4 or
browsers not compatible to the "Gecko" engine) or the indiviual table data elements (<TD>)
of the terminal's inner table (used for browsers employing the "Gecko" engine).
(This implementation was chosen for rendering speed and in order to minimize any screen
flicker.) Any output or change of state in a raw results in the inner HTML contents of a
row's HTML element to be rewritten. Please note that as a result of this a blinking cursor
may cause a flicker in the line containing the cursor's position while displayed by a
browser, which employs the "Gecko" engine.
10.3 Compatibility
Standard web browsers with a JavaScript implementation compliant to ECMA-262 2nd edition
[ECMA262-2] and support for the anonymous array and object constructs and the anonymous
function construct in the form of "myfunc = function(x) {}" (c.f. ECMA-262 3rd edion
[ECMA262-3] for details). This comprises almost all current browsers but Konquerer (khtml)
and versions of Apple Safari for Mac OS 10.0-10.28 (Safari < 1.1) which lack support for
keyboard events.
To provide a maximum of compatibilty the extend of language keywords used was kept to a
minimum and does not exceed the lexical conventions of ECMA-262-2. Especially there is no
use of the `switch' statement or the `RegExp' method of the global object. Also the use of
advanced Array methods like `push', `shift', `splice' was avoided.
11 History
This library evolved from the terminal script "TermApp" ((c) N. Landsteiner 2003) and is
in its current form a down scaled spinn-off of the "JS/UIX" project [JS/UIX] (evolution
"JS/UIX v0.5"). c.f.: <http://www.masswerk.at/jsuix>
v 1.01: added Terminal.prototype.resizeTo(x,y)
added Terminal.conf.fontClass (=> configureable class name)
Terminal.prototype.open() now checks for element conf.termDiv in advance
and returns success.
v 1.02: added support for <TAB> and Euro sign
Terminal.conf.printTab
Terminal.conf.printEuro
and method Terminal.prototype.isPrintable(keycode)
added support for getopt to sample parser ("parser_sample.html")
v 1.03: added global keyboard locking (TermGlobals.keylock)
modified Terminal.prototype.redraw for speed (use of locals)
v 1.04: modified the key handler to fix a bug with MSIE5/Mac
fixed a bug in TermGlobals.setVisible with older MSIE-alike browsers without
DOM support.
moved the script of the sample parser to an individual document
=> "termlib_parser.js" (HTML document is "parser_sample.html" as before)
v 1.05: added config flag historyUnique.
v 1.06: fixed CTRl+ALT (Windows alt gr) isn't CTRL any more
-> better support for international keyboards with MSIE/Win.
fixed double backspace bug for Safari;
added TermGlobals.setDisplay for setting style.display props
termlib.js now outputs lower case html (xhtml compatibility)
(date: 12'2006)
v 1.07: added method Terminal.rebuild() to rebuild the GUI with new color settings.
(date: 01'2007)
12 Example for a Command Line Parser
// parser example, splits command line to args with quoting and escape
// for use as `Terminal.handler'
function commandHandler() {
this.newLine();
var argv = ['']; // arguments vector
var argQL = ['']; // quoting level
var argc = 0; // arguments cursor
var escape = false ; // escape flag
for (var i=0; i<this.lineBuffer.length; i++) {
var ch= this.lineBuffer.charAt(i);
if (escape) {
argv[argc] += ch;
escape = false;
}
else if ((ch == '"') || (ch == "'") || (ch == "`")) {
if (argQL[argc]) {
if (argQL[argc] == ch) {
argc ++;
argv[argc] = argQL[argc] = '';
}
else {
argv[argc] += ch;
}
}
else {
if (argv[argc] != '') {
argc ++;
argv[argc] = '';
argQL[argc] = ch;
}
else {
argQL[argc] = ch;
}
}
}
else if ((ch == ' ') || (ch == '\t')) {
if (argQL[argc]) {
argv[argc] += ch;
}
else if (argv[argc] != '') {
argc++;
argv[argc] = argQL[argc] = '';
}
}
else if (ch == '\\') {
escape = true;
}
else {
argv[argc] += ch;
}
}
if ((argv[argc] == '') && (!argQL[argc])) {
argv.length--;
argQL.length--;
}
if (argv.length == 0) {
// no commmand line input
}
else if (argQL[0]) {
// first argument quoted -> error
this.write("Error: first argument quoted by "+argQL[0]);
}
else {
argc = 0;
var cmd = argv[argc++];
/*
parse commands
1st argument is argv[argc]
arguments' quoting levels in argQL[argc] are of (<empty> | ' | " | `)
*/
if (cmd == 'help') {
this.write(helpPage);
}
else if (cmd == 'clear') {
this.clear();
}
else if (cmd == 'exit') {
this.close();
return;
}
else {
// for test purpose just output argv as list
// assemple a string of style-escaped lines and output it in more-mode
s=' ARG QL VALUE%n';
for (var i=0; i<argv.length; i++) {
s += TermGlobals.stringReplace('%', '%%',
TermGlobals.fillLeft(i, 6) +
TermGlobals.fillLeft((argQL[i])? argQL[i]:'-', 4) +
' "' + argv[i] + '"'
) + '%n';
}
this.write(s, 1);
return;
}
}
this.prompt();
}
The file "parser_sample.html" features a stand-alone parser ("termlib_parser.js") very
much like this. You are free to use it according to the termlib-license (see sect. 13).
It provides configurable values for quotes and esape characters and imports the parsed
argument list into a Terminal instance's namespace. ("parser_sample.html" and
"termlib_parser.js" should accompany this file.)
13 License
This JavaScript-library is free for private and academic use.
Please include a readable copyright statement and a backlink to <http://www.masswerk.at>
in the web page. The library should always be accompanied by the 'readme.txt' and the
sample HTML-documents.
The term "private use" includes any personal or non-commercial use, which is not related
to commercial activites, but excludes intranet, extranet and/or public net applications
that are related to any kind of commercial or profit oriented activity.
For commercial use see <http://www.masswerk.at> for contact information.
Any changes to the library should be commented and be documented in the readme-file.
Any changes must be reflected in the `Terminal.version' string as
"Version.Subversion (compatibility)".
14 Disclaimer
This software is distributed AS IS and in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. The entire risk as to the quality and performance of the product is borne by the
user. No use of the product is authorized hereunder except under this disclaimer.
15 References
[ECMA262-2] "ECMAScript Language Specification" Standard ECMA-262 2nd Edition
August 1998 (ISO/IEC 16262 - April 1998)
[ECMA262-3] "ECMAScript Language Specification" Standard ECMA-262 3rd Edition Final
24 March 2000
[JS/UIX] JS/UIX - JavaScript Uniplexed Interface eXtension
<http://www.masswerk.at/jsuix>
Norbert Landsteiner / Vienna, August 2005
mass:werk - media environments
<http://www.masswerk.at>
See web site for contact information.
9f213f96f6