Rod's Node.js Utilities
A small library of utility functions and classes, primarily intended for use within server-side JavaScript (CoffeeScript).
Installation
The module is published as rods-util
on npm. It has no (runtime) external dependencies.
You can install rods-util directly through npm
:
npm install rods-util -g
(omit the -g
flag to install the module in a local node_modules
directory rather than the global one).
or by adding it as a dependency in your package.json
:
"dependencies": { "rods-util": "latest" }
Use
To use the module, simply require it:
var S = require('rods-util').StringUtil;
var hello = ' hello. ';
console.log(hello); // outputs: " hello. "
console.log(S.trim(hello)); // outputs: "hello."
See the test suite for more examples.
NOTE
New methods are being added to this module all the time. The documentation below probably isn't complete. See the test suite (./test/*.coffee
) for more examples and/or a more comprehensive and up-to-date description.)
Documentation
The module is divided into several independent collections of utility methods.
Currently (as of version 0.4.0) there are five collections:
-
ContainerUtil - provides utility methods that operate on containers like Arrays and Maps.
-
FileUtil - provides utility methods that operate on Files and related objects.
-
FunctorUtil - provides utility methods that manipulate functions and support function-oriented programming. (Here is where you'll find things like function composition, asynchronous loops, etc.)
-
Stopwatch - is a simple timer that can be used to time synchronous and asynchronous activities.
-
StringUtil - provides utility methods that operate on Strings.
Each is described in more detail below.
ContainerUtil
ContainerUtil
provides utility methods that operate on containers like Arrays and Maps.
Importing
To import the ContainerUtil
:
var CU = require('rods-util').ContainerUtil;
Methods
clone(map)
Creates a (shallow) copy of a map or object.
Example:
var original = { a: 1, b: 'two' };
var clone = CU.clone(original);
console.log('original.a is',original.a); // outputs: "original.a is 1"
console.log('clone.a is',clone.a); // outputs: "clone.a is 1"
clone.a = 2
console.log('original.a is',original.a); // outputs: "original.a is 1"
console.log('clone.a is',clone.a); // outputs: "clone.a is 2"
deep_clone(map)
Creates a (deep) copy of a map or object.
Example:
var original = { a: 1, b: 'two', c: { x:'alpha', y:'beta' } };
var clone = CU.deep_clone(original);
console.log('original.c.x is',original.c.x); // outputs: "original.c.x is alpha"
console.log('clone.c.x is',clone.c.x); // outputs: "clone.c.x is alpha"
clone.c.x = 'gamma'
console.log('original.c.x is',original.c.x); // outputs: "original.c.x is alpha"
console.log('clone.c.x is',clone.c.x); // outputs: "clone.c.x is gamma"
object_to_array(obj)
Creates an array of name/value pairs from an object or map.
Example:
var m = { a: 1, b: 'two' };
var a = CU.object_to_array(m);
console.log(a); // outputs: [ ['a',1], ['b','two'] ]
map_to_array(obj)
An alias for object_to_array
(which see).
object_values(obj)
Convert an object (map) into an array of values.
Example:
var m = { a: 1, b: 'two' };
var a = CU.object_vales(m);
// Array a is now: [ 1, 'two' ]
frequency_count
Converts an array into a map whose keys are the unique elements in the array and whose values are the number of times the element appears in array.
Example:
var a = [ 'a', 'b', 'c', 'b', 'c', 'b' ];
var c = CU.frequency_count(a);
console.log(c); // outputs: { a:1, b:3, c:2 }
sort_by_value
Converts a map into an array of name/value pairs, ordered by value.
Example:
var m = { a:2, c:1, b:3 };
var a = CU.sort_by_value(m);
console.log(a); // outputs: [ ['c',1], ['a',2], ['b',3] ]
sort_by_key
Converts a map into an array of name/value pairs, ordered by name (key).
Example:
var m = { a:2, c:1, b:3 };
var a = CU.sort_by_key(m);
console.log(a); // outputs: [ ['a',2], ['b',3], ['c',1] ]
FileUtil
FileUtil
provides utility methods that operate on files and related objects
Importing
To import the FileUtil
:
var FU = require('rods-util').FileUtil;
Methods
file_to_string(filename,[encoding],callback)
Read the file at filename
into a string.
var callback = function(err,contents) {
if(err) {
// an error occured
} else {
// process contents
}
};
FU.file_to_string('MY-FILE.TXT',callback);
file_to_string_sync(filename,[encoding])
A synchronous version of file_to_string
.
var contents = FU.file_to_string_sync('MY-FILE.TXT');
file_to_array(filename,options)
A convenience method that combines FileUtil.file_to_string
and StringUtil.string_to_array
.
var callback = function(err,lines) {
if(err) {
// an error occured
} else {
// process lines
}
};
FU.file_to_array('MY-FILE.TXT',callback);
Note that the options
map may contain an encoding as well as the various options supported by string_to_array
(which see).
file_to_array_sync(filename,options)
A synchronous version of file_to_array
.
var lines = FU.file_to_array_sync('MY-FILE.TXT');
FunctorUtil
Importing
To import the FunctorUtil
:
var FnU = require('rods-util').FunctorUtil;
Predicate Methods
Predicate methods provide utilties that operate on predicates (functions that return a boolean (true
/false
) value).
true()
Returns a function that yields a constant true
:
var predicate = FnU.true();
console.log( predicate() ); // outputs: true
false()
Returns a function that yields a constant false
:
var predicate = FnU.false();
console.log( predicate() ); // outputs: false
not(predicate)
Returns a function that yields the opposite of the given predicates.
var yes = FnU.true();
var predicate = FnU.not(yes);
console.log( predicate() ); // outputs: false
and(predicates...)
Returns a function that yields true
if and only if all the given predicates yield true
.
var p1 = FnU.true();
var p2 = FnU.false();
var p3 = FnU.true();
var predicate = FnU.and( p1, p2, p3 );
console.log( predicate() ); // outputs: false
var another = FnU.and( p1, p3 );
console.log( another() ); // outputs: true
or(predicates...)
Returns a function that yields true
if any of the given predicates yield true
.
var p1 = FnU.true();
var p2 = FnU.false();
var p3 = FnU.false();
var predicate = FnU.or( p1, p2, p3 );
console.log( predicate() ); // outputs: true
var another = FnU.and( p2, p3 );
console.log( another() ); // outputs: false
xor(predicates...)
Returns a function that yields true
if exactly one of the given predicates yield true
.
var p1 = FnU.true();
var p2 = FnU.false();
var p3 = FnU.true();
var p4 = FnU.false();
var predicate = FnU.or( p1, p2, p4 );
console.log( predicate() ); // outputs: true
var another = FnU.and( p1, p2, p3 );
console.log( another() ); // outputs: false
Function Methods
Function methods provide utilties that operate on functions.
transpose_arguments(function)
Given a function f(a,b)
returns a function equivalent to f(b,a)
.
Note that any arguments after the first two remain unchanged.
reverse_arguments(function)
Given a function f(a,b,c,...,z)
returns a function equivalent to f(z,...c,b,a)
.
compose(function,function,...)
Given the functions f
and g
, returns a function equivalent to f(g())
.
Given the functions f
, g
and h
, returns a function equivalent to f(g(h()))
, and so on.
for(init,condition,action,step,whendone)
Provides a functor-based for-loop.
Accepts 5 function-valued parameters:
- init - an initialization function (no arguments passed, no return value is expected)
- condition - a predicate that indicates whether we should continue looping (no arguments passed, a boolean value is expected to be returned)
- action - the action to take in each pas through the loop (no arguments passed, no return value is expected)
-
step - called at the end of every
action
, prior tocondition
(no arguments passed, no return value is expected) -
whendone - called at the end of the loop (when
condition
returnsfalse
), (no arguments passed, no return value is expected).
This method largely exists for symmetry with for_async
.
for_async(init,condition,action,step,whendone)
Executes an asynchronous for-loop.
Accepts 5 function-valued parameters:
- init - an initialization function (no arguments passed, no return value is expected)
- condition - a predicate that indicates whether we should continue looping (no arguments passed, a boolean value is expected to be returned)
- action - the action to take in each pas through the loop (no arguments passed, no return value is expected)
-
step - called at the end of every
action
, prior tocondition
(no arguments passed, no return value is expected) -
whendone - called at the end of the loop (when
condition
returnsfalse
), (no arguments passed, no return value is expected).
For example, the loop:
for(var i=0; i<10; i++) { console.log(i); }
Could be implemented as:
var i = 0;
init = function() { i = 0; };
cond = function() { return i < 10; };
actn = function(next) { console.log(i); next(); };
incr = function() { i = i + 1; };
done = function() { };
for_async(init,cond,actn,incr,done);
for_each(list,action,whendone)
Provides a functor-based for-each-loop.
Accepts 3 parameters:
- list - the array to iterate over
-
action - the function indicating the action to take (with the signature
(value,index,list)
) - whendone - called at the end of the loop
This method doesn't add much value over the built-in Array.forEach
, but exists for symmetry with for_each_async
.
for_each_async(list,action,whendone)
Executes an asynchronous for-each loop.
Accepts 3 parameters:
- list - the array to iterate over
-
action - the function indicating the action to take (with the signature
(value,index,list,next)
) - whendone - called at the end of the loop
This method largely exists for symmetry with for_each_async
.
For example, the loop
[0..10].foreach (elt,index,array)-> console.log elt
(That's in CoffeeScript, not JavaScript.)
Could be implemented as:
for_each_async [0..10], (elt,index,array,next)->
console.log elt
next()
add_callback(function)
For a given synchronous function f(a,b,c,...)
, returns a new function g(a,b,c,...,callback)
that is equivalent to callback(f(a,b,c,...))
.
The resulting method isn't asynchronous, but approximates the method signature and control flow used by asynchronous methods. This makes it easy to use a synchronous method where an asynchronous one is expected.
fork(methods,args_for_methods,callback)
Invokes each of the given asynchronous methods
immediately (passing the corresponding args_for_methods
, if any), and collects the response from each.
When all methods have invoked their callbacks, the specified callback
is invoked, passing an array containing the callback arguments from each method.
For example:
sum = (a,b,callback)->callback(a+b)
product = (a,b,callback)->callback(a*b)
identity = (a,b,callback)->callback(a,b)
methods = [ sum, product, identity ]
arguments = [ [ 3, 4], [ 3, 4 ], [ 3, 4 ] ]
FnU.fork methods, arguments, (results)->
console.log results[0] # yields: 7
console.log results[1] # yields: 12
console.log results[3] # yields: [ 3, 4 ]
(That's in CoffeeScript, not JavaScript.)
throttled_fork(max,methods,args_for_methods,callback)
Just like fork
, but ensures no more than max
of the methods are running at the same time.
StringUtil
trim(string)
Removes leading and trailing whitespace from the given string.
Both vertical (\n
, \r\f
, etc.) and horizonal (\t
,
, etc.) whitespace are removed.
var S = require('rods-util').StringUtil;
S.trim("\t hello \n"); // returns "hello"
Only the leading and trailing whitespace is removed. Whitespace that appears "within" the text of the string is left intact.
S.trim("\t hello \n\tworld \n"); // returns "hello \n\tworld"
strip_comment(str)
Equivalent to comment_stripper('#','\\')
, which see.
comment_stripper(comment_char,[escape_char])
Returns a function that will strip (inline) comments of the specified format from input strings.
The comment_char
and all subsquent characters (thru the end of the string) will be removed.
An instance of comment_char
that is immediately proceeded by escape_char
will be treated as a literal comment_char
. (Other instances of escape_char
will be treated as a literal escape_char
.)
Example:
var S = require('rods-util').StringUtil;
var f = S.comment_stripper('%','}');
f("This is text. % This is comment."); // returns ""This is text. "
f("25}% of 20 is 5"); // returns "25% of 20 is 5"
The StringUtil.strip_comment
method is a comment stripper with #
as the comment delimiter, and \
as the escape character. (Note that since \
is JavaScript's escape character, you must write "\\"
to pass "\"
. E.g.: f = S.comment_stripper('#','\\')
will create a comment stripper with a single backslash as the escape character.
escape_for_regexp(str)
Returns a representation of str
that can be passed to the RegExp
constructor in order to match the literal sequence found in str
.
Example:
var S = require('rods-util').StringUtil;
var dot_paren = S.escape_for_regexp('.)'); // returns `\.\)`
var re = new RegExp('^[A-Z]'+dot_paren) // returns /^[A-Z]\.\)/
re.test("A.)") // returns true
re.test("A\.\)") // returns false
is_blank(str)
Returns true
if the given string is null
, empty (""
) or only contains whitespace characters.
isnt_blank(str)
Returns true
if the given string is not null
, not empty (""
) and contains at least one non-whitespace character.
string_to_array(str,[options])
Splits a string into an array of strings with various configurable options.
-
options.delimiter
- a pattern on which to split the string (defaults to/[\n\r\f\v]/
) -
options.comment_char
- when present (and notfalse
) this and all subsequent characters (up to the next delimiter) will be stripped (defaults to'#'
) -
options.comment_char_escape
- when present, a character than can be used to "escape" a literal comment character (defaults to a single backslash). -
options.trim
- whentrue
, remove leading and trailing whitespace characters from each "line" (defaults totrue
) -
options.strip_blanks
- when true, remove empty lines from the returned array (defaults totrue
)
For example, given a string str
such as:
Line 1
Line 3 # with a comment
Line 4
# Line 5 is all comment
Line 6 has an \# escaped comment.
then:
var S = require('rods-util').StringUtil;
S.string_to_array(str);
will yield:
Line 1
Line 3
Line 4
Line 6 has an # escaped comment.
Legal Stuff
This software and associated materials are made available under the terms of the Apache License, Version 2.0, an OSD-compliant, non-viral, open source license. Use it in good health.
See the license.txt
file for details.