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. Thusprintf("%4J", obj);
is equivalent toprintf("%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 everywidth
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 is0
. If0
, 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 ofi
or leading white space on first line.
.w
wherew
is the optional length of each line (default80
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
- wherew
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
, or0x0
-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>
*/
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 inoldbuf
to start writing data. Default is the end ofoldbuf
. 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 andoldbuf
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"]}
becomeskey1=val1&key1=val2
.
"bracket"
- similar to repeat, except url encoded[]
is appended to the keys. Example:{key1: ["val1", "val2"]}
becomeskey1%5B%5D=val1&key1%5B%5D=val2
.
"comma"
- One key with corresponding values separated by a,
(comma). Example:{key1: ["val1", "val2"]}
becomeskey1=val1,val2
.
"json"
- encode array as JSON. Example:{key1: ["val1", "val2"]}
becomeskey1=%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
orbracket
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.
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 untilnchar
chars are input. Unlikefread(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. |
If negative, start position to read from end of file. |
||
rLength |
Number |
If greater than zero, amount in bytes to be read. |
If 0 or negative, position from end of file to stop reading. |
||
return_str |
Boolean |
If not set, or |
If |
- 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'
*/
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,
"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 settrue
if the file is a symbolic link.
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 currentPATH
environment variable. -
options
- Object. Containing the following properties:-
timeout
- Number. Maximum amount of time in milliseconds before the process is automatically killed. Valid ifbackground
is unset orfalse
. -
killSignal
- Number. If timeout is reached, use this signal. Valid ifbackground
is unset orfalse
and atimeout
value is set. -
background
- Boolean. Whether to execute detached and return immediately. Iftrue
,stdout
andstderr
below will be set tonull
. Anytimeout
value is ignored. -
env
- Object. Key/value pairs to be used as environment variables for the executed process. -
appendEnv
- Boolean. Only valid ifenv
is provided. Iffalse
(the default), only the environment variables given inenv
will be available. Iftrue
, variables provided inenv
will be appended to process.env. Duplicate keys in process.env are replaced with the value fromenv
. -
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.
-
-
argn
- String/Number/Object/Boolean/Null - Arguments to be passed tocommand
. Non-Strings are converted to a String (e.g. “true”, “null”, “42” or for Object, the equivalent ofJSON.stringify(obj)
).
- Return Value:
-
Object. Properties as follows:
-
stdout
- String. Output of command ifbackground
is not settrue
. Otherwisenull
. -
stderr
- String. stderr output of command ifbackground
is not settrue
. Otherwisenull
. -
exitStatus
- Number. The returned exit status of the command. -
timedOut
- Boolean. Set true if the program was killed aftertimeout
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
}
*/
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 (defaultfalse
) which, iftrue
will only update the timestamp, and will not create a non-existingfile
. -
setAccess
is a Boolean (defaulttrue
). Whether to update access timestamp of file. -
setModify
is a Boolean (defaulttrue
). Whether to update modification timestamp of file. -
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
orObject
(excluding any of the other types of Objects such asNull
,Array
orFunction
) .
dateFmt¶
Format a date String.
Usage:
var datestr = rampart.utils.dateFmt(format[, date][, input_format])
Where:
"%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 theinput_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:
- Return Value:
-
A JavaScript Date.
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 inserver.start()
for therampart-server
module. If not specified, or not loaded, same asrampart.utils.stdout
. - rampart.utils.errorLog:
-
A handle that corresponds to the
errorLog
file option inserver.start()
for therampart-server
module. If not specified, or not loaded, same asrampart.utils.stderr
.
The
rampart.utils.stdin
handle includes 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 - iftrue
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
|
- Return Value:
-
A Buffer or a String if
returnString
istrue
.
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 |
- 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 offile
is returned, subsequent calls tonext
will returnnull
.
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 – thecity128
hash concatenated with themurmur
hash.
-
-
function
- Alias fortype
. -
returnBuffer
- a Boolean, iftrue
, the hash will be returned as the binary value of the hash in a a Buffer. Iffalse
(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 samename
in order to retrieve the same hll object. -
hllBufferData
is a Buffer - The raw hll buffer to initialize the newhll
Object with data previously extracted using getBuffer below. -
merge_hll1
,merge_hll2
, etc. are hll Objects created withnew 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
, andgetBuffer
.
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() orrampart.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.