Home

Awesome

String Kit

A string manipulation toolbox, featuring a string formatter (inspired by sprintf), a variable inspector (output featuring ANSI colors and HTML) and various escape functions (shell argument, regexp, html, etc).

Install

Use Node Package Manager:

npm install string-kit

Reference

<a name="ref.format"></a>

.format( formatString , ... )

This function is inspired by the C's sprintf() function.

Basicly, if formatString includes format specifiers (subsequences beginning with %), the additional arguments following formatString are formatted and inserted in the resulting string replacing their respective specifiers.

Also it diverges from C in quite a few places.

New: Since v0.3.x we can add styles markup (color, bold, italic, and so on...) using the ^ caret. See the format markup documentation.

Basic usage:

var format = require( 'string-kit' ).format ;
console.log( format( 'Hello %s %s, how are you?' , 'Joe' , 'Doe' ) ) ;
// Output: 'Hello Joe Doe, how are you?'

Specifiers:

Few examples:

var format = require( 'string-kit' ).format ;

console.log( format( 'This company regains %d%% of market share.' , 36 ) ) ;
// Output: 'This company regains 36% of market share.'

console.log( format( '11/8=%f' , 11/8 ) ) ;
// Output: '11/8=1.375'

console.log( format( 'Hexa %h %x' , 11 , 11 ) ) ;
// Output: 'Hexa b 0b'

We can insert a number between the % sign and the letter of the specifier, this way, rather than using the next argument, it uses the Nth argument, this is the absolute position:

console.log( format( '%2s%1s%3s' , 'A' , 'B' , 'C' ) ) ; // 'BAC'

Also, the internal pointer is moved anyway, so the Nth format specifier still use the Nth argument if it doesn't specify any position:

console.log( format( '%2s%s%s' , 'A' , 'B' , 'C' ) ) ; // 'BBC'

If the number is preceded by a plus or a minus sign, the relative position is used rather than the absolute position.

console.log( format( '%+1s%-1s%s' , 'A' , 'B' , 'C' ) ) ; // 'BAC'

Use case: language.

var hello = {
	en: 'Hello %s %s!' ,
	jp: 'Konnichiwa %2s %1s!'
} ;

console.log( format( hello[ lang ] , firstName , lastName ) ) ;
// Output the appropriate greeting in a language.
// In japanese the last name will come before the first name,
// but the argument list doesn't need to be changed.

Some specifiers accept parameters: there are between bracket, inserted before the letter, e.g.: %[L5]s. See the specifier parameters section.

The mysterious %[]F format specifier is used when we want custom formatter. Firstly we need to build an object containing one or many functions. Then, format() should be used with call(), to pass the functions collection as the this context.

The %[ is followed by the function's name, followed by a :, followed by a variable list of arguments using %a. It is still possible to use relative and absolute positionning. The whole format specifier is finished when a ]F is encountered.

Example:

var filters = {
	fxy: function( a , b ) { return '' + ( a * a + b ) ; }
} ;

console.log( format.call( filters , '%s%[fxy:%a%a]F' , 'f(x,y)=' , 5 , 3 ) ) ;
// Output: 'f(x,y)=28'

console.log( format.call( filters , '%s%[fxy:%+1a%-1a]F' , 'f(x,y)=' , 5 , 3 ) ) ;
// Output: 'f(x,y)=14'

<a name="ref.format.parameters"></a>

Specifiers parameters

A parameter consists in a letter, then one character (letter or not letter), that could be followed by any number of non-letter characters. E.g. %[L5]s, the L parameter that produce left-padding to force a 5 characters-length.

A special parameter (specific for that specifier) consists in any number of non-letter characters and must be the first parameter. E.g.:

When a parameter needs a boolean, + denotes true, while - denotes false.

Generic parameters -- they almost always exists for any specifier and use an upper-case parameter letter:

Specifier's specific parameters :

<a name="ref.format.markup"></a>

Style markup reference

Since v0.3.x we can add styles (color, bold, italic, and so on...) using the ^ caret:

var format = require( 'string-kit' ).format ;
console.log( format( 'This is ^rred^ and ^bblue^:!' ) ) ;
// Output: 'This is red and blue!' with 'red' written in red and 'blue' written in blue.

Style markups:

Note: as soon as the format string has one style markup, a style reset will be added at the end of the string.

New: Complex Markup

The complex markup syntax starts with ^[ follows with the markup keyword or key:value, and ends with a ].

Complex markup in the key:value format

E.g: This output “This is pink!” with the word pink written in pink color: console.log( format( 'This is: ^[fg:#f9b]pink^:!' ) )

Complex markup NOT in the key:value format

E.g: This output “This is pink!” with the word pink written in pink color: console.log( format( 'This is: ^[#f9b]pink^:!' ) )

<a name="ref.format.count"></a>

.format.count( formatString )

It just counts the number of format specifier in the formatString.

<a name="ref.inspect"></a>

.inspect( [options] , variable )

It inspect a variable, and return a string ready to be displayed with console.log(), or even as HTML output.

It produces a slightly better output than node's util.inspect(), with more options to control what should be displayed.

Since options come first, it is possible to use bind() to create some custom variable inspector.

For example:

var colorInspect = require( 'string-kit' ).inspect.bind( undefined , { style: 'color' } ) ;

Escape functions collection

<a name="ref.escape.shellArg"></a>

.escape.shellArg( str )

It escapes the string so that it will be suitable as a shell command's argument.

<a name="ref.escape.regExp"></a>

.escape.regExp( str ) , .escape.regExpPattern( str )

It escapes the string so that it will be suitable to inject it in a regular expression's pattern as a literal string.

Example of a search and replace from a user's input:

var result = data.replace(
	new RegExp( stringKit.escape.regExp( userInputSearch ) , 'g' ) ,
	stringKit.escape.regExpReplacement( userInputReplace )
) ;

<a name="ref.escape.regExpReplacement"></a>

.escape.regExpReplacement( str )

It escapes the string so that it will be suitable as a literal string for a regular expression's replacement.

<a name="ref.escape.html"></a>

.escape.html( str )

It escapes the string so that it will be suitable as HTML content.

Only < > & are replaced by HTML entities.

<a name="ref.escape.htmlAttr"></a>

.escape.htmlAttr( str )

It escapes the string so that it will be suitable as an HTML tag attribute's value.

Only < > & " are replaced by HTML entities.

It assumes valid HTML: the attribute's value should be into double quote, not in single quote.

<a name="ref.escape.htmlSpecialChars"></a>

.escape.htmlSpecialChars( str )

It escapes all HTML special characters, < > & " ' are replaced by HTML entities.

<a name="ref.escape.control"></a>

.escape.control( str )

It escapes all ASCII control characters (code lesser than or equals to 0x1F, or backspace).

Carriage return, newline and tabulation are respectively replaced by \r, \n and \t. Other characters are replaced by the unicode notation, e.g. NUL is replaced by \x00.

Full BDD spec generated by Mocha: