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.