rampart.utils¶

Utility functions are provided in the global rampart.utils Object. These functions bring file io and other functionality to Duktape JavaScript.

License¶

The modified printf code used in the rampart utilities and in the Rampart Server Module is provided by Marco Paland under the MIT License.

The %!H HTML escape decoding is provided by Christoph Gärtner under the Boost License.

The utilities are included in Rampart JavaScript and as such are licensed under the same MIT license.

General Utilities¶

printf¶

Print a formatted string to stdout. Provides C-like printf(3) functionality in JavaScript.

Usage:

                          rampart.utils.printf(fmt, ...)

                        

Return Value:: Number. The length in bytes of the printed string.

Standard formats: Most of the normal flags and formats are respected. See standard formats and flags from printf(3).

Extended (non-standard) formats:

%s - corresponding argument is treated as a String (converted/coerced if necessary; Objects are converted the same as for %J and Buffers are printed as is).

%S - same as %s except an error is thrown if the corresponding argument is not a String.

%J - print Object as JSON. An optional width (i.e. printf("%4J", obj);) may be given which will print with new lines and indentation of the specified amount. Thus printf("%4J", obj); is equivalent to printf("%s", JSON.stringify(obj, null, 4) );.

%B - print contents of a Buffer or String as base64.

If ! flag present, it decodes a Buffer or String containing base64 (throws an error if not valid base64).

If a width is given (e.g. %80B), a newline will be printed after every width characters.

If the - flag is present and ! is not present, the output will be a modified url safe base64 (using - and _ in place of + and /).

If the 0 flag is given (e.g. %0B or %-080B), and ! is not present, the output will not be padded with = characters.

%U - url encode (or if ! flag present, decode) a String.

%H - html encode (or if ! flag present, decode) a String.

%P - pretty print a String or Buffer. Expects text with white space. Format is %[!][-][i][.w]P where:

i is the optional level of indentation. Each output line will be indented by this amount. Default is 0. If 0, the indent level for each paragraph will match the indentation of the first line of the corresponding paragraph in the input text (number of spaces at beginning of the paragraph).

- when used with the ! flag optionally sets indentation to 0 on all lines regardless of i or leading white space on first line.

.w where w is the optional length of each line (default 80 if not specified).

! specifies, if present, that newlines are not converted to spaces (but text after newlines is still indented). In all cases, a double newline (“\n\n”) is considered a separator of paragraphs and is respected.

%w - a shortcut format for %!-.wP - where w is effectively unlimited. Remove all leading white space from each line and don’t wrap lines.

%C - like %c but prints multi-byte character. Example:

rampart.utils.printf("%C", 0xf09f9983); prints 🙃.

Requires a number, 1-4 bytes (0-4294967295, or 0x0-0xffffffff).

Example:

                          var uenc = "a+url+encoded+string.+%27%23%24%3f%27";

rampart.utils.printf("Encoded: %s\nDecoded: %!U\n", uenc, uenc);

/* expected output:
Encoded: a+url+encoded+string.+%27%23%24%3f%27
Decoded: a url encoded string. '#$?'
*/

var getty = "Four score and seven years ago our fathers\n" +
         "brought forth on this continent, a new nation,\n" +
         "conceived in Liberty, and dedicated to the proposition\n" +
         "that all men are created equal."

rampart.utils.printf("%5.40P\n", getty);
/* or
     rampart.utils.printf("%*.*P\n", 5, 40, getty);
*/

/* expected output:
     Four score and seven years ago our
     fathers brought forth on this
     continent, a new nation, conceived
     in Liberty, and dedicated to the
     proposition that all men are
     created equal.
*/

 var html =
 "<html>\n"+
 "  <body>\n"+
 "    <div>\n"+
 "      content\n"+
 "    </div>\n"+
 "  </body>\n"+
 "</html>\n";

 /* remove leading white space */
 /* rampart.utils.printf("%!-.1000P", html); */
 /* or more simply as */
 rampart.utils.printf("%w", html);

 /* expected output
 <html>
 <body>
 <div>
 content
 </div>
 </body>
 </html>
 */

                        

sprintf¶

Same as printf() except a String is returned

Return Value:: String. The formatted string.

bprintf¶

Same as sprintf() except a Buffer is returned.

Return Value:: Buffer. The formatted string as a Buffer.

abprintf¶

Same as bprintf() except a provided Buffer is resized and appended.

Usage:

                          var newBuf = abprintf(oldbuf[, start], fmt, ...);

                        

Where:

oldbuf is a Buffer - the Buffer to be appended.

start is an optional Number, where in oldbuf to start writing data. Default is the end of oldbuf. May be a negative number, signifying how many bytes from the end of the string to start.

fmt, ... - A format String and optional format parameters.

Return Value:: Buffer. The formatted string appended to oldbuf as a dynamic Buffer.
Note:: The Buffer oldbuf will be altered if it is a dynamic buffer. Otherwise, it will be copied and oldbuf remains unaltered.

hexify¶

Convert data to a hex string.

Usage:

                          var hexstring = rampart.utils.hexify(data [, upper]);

                        

Where data is the string of bytes (String or Buffer) to be converted and upper is an optional Boolean, which if true prints using upper-case A-F.

Return Value:: String. Each byte in data is converted to its two character hex representation.

Example: See dehexify below.

dehexify¶

Convert a hex string to a string of bytes.

Usage:

                          var data = rampart.utils.dehexify(hexstring);

                        

Return Value:: Buffer. Each two character hex representation converted to a byte in the binary string.

Example:

                          rampart.globalize(rampart.utils);

var s=sprintf("%c%c%c%c",0xF0, 0x9F, 0x98, 0x8A);

printf("0x%s\n", hexify(s) );
printf("%s\n", dehexify(hexify(s)) );

/* expected output:
0xf09f988a
😊
*/

                        

stringToBuffer¶

Performs a byte-for-byte copy of String into a Buffer. Also convert one Buffer to a Buffer of another type. See duk_to_buffer() in the Duktape documentation

Usage:

                          var buf = rampart.utils.stringToBuffer(data [, buftype ]);

                        

Where data is a String or Buffer and buftype is one of the following Strings:

"fixed" - returned Buffer is a “fixed” Buffer.

"dynamic" - returned Buffer is a “dynamic” Buffer.

If no buftype is given and data is a Buffer, the same type of Buffer is returned. If no buftype is given and data is a String, a “fixed” Buffer is returned.

See Duktape documentation for more information on different types of Buffers.

Return Value:: Buffer. Contents of String/Buffer copied to a new Buffer Object.

bufferToString¶

Performs a 1:1 copy of the contents of a Buffer to a String.

See duk_buffer_to_string() in the Duktape documentation

Usage:

                          var str = rampart.utils.bufferToString(data);

                        

Where data is a Buffer Object.

Return Value:: String. Contents of Buffer copied to a new String.

objectToQuery¶

Convert an Object of key/value pairs to a String suitable for use as a query string in an HTTP request.

Usage:

                          var qs = rampart.utils.objectToQuery(kvObj [, arrayOpt]);

                        

Where kvObj is an Object containing the key/value pairs and arrayOpt controls how Array values are treated. A String, one of the following:

"repeat" - default value if not specified. Repeat the key in the query string with each value from the array. Example: {key1: ["val1", "val2"]} becomes key1=val1&key1=val2.

"bracket" - similar to repeat, except url encoded [] is appended to the keys. Example: {key1: ["val1", "val2"]} becomes key1%5B%5D=val1&key1%5B%5D=val2.

"comma" - One key with corresponding values separated by a , (comma). Example: {key1: ["val1", "val2"]} becomes key1=val1,val2.

"json" - encode array as JSON. Example: {key1: ["val1", "val2"]} becomes key1=%5b%22val1%22%2c%22val2%22%5d.

Note that the values null and undefined will be translated as the Strings "null" and "undefined" respectively. Also values which themselves are Objects will be converted to JSON.

queryToObject¶

Convert a query string to an Object. Reverses the process, with caveats, of objectToQuery().

Usage:

                          var kvObj = rampart.utils.queryToObject(qs);

                        

Caveats:

All primitive values will be converted to Strings unless json was used.
If repeat or bracket was used to create the query string, all values will be returned as strings (even if an Array of Numbers was given to objectToQuery().
If comma was used to create the query string, no separation of comma separated values will occur and the entire value will be returned as a String.
If json was used, numeric values will be preserved as Numbers.
If the querystring contains object like notation (e.g. ?myvar[mykey]=myval&myvar[mykey2]=myval2), it will be converted into an Object;

Example:

                          var obj= {
  key1: null,
  key2: [1,2,3],
  key3: ["val1","val2"]
}

var type = [ "repeat", "bracket", "comma", "json" ];

for (var i=0; i<4; i++) {
    var qs = rampart.utils.objectToQuery(obj, type[i] );
    var qsobj = rampart.utils.queryToObject(qs);
    rampart.utils.printf("qToO(\n     '%s'\n    ) = \n%s\n", qs, JSON.stringify(qsobj,null,3));
}

/* expected output:
qToO(
     'key1=null&key2=1&key2=2&key2=3&key3=val1&key3=val2'
    ) =
{
   "key1": "null",
   "key2": [
      "1",
      "2",
      "3"
   ],
   "key3": [
      "val1",
      "val2"
   ]
}
qToO(

'key1=null&key2%5B%5D=1&key2%5B%5D=2&key2%5B%5D=3&key3%5B%5D=val1&key3%5B%5D=val2'
    ) =
{
   "key1": "null",
   "key2": [
      "1",
      "2",
      "3"
   ],
   "key3": [
      "val1",
      "val2"
   ]
}
qToO(
     'key1=null&key2=1,2,3&key3=val1,val2'
    ) =
{
   "key1": "null",
   "key2": "1,2,3",
   "key3": "val1,val2"
}
qToO(
     'key1=null&key2=%5b1%2c2%2c3%5d&key3=%5b%22val1%22%2c%22val2%22%5d'
    ) =
{
   "key1": "null",
   "key2": [
      1,
      2,
      3
   ],
   "key3": [
      "val1",
      "val2"
   ]
}
*/

                        

getchar¶

Get one or more characters from stdin.

Usage:

                          var instr = rampart.utils.getchar([nchar]);

                        

Where nchar is an optional number, the number of characters to read from stdin. The default is 1.

Return Value:: A String of length nchars.
Note:: If stdin is from an interactive terminal, execution will be paused until nchar chars are input. Unlike fread(stdin); below, the terminal will be set to return characters in without waiting for a newline.

readFile¶

Read the contents of a file.

Usage:

                          var contents = rampart.utils.readFile({
   file: filename
   [, offset: offsetPos]
   [, length: rLength]
   [, returnString: return_str]
});

/* or */

var contents = rampart.utils.readFile(filename [, offsetPos [, rLength]] [, return_str]);

                        

Where values filename and optional values offsetPos, rLength and/or return_str are:

Argument	Type	Description
filename	String	Path to the file to be read
offsetPos	Number	If positive, start position to read from beginning of file.
offsetPos	Number	If negative, start position to read from end of file.
rLength	Number	If greater than zero, amount in bytes to be read.
rLength	Number	If 0 or negative, position from end of file to stop reading.
return_str	Boolean	If not set, or `false`, return a Buffer.
return_str	Boolean	If `true`, return contents as a String. May be truncated if the file contains null characters.

Return Value:: Buffer or String. The contents of the file.

Example:

                          rampart.utils.fprintf("/tmp/file.txt","This is a text file\n");

var txt = rampart.utils.readFile({
   filename:  "/tmp/file.txt",
   offset:    10,
   length:    -6,
   retString: true
});

/* or var txt = rampart.utils.readFile("/tmp/file.txt", 10, -6, true); */

rampart.utils.printf("'%s'\n", txt);

/* expected output:
'text'
*/

                        

Note:: If return_str is true and offsetPos and/or rLength are set, the returned String may be shortened to ensure that the return value is a valid UTF-8 string. If that behavior is not desired, returning a Buffer and converting to a string with, e.g. sprintf() or bufferToString() will bypass the UTF-8 character/byte boundary check.

trim¶

Remove whitespace characters from the beginning and end of a String.

Usage:

                          var trimmed = rampart.utils.trim(str);

                        

Where str is a String.

Return Value:: String. str with whitespace removed from beginning and end.

Example:

                          var str = "\n a line of text \n";
rampart.utils.printf("'%s'", rampart.utils.trim(str));
/* expected output:
'a line of text'
*/

                        

stat¶

Return information on a file.

Usage:

                          var st = rampart.utils.stat(file);

                        

Where file is a String (name of file).

Return Value:: Boolean/Object. false if file does not exist. Otherwise an Object with the following properties:

                          {
   "dev":               Number,
   "ino":               Number,
   "mode":              Number,
   "nlink":             Number,
   "uid":               Number,
   "gid":               Number,
   "rdev":              Number,
   "size":              Number,
   "blksize":           Number,
   "blocks":            Number,
   "atime":             Date,
   "mtime":             Date,
   "ctime":             Date,
   "readable":          Boolean,
   "writable":          Boolean,
   "executable":        Boolean,
   "owner":             String,
   "group":             String,
   "isBlockDevice":     Boolean,
   "isCharacterDevice": Boolean,
   "isDirectory":       Boolean,
   "isFIFO":            Boolean,
   "isFile":            Boolean,
   "isSocket":          Boolean
}

                        

See stat (2) for the meaning of each property. The is* Booleans are set to true if the corresponding file property is true.

Example:

                          var st = rampart.utils.stat("/tmp/file.txt");

if(st) {
   /* print file mode as octal number */
   rampart.utils.printf("%o\n", st.mode & 0777)
} else {
   console.log("file /tmp.file.txt does not exist");
}
/* expected output: 644 */

                        

lstat¶

Same as stat() except if file is a link, return information about the link itself.

Return Value:: Same as stat() with the addition of the property isSymbolicLink which is set true if the file is a symbolic link. readable and writable refer to the link, not the target.

exec¶

Run an executable file.

Usage:

                          var ret = rampart.utils.exec(command [, options] [,arg1, arg2, ..., argn] );

                        

Where:

command - String. An absolute path to an executable or the name of an executable that may be found in the current PATH environment variable.
options - Object. Containing the following properties:
- timeout - Number. Maximum amount of time in milliseconds before the process is automatically killed. Valid if background is unset or false.
- killSignal - Number. If timeout is reached, use this signal. Valid if background is unset or false and a timeout value is set.
- background - Boolean. Whether to execute detached and return immediately. If true, stdout and stderr below will be set to null. Any timeout value is ignored.
- env - Object. Key/value pairs to be used as environment variables for the executed process.
- appendEnv - Boolean. Only valid if env is provided. If false (the default), only the environment variables given in env will be available. If true, variables provided in env will be appended to process.env. Duplicate keys in process.env are replaced with the value from env.
- stdin - String or Buffer. If specified, the content of the String or Buffer is piped to the command as stdin.
- returnBuffer - Boolean. Whether content is returned in a Buffer rather than a String. Useful for capturing binary data output.
- args - Array. An array of arguments to be passed to the executable. If arguments are also given as parameters to exec(), the Array of arguments are appended.
- changeDirectory - String. Change the working directory to value before executing.
- cd - Alias for changeDirectory .
argn - String/Number/Object/Boolean/Null - Arguments to be passed to command. Non-Strings are converted to a String (e.g. “true”, “null”, “42” or for Object, the equivalent of JSON.stringify(obj)).

Return Value:

Object. Properties as follows:

stdout - String. Output of command if background is not set true. Otherwise null.
stderr - String. stderr output of command if background is not set true. Otherwise null.
exitStatus - Number. The returned exit status of the command.
timedOut - Boolean. Set true if the program was killed after timeout milliseconds has elapsed.
pid - Number. Process id of the executed command.

shell¶

Execute String in a bash shell. Equivalent to rampart.utils.exec("bash", "-c", shellcmd);.

Usage:

                          var ret = rampart.utils.shell(shellcmd[, options]);

                        

Where shellcmd is a String containing the command and arguments to be passed to bash and options are the same as specified for exec.

Return Value:: Same as exec().

Example:

                          var ret = rampart.utils.shell('echo -n "hello"; echo "hi" 1>&2;');
console.log(JSON.stringify(ret, null, 3));

/* expected output:
{
   "stdout": "hello",
   "stderr": "hi\n",
   "timedOut": false,
   "exitStatus": 0,
   "pid": 24658
}
*/

                        

forkpty¶

Run an executable file in a pseudo-terminal with unbuffered IO. IO is performed asynchronously in the event loop of the current thread.

Usage:

                          var pty = rampart.utils.forkpty(command [, options] [,arg1, arg2, ..., argn] );

                        

Where:

command - String. An absolute path to an executable or the name of an executable that may be found in the current PATH environment variable.
options - Object. Containing the following properties:
- env - Object. Key/value pairs to be used as environment variables for the executed process.
- appendEnv - Boolean. Only valid if env is provided. If false (the default), only the environment variables given in env will be available. If true, variables provided in env will be appended to process.env. Duplicate keys in process.env are replaced with the value from env.
argn - String/Number/Object/Boolean/Null - Arguments to be passed to command. Non-Strings are converted to a String (e.g. “true”, “null”, “42” or for Object, the equivalent of JSON.stringify(obj)).

Return Value:

Object. Properties as follows:

read - Function. Read data from the stdout of the executed process.
pty.read([buffersize [, maxread]] [, retstring]);
Where: buffersize defaults to 4096, maxread defaults to unlimited and retstring (default false for Buffer) is a Boolean - whether the return contents should be converted to String.
write - Function. Write data to the stdin of the executed process.
```
pty.write([buffer|string]);
```
resize - Function. Set a new size for the pseudo-terminal.
pty.resize(width, height);
Where: width and height are Numbers - number of character rows and columns.
on - Function: Two events are currently allowed: "data" and "close". If, "data" is specified, when new data is available to be read, the provided callback function will be called. If "close" is specified, the provided callback function will be called when the process exits.
```
pty.on(['data'|'close'], callback);
```

An example for using forkpty() with websockets to run a terminal in a web browser can be found here.

kill¶

Terminate a process or send a signal.

Usage:

                          var ret = rampart.utils.kill(pid [, signal]);

                        

Where pid is a Number, the process id of process which will receive the signal and signal is a Number, the signal to send. If signal is not specified, 15 (SIGTERM) is used. See manual page for kill(1) for a list of signals, which may vary by platform. Setting signal to 0 sends no signal, but checks for the existence of the process identified by pid.

Return Value:: Boolean. true if the signal was successfully sent. false if there was an error or process does not exist.

Example:

                          var ret = rampart.utils.exec("sleep", "100", {background:true});
var pid=ret.pid;

if (rampart.utils.kill(pid,0)) {
    console.log("process is still running");
    rampart.utils.kill(pid);
    rampart.utils.sleep(0.2);
    if( rampart.utils.kill(pid,0) == 0 )
       console.log("and now is dead");
} else
    console.log("not running");
/* expected output:
   process is still running
   and now is dead
*/

                        

getcwd¶

Return the current working directory as a String.

Usage:

                          rampart.utils.getcwd();

                        

Return Value:: A String, the current working directory of the script.

chdir¶

Change the current working directory.

Usage:

                          rampart.utils.chdir(path);

                        

Where path is a String, the location of the new working directory. This command throws an error if it fails to change to the specified directory.

Return Value:: undefined.

mkdir¶

Create a directory.

Usage:

                          rampart.utils.mkdir(path [, mode]);

                        

Where path is a String, the directory to be created and mode is a Number or String, the octal permissions mode. Any parent directories which do not exist will also be created. Throws error if lacking permissions or if another error was encountered.

Note that mode is normally given as an octal. As such it can be, e.g., 0755 (octal number) or "755" (String representation of an octal number), but 755, as a decimal number will give the octal 01363, which is likely not what was intended.

Return Value:: undefined.

rmdir¶

Remove an empty directory.

Usage:

                          rampart.utils.rmdir(path [, recurse]);

                        

Where path is a String, the directory to be removed and recurse is an optional Boolean, which if true, parent directories explicitly present in path will also be removed. Throws an error if the directory cannot be removed (.e.g., not empty or lacking permission).

Return Value:: undefined.

Example:

                          /* make the following directories in the
   current working directory             */
rampart.utils.mkdir("p1/p2/p3",0755);

/* remove the directories recursively */
rampart.utils.rmdir("p1/p2/p3", true);

                        

readDir¶

Get listing of directory files.

Usage:

                          var files = rampart.utils.readdir(path [, showhidden]);

                        

Where path is a String, the directory whose content will be listed and showhidden is a Boolean, which if true, files or directories beginning with . (hidden files) will be included in the return value.

Return Value:: Array. An Array of Strings, each filename in the directory.

copyFile¶

Make a copy of a file.

Usage:

                          rampart.utils.copyFile({src: source, dest: destination [, overwrite: overWrite]});

/* or */

rampart.utils.copyFile(source, destination [, overWrite]);

Where source is a String, the file to be copied, destination is a String, the name of the target file and optional overWrite is a Boolean which if true will overwrite destination if it exists.

Return Value:: undefined.

rmFile¶

Delete a file.

Usage:

                          rampart.utils.rmFile(filename);

                        

Where filename is a String, the name of the file to be removed.

Return Value:: undefined.

link¶

Create a hard link.

Usage:

                          rampart.utils.link({src: sourceName, target: targetName});

/* or */

rampart.utils.link(sourceName, targetName);

Where sourceName is the existing file and targetName is the name of the to-be-created link.

Return Value:: undefined.

symlink¶

Create a soft (symbolic) link.

Usage:

                          rampart.utils.symlink({src: sourceName, target: targetName});

/* or */

rampart.utils.symlink(sourceName, targetName);

Where sourceName is the existing file and targetName is the name of the to-be-created symlink.

Return Value:: undefined.

chmod¶

Change the file mode bits of a file or directory.

Usage:

                          rampart.utils.chmod(path [, mode]);

                        

Where path is a String, the file or directory upon which to be operated and mode is a Number or String, the octal permissions mode. Any parent directories which do not exist will also be created. Throws error if lacking permissions or if another error was encountered.

Note that mode is normally given as an octal. As such it can be, e.g., 0755 (octal number) or "755" (String representation of an octal number), but 755, as a decimal number will likely not work as intended.

Return Value:: undefined.

realPath¶

Find the canonical form of a file system path. The path or file must exist.

Usage:

                          rampart.utils.realPath(path);

                        

Where path is a String, not necessarily in canonical form.

Return Value:: A String, the canonical form of the path.

touch¶

Create an empty file, or update the access timestamp of an existing file.

Usage:

                          rampart.utils.touch(file);

/* or */

rampart.utils.touch({
   path: file
   [, nocreate: noCreate]
   [, setaccess: setAccess]
   [, setmodify: setModify]
   [, reference: referenceFile]
});

                        

Where:

file is a String, the name of the file upon which to operate,
noCreate is a Boolean (default false) which, if true will only update the timestamp, and will not create a non-existing file.
setAccess is a Boolean (default true), a Date Object, or an Number (seconds since unix epoch). Update access time of the file to specified date or current date if true. Do not update if false.
setModify is a Boolean (default true), a Date Object, or an Number (seconds since unix epoch). Update modification time of the file to specified date or current date if true. Do not update if false.
referenceFile is a String. If specified, the named file’s access and modification timestamps will be used rather than the current time/date.

Return Value:: undefined.

rename¶

Rename or move a file.

Usage:

                          rampart.utils.rename(source, destination);

                        

Where source is a String, the file to be renamed or moved, destination is a String, the name of the target file.

Return Value:: undefined.

sleep¶

Pause execution for specified number of seconds.

Usage:

                          rampart.utils.sleep(seconds);

                        

Where seconds is a Number. Seconds may be a fraction of seconds. Internally nanosleep is used.

Example:

                          /* wait 1.5 seconds */
rampart.utils.sleep(1.5);

getType¶

Get the type of variable. A simplified but more specific version of typeof.

Usage:

                          var type = rampart.utils.getType(myvar);

                        

Return Value:: A String, one of String, Array, Number, Function, Boolean, Buffer (any buffer type), Nan, Null, Undefined, Date or Object (excluding any of the other types of Objects such as Null, Array or Function) .

dateFmt¶

Format a date String.

Usage:

                          var datestr = rampart.utils.dateFmt(format[, date][, input_format])

                        

Where:

format is a strftime style format String.

date is an optional date as a String, Number (seconds since 1970-01-01), or a Date. The default value is the current time.

input_format is an optional format if date is a String, in the style of strptime. The default is to try the following in order:

                          "%Y-%m-%d %H:%M:%S %z"
"%A %B %d %H:%M:%S %Y %z"
"%Y-%m-%d %H:%M:%S"
"%A %B %d %H:%M:%S %Y"
"%Y-%m-%dT%H:%M:%S"
"%c"

                        

Return Value:: The formatted date as a String.

Note:

Millisecond notation in the string in the form of .123 or .123Z is disregarded.

The return String is a date in local time.

If year or year/month/day formats are missing, the current year or date respectively is assumed.

If the %z format is specified in the input_format String, the date will be converted from that timezone offset to local time.

The %Z format has no effect on the time zone.

Example:

                          rampart.globalize(rampart.utils);

var d = new Date();

printf( "%s\n%s\n%s\n%s\n%s\n%s\n%s\n%s\n",
    dateFmt("%c", "Mon Jul 26 12:00:01 2021"),
    dateFmt("%c", "Mon Jul 26 12:00:01 2021 -04:00"),
    dateFmt("%c", "1999-12-31 23:59:59 -0000"),
    dateFmt("%c", "2020", "%Y"),
    dateFmt("%c", d),
    dateFmt("%Y-%m-%d"),
    dateFmt("%m/%d/%Y %H:%M:%S %Z", 946713599),
    dateFmt("Today's lunch:  %c", "12:15", '%H:%M')
);

/* Expected output:
Mon Jul 26 12:00:01 2021
Mon Jul 26 09:00:01 2021
Fri Dec 31 15:59:59 1999
Wed Jan  1 00:00:00 2020
Tue Jul 27 01:06:57 2021
2021-07-27
12/31/1999 23:59:59 PST
Today's lunch:  Tue Jul 27 12:15:00 2021
*/

                        

scanDate¶

Scan a date String and return a JavaScript date.

Usage:

                          var mydate = rampart.utils.scanDate(dateString[, default_offset][, input_format]);

                        

Where:

dateString is the same as date (as a String) in dateFmt above.

default_offset is the time zone offset in seconds to use if not provided in dateString. The default is 0 (UTC).

input_format is the same as in dateFmt above.

Return Value:: A JavaScript Date.

use¶

Shortcut and alternative for importing modules with require.

Usage:

                          rampart.globalize(rampart.utils);//put utils in the global namespace

var Sql = use.sql; //same as var Sql = require("rampart-sql");

The use Object is a proxy object which uses the property name referenced (here "sql) and searches for a module named "rampart-sql". Failing that it will search for a module named ("sql"). It will then call the require function to import and return that value. If no module can be found, it will throw an error.

Return Value:: The exported module.

load¶

Same as use above except that the property name is also put in the global namespace.

Example:

                          rampart.globalize(rampart.utils);//put utils in the global namespace

load.curl;  //same as global.curl = require("rampart-curl");

var res = curl.fetch("http...");

Note:: The file name of the module must be lowercase, while the variable name may be mixed case. Example: load.Sql; is equivalent to global.Sql=require("rampart-sql");.
Caveat:: This cannot be used to load a module whose name contains illegal JavaScript variable name characters. Thus, load["my@mod"] will not work since '@' is not legal in javaScript even though it is legal in a file name. However '-' and '.' characters will be replaced with '_'. Thus, load["rampart-curl.so"] will load the Curl Module and put it in the global namespace similar to var rampart_curl_so = require("rampart-curl.so").

File Handle Utilities¶

The functions fprintf (), fseek(), rewind(), ftell(), fflush(), fread(), fgets(), fwrite(), and readLine() take a filehandle, which may be obtained using fopen().

Calling Methods:

The above listed functions (functions which take filehandles) may be called using one of two alternative syntaxes.

                            var handle = rampart.utils.fopen(filename, mode);

rampart.utils.fprintf(handle, fmt, ...);

/* or */

handle.fprintf(fmt, ...);

The return value for each of the file handle functions is the same for either syntax, with the exception that fseek(), rewind() and fflush() return undefined in the first syntax and handle in the second.

Below, only the first syntax is documented.

Pre-opened file handles:

rampart.utils.stdin:: A handle that corresponds to the UNIX standard in stream.
rampart.utils.stdout:: A handle that corresponds to the UNIX standard out stream.
rampart.utils.stderr:: A handle that corresponds to the Unix standard error stream.
rampart.utils.accessLog:: A handle that corresponds to the accessLog file option in server.start() for the rampart-server module. If not specified, or not loaded, same as rampart.utils.stdout.
rampart.utils.errorLog:: A handle that corresponds to the errorLog file option in server.start() for the rampart-server module. If not specified, or not loaded, same as rampart.utils.stderr.

The rampart.utils.stdin handle includes in its properties the fread(), fgets() and readLine() functions while the other four include the fprintf(), fflush() and fwrite() functions. Example:

                            var line, inf = rampart.utils.stdin.readLine();

while ( line = inf.next() )
   rampart.utils.stdout.fprintf("%s", line); //same as rampart.utils.printf

fopen¶

Open a filehandle for use with fprintf(), fclose(), fseek(), rewind(), ftell(), fflush() fread(), fgets(), fwrite() and readLine().

Return Value:: Object. An object which opaquely contains the opened file handle along with the above functions.

Usage:

                          var handle = rampart.utils.fopen(filename, mode);

                        

Where filename is a String containing the file to be opened and mode is a String (one of the following):

"r" - Open text file for reading. The stream is positioned at the beginning of the file.
"r+" - Open for reading and writing. The stream is positioned at the beginning of the file.
"w" - Truncate file to zero length or create text file for writing. The stream is positioned at the beginning of the file.
"w+" - Open for reading and writing. The file is created if it does not exist, otherwise it is truncated. The stream is positioned at the beginning of the file.
"a" - Open for appending (writing at end of file). The file is created if it does not exist. The stream is positioned at the end of the file.
"a+" - Open for reading and appending (writing at end of file). The file is created if it does not exist. The initial file position for reading is at the beginning of the file, but output is always appended to the end of the file.

fclose¶

Close a previously opened handle Object opened with fopen().

Example:

                          var handle = rampart.utils.fopen("/tmp/out.txt", "a");

...

rampart.utils.fclose(handle);

  /* or */

handle.fclose();

Return Value:: undefined.

fprintf¶

Same as printf() except output is sent to the file provided by a String or filehandle Object opened and returned from fopen().

Usage:

                          var filename = "/home/user/myfile.txt";

var output = rampart.utils.fopen(filename, mode);
rampart.utils.fprintf(output, fmt, ...);
rampart.utils.fclose(output);

/* or */

var output = filename;
rampart.utils.fprintf(output, [, append], fmt, ...);
/* file is automatically closed after function returns */

                        

Where:

output may be a String (a file name), or an Object returned from fopen().
fmt is a String, a printf() format.
append is an optional Boolean - if true and output is a file name, append instead of overwrite an existing file.

Return Value:: A Number. The length in bytes of the printed string.

Example:

                          rampart.globalize(rampart.utils);

var handle = fopen("/tmp/out.txt", "w+");
fprintf(handle, "A number: %d\n", 123);
fclose(handle);

/* OR */

fprintf("/tmp/out.txt", "A number: %d\n", 123); /* implicit fclose */

fseek¶

Set file position for file operations.

Usage:

                          rampart.utils.fseek(handle, offset[, whence]);

                        

Argument	Type	Description
handle	Object	A handle opened with fopen()
offset	Number	offset in bytes from whence
whence	String	“seek_set” - measure offset from start of file (default)
		“seek_cur” - measure offset from current position
		“seek_end” - measure offset from end of file.

Return Value:: undefined

Example

                          rampart.globalize(rampart.utils,
  ["fopen","printf","fprintf","fseek","fread"]);

var handle = fopen("/tmp/out.txt", "w+");

fprintf(handle, "123def");

fseek(handle, 0, "seek_set");

fprintf(handle, "abc");

fseek(handle, 0, "seek_set");

var out=fread(handle);

printf("'%s'\n", out);
/*
expect output:
'abcdef'
*/

fclose(handle);

rewind¶

Set the file position to the beginning of the file. It is equivalent to:

                          rampart.utils.fseek(handle, 0, "seek_set")

                        

Usage:

                          rampart.utils.rewind(handle);

                        

Return Value:: undefined

ftell¶

Obtain the current value of the file position for the handle opened with fopen().

Usage:

                          var pos = rampart.utils.ftell(handle);

                        

Return Value:: Number. Current position of handle.

fflush¶

For output file handles opened with fopen(), or for stdout/stderr/accessLog/errorLog, fflush() forces a write of buffered data.

Usage:

                          rampart.utils.fflush(handle);

                        

Return Value:: undefined

Example:

                          /* normally a flush happens automatically
   when a '\n' is printed.  Since we are using
   '\r', flush manually                        */

for (var i=0; i< 10; i++) {
   rampart.utils.printf("doing #%d\r", i);
   rampart.utils.fflush(rampart.utils.stdout);
   rampart.utils.sleep(1);
}

rampart.utils.printf("blast off!!!\n");

                        

fread¶

Read data from a file, handle opened with fopen() or the pre-opened handle stdin.

Usage:

                          var data = rampart.utils.fread([handle|file] [, max_size [, chunk_size [,returnString]]]);

                        

Argument	Type	Description
handle	Object	A handle opened with fopen()
file	String	A filename – file will be auto opened and closed
max_size	Number	Maximum number of bytes to read. Unlimited if not specified.
chunk_size	Number	Initial size of return Buffer and number of bytes to read at a time. If the total number of bytes read is greater, the buffer grows as needed. If total bytes read is less, the returned buffer will be reduced in size to match. Default is 4096 if not specified.
returnString	Boolean	Whether return value is returned as a String. Default is `false`.

Return Value:: A Buffer or a String if returnString is true.

fgets¶

Usage:

                          var data = rampart.utils.fgets([handle|file] [, max_size]);

                        

Read data from file, up to max_size bytes (default 1), stopping at the and including the first \n or the end of the file.

Return Value:: A String.

fwrite¶

Write data to a file, a handle opened with fopen() or a pre-opened output handle (stdout/stderr/accessLog/errorLog). If using a handle, the start of the write will be the current position based on how the file was opened and whether any seeks have been performed. If using a file name, the append parameter will determine whether the file is appended or truncated.

Usage:

                          var nbytes = rampart.utils.fwrite([handle|file], data [, max_bytes][, append]);

                        

Argument	Type	Description
handle	Object	A handle opened with fopen()
file	String	A filename – file will be auto opened and closed
data	Buffer/ String	The data to be written.
max_bytes	Number	Maximum number of bytes to write. Buffer/ String length if not specified.
append	Boolean	If opened with `file` instead of `handle`, whether to append the file. Default is `false`, in which case the file will be truncated.

Return Value:: A Number. Number of bytes written.

readLine¶

Read a text file line-by-line.

Usage:

                          var rl = rampart.utils.readLine(file);
var line = rl.next();

Where file is a String (name of file to be read) or a file handle opened with with fopen() or rampart.utils.stdin. It returns a Object that contains the property next which is Function to retrieve and return the next line of text in the opened file.

Return Value:: An Object. Property next of the return Object is a Function which retrieves and returns the next line of text in the file. After the last line of file is returned, subsequent calls to next will return null.

Example:

                          var rl = rampart.utils.readLine("./myfile.txt");
var i = 0;
var line, firstline, lastline;

while ( (line=rl.next()) ) {
    if(i==0)
        firstline = rampart.utils.trim(line);
    i++;
    lastline = line;
}
rampart.utils.printf("%s\n%s\n", firstline, lastline);

/* expected output: first and last line of file "./myfile.txt" */

                        

Rand, Hash and HyperLogLog¶

Included in rampart.utils are several non-cryptographic functions which have been optimized for speed and ease of use.

Note that the rand() and hash() functions are not of cryptographic quality. For cryptographic quality hashes and random numbers, see The Rampart-Crypto Module.

rand¶

Generate a random number using a fast, non-cryptographic random number generator.

Usage:

                          var rn = rampart.utils.rand([min, max]);

   /* or */

var rn = rampart.utils.rand(max);

Where min is the floor and max is the ceiling (EXCLUSIVE) of the range of the random number to produce. If not provided, min and max default to 0.0 and 1.0 respectively.

Return Value:: A Number - the generated random number.

Note that if srand has not been called before use, the random number generator will be automatically seeded.

irand¶

Generate a random integer using a fast, non-cryptographic random number generator.

Usage:

                          var rn = rampart.utils.irand([min, max]);

   /* or */

var rn = rampart.utils.rand(max);

   /* or */

var rn = rampart.utils.rand([max[min,max]],callback);

Where min is the floor and max is the ceiling (INCLUSIVE) of the range of the random integers to produce. If not provided, min and max default to 0 and 99 respectively.

If provided, callback is a Function callback(r,i) where r is the random integer and i is the loop count. The Function will be called repeatedly until it returns false.

Return Value:: A Number - the generated random integer as a number. If a function is provided, returns undefined.

Note that if srand has not been called before use, the random number generator will be automatically seeded.

Note also because of JavaScript Number precision, the maximum and minimum max or min that may be provided is 9007199254740991 and -9007199254740991 respectively.

gaussrand¶

The gaussrand([sigma]) function returns a random Number using a fast, non-cryptographic random number generator and based on a normal distribution centered at zero (0.0), where sigma is one standard deviation. sigma is optional, defaulting to 1.0.

normrand¶

The normrand([scale]) function returns a random Number using a fast, non-cryptographic random number generator and based on a normal distribution centered at zero (0.0) and clamped between -scale and scale.

Similar to the gaussrand above. It is equivelant to:

                          var nrand = scale * rampart.utils.gaussrand(1.0)/5.0;

if(nrand>scale)
    nrand=scale;
else if (nrand < -scale)
    nrand = -scale;

                        

With a scale of 1.0 (the default), the distribution of numbers has a standard deviation of 0.2.

srand¶

Seed the random number generator for use with rand() above.

Usage:

                          rampart.utils.srand([random_num]);

                        

Where random_num is an optional number to seed the random number generator. If not specified, a number will be derived by reading /dev/urandom.

hash¶

Calculate the hash of data.

Usage:

                          var myhash = rampart.utils.hash(data,options);

                        

Where data is the data from which the hash is calculated and options is an Object with the following optional properties:

type - the type of hash to be calculated. A String, one of:
- "murmur" - A 64 bit hash using the murmur algorithm.
- "city" - A 64 bit hash using the city algorithm.
- "city128" - A 128 bit hash using the city algorithm. This is the default if not specified.
- "both" - A 192 bit hash – the city128 hash concatenated with the murmur hash.
function - Alias for type.
returnBuffer - a Boolean, if true, the hash will be returned as the binary value of the hash in a a Buffer. If false (the default), the return value will be a String - a hex encoded representation of the hash.

Return Value:: A String or Buffer - the computed hash.

hll¶

The hll function calculates a count of unique items based on Rampart’s own hyperloglog algorithm. It allocates and uses a 16384 byte buffer to calculate a distinct count of items added.

Usage:

                          var myhll = new rampart.utils.hll(name);

   /* or */

var myhll = new rampart.utils.hll(name, hllBufferData);

   /* or */

var myhll = new rampart.utils.hll(name [, hllBufferData], merge_hll1 [, merge_hll2, ...]);

Where:

name is an arbitrary String. It may be called again with the same name in order to retrieve the same hll object.
hllBufferData is a Buffer - The raw hll buffer to initialize the new hll Object with data previously extracted using getBuffer below.
merge_hll1, merge_hll2, etc. are hll Objects created with new rampart.utils.hll(name) to be merged into the new (blank) return hll Object in the same manner as merge below.

Return Value:: An opaque hll Object containing the following functions: add, addFile, count, merge, and getBuffer.

Note that an hll can be referred to from different threads in the Rampart Server. Each server thread may specify the same hll by using the same name. In addition, the below functions are thread-safe.

hll.add¶

Add a value or values to the hll.

Usage:

                          var myhll = new rampart.utils.hll(name);

myhll.add(value);

Where value is a String, Buffer or an array of Strings and/or Buffers.

Return Value:: The hll Object.

hll.addFile¶

Add values to the hll from a file, with each value on a separate line.

                          var myhll = new rampart.utils.hll(name);

myhll.addFile(file [, delim] );

Where

file is a String (name of file to be read) or a file handle opened with with fopen() or rampart.utils.stdin.
delim is an optional String, the first character of which is used as a line separator. The default value is "\n".

Return Value:

The hll Object.

hll.count¶

Get a current estimate count of distinct items added to the hll.

Usage:

                          var myhll = new rampart.utils.hll(name);

/* add items */
...

var mycount = myhll.count();

Return Value:: A Number, the estimated number of distinct items added to the hll.

hll.merge¶

Merge one or more hll files into the current hll in order to calculate an estimate of the number of distinct items of the union.

Usage:

                          var mergedHll = myhll.merge(myhll2 [, myhll3, ...]);

                        

Where myhll2, myhll3, etc. are hlls created with new rampart.utils.hll above.

Return Value:: The hll Object merged and updated with the provided hlls.

hll.getBuffer¶

Get the raw hll buffer as a JavaScript Buffer, which may be used to save the hll to disk using a command such as fwrite() above.

Usage:

                          var myhll = new rampart.utils.hll(name);

/* add items */
...

var hllbuf = myhll.getBuffer();

Return Value:: A Buffer 16384 bytes in length.