cronvelString 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).
- License: MIT
- Current status: beta
- Platform: Node.js only (browser support is planned)
Install
Use Node Package Manager:
npm install string-kitReference
- .format()
- .format.count()
- .inspect()
- Escape functions collection
.format( formatString , ... )
- formatString
Stringa string containing somesprintf()-like formating - ...
mixeda variable list of arguments to insert into the 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:
%%write a single %%sto string, with sanitizer%Sto string, with^interpretation%rto raw string, without any sanitizer%nto natural: output the most natural representation for this type%Nto even more natural: avoid type hinting marks like bracket for array%fto (float) number%kto number with metric system prefixes (like k, M, G, and so on...)%eto exponential “E notation” (e.g. 13 -> 1.23e+2)%Kto scientific notation (e.g. 123 -> 1.23 × 10²)%ito integer%dalias of%i(C'sprintf()compatibility)%uto unsigned integer%Uto unsigned positive integer (>0)%Pto (absolute) percent (e.g.: 1.25 -> 125% ; 0.75 -> 75%)%pto relative percent (e.g.: 1.25 -> +25% ; 0.75 -> -25%)%tto time duration, convert ms into H:min:s%mto degrees/minutes/seconds notation%hto unsigned hexadecimal%xto unsigned hexadecimal, force pairs of symbols (e.g. 'f' -> '0f')%oto unsigned octal%bto unsigned binary%Xstring/binary/buffer to hexadecimal: convert a string into hex charcodes, force pair of symbols (e.g. 'f' -> '0f' ; 'hello' -> '68656c6c6f')%zstring/binary/buffer to base64%Zstring/binary/buffer to base64url%Ofor objects (call string-kit's inspect() with ultra-minimal options)%Icall string-kit's inspect()%Ycall string-kit's inspect(), but do not inspect non-enumerable%Ecall string-kit's inspectError()%Jto JSON (call JSON.stringify()%Ddrop, the argument does not produce anything but is eaten anyway%Ffilter function existing in the this context, e.g. %[filter:%a%a]F%aargument for a filter function
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'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.:
%[.2]f, the special parameter for the f specifier (float), it rounds the number to the second decimal place.%[.2L5]f, mixing both the special and normal parameters, the special parameter comes first (round the the second decimal place), then comes the generic and normal parameter L (left-padding)
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:
- L integer: it produces left-padding (using space) and force the length to the value
- R integer: same than L but produce right-padding instead
Specifier's specific parameters :
- %f %e %K %k %p %P:
- integer: the number precision in digits, e.g.
%[3]f(12.345 -> 12.3) - integer .: rounds to this integer place, e.g.
%[3.]f(12345 -> 12000) - . integer: rounds to this decimal place, e.g.
%[.2]f(1.2345 -> 1.23) - . integer !: rounds to this decimal place and force displaying 0 up to this decimal place,
e.g.
%[.2!]f(12.9 -> 12.90 ; 12 -> 12.00) (useful for prices) - . integer ?: rounds to this decimal place and force displaying 0 up to this decimal place if there is at least one non-zero in the decimal part,
e.g.
%[.2?]f(12.9 -> 12.90 ; 12 -> 12) - z integer: it produces zero padding for the integer part forcing at least integer digits, e.g.
%[z5]f(12 -> 00012) - g char: set a group separator character for thousands, e.g.
%[g,]f(123456 -> 12,345) - g: use the default group separator for thousands, e.g.
%[g]f(123456 -> 12 345)
- integer: the number precision in digits, e.g.
- %O %I %Y %E:
- integer: the depth of nested object inspection
- c boolean: if true, can use ANSI color, if false, it will not use colors. E.g.
%[c+]I.
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:
^^write a single caret^^bswitch to blue^Bswitch to bright blue^cswitch to cyan^Cswitch to bright cyan^gswitch to green^Gswitch to bright green^kswitch to black^Kswitch to bright black^mswitch to magenta^Mswitch to bright magenta^rswitch to red^Rswitch to bright red^wswitch to white^Wswitch to bright white^yswitch to yellow (i.e. brown or orange)^Yswitch to bright yellow (i.e. yellow)^_switch to underline^/switch to italic^!switch to inverse (inverse background and foreground color)^+switch to bold^-switch to dim^:reset the style^(caret followed by a space) reset the style and write a single space^#background modifier: next color will be a background color instead of a foreground color, e.g.:'Some ^#^r^bred backgroundtext' will write red background in blue over red.
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
fg(or aliases:fgColor,color,c) set the foreground color, the value can be one of the ANSI color (red, brightRed, etc), it can also be any color declared in a Palette for methods of object supportingPalette, it can be a color-code (e.g.:#aa5577) if both the terminal and the method support true-color.bg(or alias:bgColor) set the background color, the supported values are exactly the same than for foreground color.
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
- Any ANSI color (red, brightRed, etc) or color code (e.g.:
#aa5577) will be considered as the value for the foreground color. - Named background color should be prefixed by
bgand followed by camel-case (e.g. red becomes bgRed), for color code you have to use the key:value syntax (see above, e.g.:bg:#aa5577). - Other styles like bold, italic, underline, inverse, dim are also supported.
E.g: This output “This is pink!” with the word pink written in pink color: console.log( format( 'This is: ^[#f9b]pink^:!' ) )
.format.count( formatString )
- formatString
Stringa string containing somesprintf()-like formating
It just counts the number of format specifier in the formatString.
.inspect( [options] , variable )
- options
Objectdisplay options, the following key are possible:- style
stringthis is the style to use, the value can be:- 'none': (default) normal output suitable for console.log() or writing into a file
- 'inline': like 'none', but without newlines
- 'color': colorful output suitable for terminal
- 'html': html output
- tab:
stringoverride the default tab string of the style - depth:
numberdepth limit, default: 3 - maxLength:
numberlength limit for strings, default: 250 - outputMaxLength:
numberlength limit for the inspect output string, default: 5000 - noFunc:
booleando not display functions - noDescriptor:
booleando not display descriptor information - noArrayProperty:
booleando not display array properties - noType:
booleando not display type and constructor - enumOnly:
booleanonly display enumerable properties - funcDetails:
booleandisplay function's details - proto:
booleandisplay object's prototype - sort:
booleansort the keys - minimal:
booleanimply noFunc: true, noDescriptor: true, noType: true, enumOnly: true, proto: false and funcDetails: false. Display a minimal JSON-like output. - protoBlackList:
Setof blacklisted object prototype (will not recurse inside it) - propertyBlackList:
Setof blacklisted property names (will not even display it) - useInspect:
booleanuse .inspect() method when available on an object (default to false)
- style
- variable
mixedanything we want to inspect/debug
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
.escape.shellArg( str )
- str
Stringthe string to filter
It escapes the string so that it will be suitable as a shell command's argument.
.escape.regExp( str ) , .escape.regExpPattern( str )
- str
Stringthe string to filter
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 )
) ;.escape.regExpReplacement( str )
- str
Stringthe string to filter
It escapes the string so that it will be suitable as a literal string for a regular expression's replacement.
.escape.html( str )
- str
Stringthe string to filter
It escapes the string so that it will be suitable as HTML content.
Only < > & are replaced by HTML entities.
.escape.htmlAttr( str )
- str
Stringthe string to filter
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.
.escape.htmlSpecialChars( str )
- str
Stringthe string to filter
It escapes all HTML special characters, < > & " ' are replaced by HTML entities.
.escape.control( str )
- str
Stringthe string to filter
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: