termhelper v1.1.0

Terminal Helper Author: Elijah Cowley Website: http://au.epcit.biz

This module is designed to allow both keypress and string event firing and includes some helper methods for terminal commands. I have also included basic processing of arrow keys and backspace.

Tested on Debian Linux, please contact me via email ecowley@epcit.biz or using GitHub https://github.com/greywolf001au/termhelper to report any bugs or get help using this modules.

** Install

Install this module using NPM or copy the package to your applications '/node_modules' directory.

npm install termhelper

** Useage

In the application files you would like to use this module add the following line:

var term = require('termhelper')

** Settings

The settings can be changed in termhelper.lib.js The main settings are described here for reference, other settings may be added in future versions.

Available Settings:

---------------------------------------------------------------------------------------------------
|      Setting      |    Default Value    |               Description
---------------------------------------------------------------------------------------------------
| Section: settings
---------------------------------------------------------------------------------------------------
echoKeys                true                 Outputs key on key stroke
prompt                  '> '                 Sets the prompt string
termHistory             true                 Keep command history
allowKill               true                 Allow CTRL + C to kill app
lineEndOut              '\n'                 Line end charater to output
lineEndIn               '\n'                 Line end charater to capture from input
appendEndChar           true                 Append lineEnd character to event data
debug                   false                Outputs keystroke data
allowRun                true                 Allow running of shell commands
date_format             0                    Sets the format to use for dates
date_splitter           '-'                  Sets the default date splitter (for prompt)
locale                  'default'            Sets the language locale (See locale folder for supported locale files, currently supports 'default' only)
locale_path             './locale'           Sets the path to the locale file (without trailing slash)
processing              true                 Turns on or off key and line processing (false will stop all commands from being processed)
proc_blank_line         true                 Turn on or off the default processing of a blank line
use_old_stdin_stream    false                Use old stdin processing stream for keypress module (set to true if you are using an older version of keypress)
exit                    0                    Override an exit value or inject a method (see notes below for options)
---------------------------------------------------------------------------------------------------
| Section: log
---------------------------------------------------------------------------------------------------  
path              ''                   Set the path for storing logs
dir_mode          '0775'               Use mode when creating paths
level             3                    Logging level (input, output, both)
extension         'log'                Create log files with this extension
format            0                    Date format for log filenames
hourly            false                Create a new log file each hour
timestamp         true                 Place timestamp before each log entry
date_splitter     '-'                  Use this date splitter for log files
---------------------------------------------------------------------------------------------------
| Section: alias
---------------------------------------------------------------------------------------------------
run               'run'                Change the terminal run command
echo              'echo'               Change the terminal echo command
exit              'exit'               Change the terminal exit command
prompt            'prompt'             Change the terminal prompt command
version           'version'            Change the terminal version command
show              'show'               Change the terminal show command
time              'time'               Output time to terminal

date 'date' Output date to terminal clear 'clear' Clear terminal uptime 'uptime' Display how long the application has been running (most accurate if the termhelper object is initialised early in your application) unixTime 'utime' Display the time as a unix timestamp __clock '%*' Start the clock (only works in a prompt) console 'console' Display which console we are using ===================================================================================================

---------------------------------------------------------------------------------------------------
| Result        |  Identifier    |     Default Value
---------------------------------------------------------------------------------------------------
| Section: globalVars
---------------------------------------------------------------------------------------------------
Date              '%d'                 'exports.formatDate(thlib.settings.date_format, thlib.settings.date_splitter)'
Current Path      '%p'                 '__dirname'
Locale Time       '%t'                 'd.toLocaleTimeString()'
History Position  '%@'                 'thlib.input.history_position'
History Length    '%#'                 'thlib.input.history.length'
Version           '%v'                 'exports.version()'
Unix Time         '%u'                 'd.getUnixTime()'
Uptime            '%uptime'            'exports.counterFormat(exports.uptime()).toString()'
Start Clock       '%*'                 ''

---------------------------------------------------------------------------------------------------
| Section: input
---------------------------------------------------------------------------------------------------
This section should not be changed unless you know what you are doing and change the code
to use the new object for line & key processing. New variables can be added to the object if you require
or your methods can manipulate these strings before or after default processing.
---------------------------------------------------------------------------------------------------
| Section: temp
---------------------------------------------------------------------------------------------------
Stores a temporary copy of the input string for xconsole and some variables which may be used in future.
These are added by termhelper at run time to save adding to many unchangeable configuartion values in the conf file.

Settings can be modified in the following manner: term.set(section, key, value)

Where 'section' refers to the section key, current sections are: settings, log, alias & locale If a section is null the default section of 'settings' will be used. Key refers to the settings key to change, key may be an object of key/value pairs. Value is the new value for the setting.

Example:

term.set('settings', 'prompt', 'node.js> ');

or

term.set(null, {
  prompt: 'node.js> ',
  debug: true
});

Notes: To load a configuration file use term.set('settings', 'conf_path', '/path/to/my/conf') to load a configuration file (will not be read from config file to save recursive loads ocurring). To have no prompt displayed set the prompt to a blank string or null.

The exit setting can be a string overriding the exit message by passing a string, the exit code if a number is given, a function to call prior to exiting the application or
the following object:
{
  exitCode: exitCode,
  message: message,
  logLevel: logLevel,
  logMessage: logMessage
}

** Processed Keys

|   Key   |           Default Function             |
----------------------------------------------------
  Up            Arrow Scroll back through history
  Down          Arrow Scroll forward through history
  Left          Arrow Move cursor back
  Right         Arrow Move cursor forward
  Backspace     Delete character behind cursor
  Delete        Delete character infront of cursor
  Enter         Process line
  CTRL+C        Exit application
  Home          Move cursor to start of line
  End           Move cursor to end of line
  CTRL+LEFT		Move cursor to the backwards to the start of each new word
  CTRL+RIGHT    Move cursor forward to the start of each new word

** Events

Events can be set for a single keypress and on line data using the following:

term.on('before_proc', function(ch, key) {
  Add your code here....
}

term.on('keypress', function(ch, key) {
  Add your code here....
}

term.on('line', function(data) {
  Add your code here....
}

Default key press processing can be bypassed by returning false from your event handler. Example:

term.on('before_proc', function(ch, key) {
  if (key && key.name === 'home') {
    Add code here....
    return false;
  }
  return { home: false }
}

Note: bypassing command processing will cause all key press events to be bypassed including enter and CTRL+C, to skip individual keypress events return an object containing keyname: false as shown for the home key above.

Line processing will give an invalid command when false is returned from the event handler method however if there is a matching command alias, return true to signal that a command has been processed. This will stop the default command from running. Optionally an object can be returned containing a key named 'valid' and a boolean value showing if a valid command was typed. The prompt can be disabled for a command by returning an object with a 'prompt' key and the boolean value of false (see example.js)

** Available Methods

Several methods have been added to make working in the terminal easier

Method        |      Useage         |   Description                                                                    |
------------------------------------------------------------------------------------------------------------------------
Set              term.set(s, k, v)       Change section of termhelper.lib.js
On               term.on(evt, method)    Overwrite default event handler with custom method
Clear            term.Clear()            Clear terminal window
ClearLine        term.ClearLine()        Clear output from current line (clear prompt, does not clear input string)
getPrompt        term.getPrompt()        Returns the evaluated prompt string
Prompt           term.Prompt()           Output prompt string
Write            term.Write(text)        Send text to terminal
Writeln          term.Writeln(text)      Send text to terminal with line end out appended
CursorPos        term.CursorPos()        Returns an integer denoting cursor position
CursorTo         term.CursorTo(pos)      Move the cursor to a specified position on the line
Run              term.Run(command)       Run shell commands from your node apps
Eval             term.Eval(command)      Evaluate string as JavaScript
Echo             term.Echo(obj)          Parse an object and output to cli
log.set          term.log.set()          Set log options
log.Write        term.log.Write(data)    Write data to log file
log.Writeln      term.log.Writeln(data)  Write data to log and move to next line
Version          term.Version()          Return termhelper version number
Show             term.Show(key)          Return termhelper information (key denotes which peice of information to show e.g name, version etc)
formatDate       term.formatDate(f, s)   Return the date with the format 'f' using the splitter 's'

** Processed Input

Line inputs processed from the terminal (see aliases)

** Prompt String

The prompt string sets the prompt that is dispayed for command entry. The string can be a literal string or a JavaScript string to be evaluated. The prompt string can be changed by editing the settings.prompt variable in termhelper.lib.js, using the set method to change the settings.prompt variable or by calling the prompt alias at the command line.

You may also use the following notation to insert information to the prompt string (see globalVars for more info):

%d		The date with the format as defined in termhelper.lib.js
%p		The current command line path
%t		The time, this uses the systems locale time string
%v		Termhelper version number
%@		The command history position number (changes when cycling through history)
%#		The history length (command number)

Examples:

In termhelper.lib.js:

settings: {
  prompt: "%p [%@]> ";
  ...
}

In your application:

term.set("settings", "prompt", "[%d]%p> ");

On the command line:

prompt __dirname + '> ';

Note: The values set in these examples could be set using any of the prompt methods.

** App object

A blank object called app has been added to store custom variables for displaying in a prompt or other evaluated commands.

prompt this.app.name + "> "

** Module object

Contains details about the termhelper module for use with evaluated methods and commands

prompt this.module.name + " " + this.module.version + "> "

** Complimentary Modules

Colors: this module will allow terminal colors and styles to be used. To use with termhelper simply setup each as normal then use: term.write('test'.red); Or term.write(colors.red('test'));

Other Projects * AuroraChat Server A full featured IRCD like modular chat server with SSL and individual client encryption for secure group chat. Coming soon.