string-kit - npm Package Compare versions

Comparing version 0.0.8 to 0.0.9

bdd-spec.md

@@ -16,2 +16,8 @@ # TOC
 expect( format( 'I have %i cookies.' , 3 ) ).to.be( 'I have 3 cookies.' ) ;
+expect( format( 'This company regains %d%% of market share.' , 36 ) ).to.be( 'This company regains 36% of market share.' ) ;
+expect( format( '11/8=%f' , 11/8 ) ).to.be( '11/8=1.375' ) ;
+expect( format( 'Binary %b %b' , 11 , 123 ) ).to.be( 'Binary 1011 1111011' ) ;
+expect( format( 'Octal %o %o' , 11 , 123 ) ).to.be( 'Octal 13 173' ) ;
+expect( format( 'Hexa %h %x %x' , 11 , 11 , 123 ) ).to.be( 'Hexa b 0b 7b' ) ;
+expect( format( 'JSON %J' , {hello:'world',here:'is',my:{wonderful:'object'}} ) ).to.be( 'JSON {"hello":"world","here":"is","my":{"wonderful":"object"}}' ) ;
 ```
@@ -18,0 +24,0 @@

documentation.md

@@ -24,16 +24,133 @@
 
-* [.escape.shellArg()](#ref.escape.shellArg)
-* [.escape.regExp()](#ref.escape.regExp)
-* [.escape.regExpPattern()](#ref.escape.regExp)
-* [.escape.regExpReplacement()](#ref.escape.regExpReplacement)
-* [.escape.html()](#ref.escape.html)
-* [.escape.htmlAttr()](#ref.escape.htmlAttr)
-* [.escape.htmlSpecialChars()](#ref.escape.htmlSpecialChars)
-* [.escape.control()](#ref.escape.control)
+* [.format()](#ref.format)
+* [.format.count()](#ref.format.count)
+* [.inspect()](#ref.inspect)
+* Escape functions collection
+	* [.escape.shellArg()](#ref.escape.shellArg)
+	* [.escape.regExp()](#ref.escape.regExp)
+	* [.escape.regExpPattern()](#ref.escape.regExp)
+	* [.escape.regExpReplacement()](#ref.escape.regExpReplacement)
+	* [.escape.html()](#ref.escape.html)
+	* [.escape.htmlAttr()](#ref.escape.htmlAttr)
+	* [.escape.htmlSpecialChars()](#ref.escape.htmlSpecialChars)
+	* [.escape.control()](#ref.escape.control)
 
 
 
+<a name="ref.format"></a>
+### .format( formatString , ... )
+
+* formatString `String` a string containing some `sprintf()`-like formating
+* ... `mixed` a 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.
+
+Basic usage:
+```js
+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 %
+* %s string
+* %f float
+* %d *or* %i integer
+* %u unsigned integer
+* %U unsigned positive integer (>0)
+* %h unsigned hexadecimal
+* %x unsigned hexadecimal, force pair of symbols (e.g. 'f' -> '0f')
+* %o unsigned octal
+* %b unsigned binary
+* %J JSON.stringify()
+* %D drop, the argument does not produce anything but is eaten anyway
+* %[ filter function existing in the *this* context, e.g. %[filter:%a%a]
+* %a argument for a filter function
+
+Few examples:
+```js
+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:
+```js
+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:
+```js
+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.
+```js
+console.log( format( '%+1s%-1s%s' , 'A' , 'B' , 'C' ) ) ; // 'BAC'
+```
+
+Use case: language.
+```js
+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.
+```
+
+The mysterious `%[` 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 `]` is encountered.
+
+Example:
+```js
+var filters = {
+	fxy: function( a , b ) { return '' + ( a * a + b ) ; }
+} ;
+
+console.log( format.call( filters , '%s%[fxy:%a%a]' , 'f(x,y)=' , 5 , 3 ) ) ;
+// Output: 'f(x,y)=28'
+
+console.log( format.call( filters , '%s%[fxy:%+1a%-1a]' , 'f(x,y)=' , 5 , 3 ) ) ;
+// Output: 'f(x,y)=14'
+```
+
+
+
+<a name="ref.format.count"></a>
+### .format.count( formatString )
+
+* formatString `String` a string containing some `sprintf()`-like formating
+
+It just counts the number of *format specifier* in the `formatString`.
+
+
+
 ## Escape functions collection
 
 
+
 <a name="ref.escape.shellArg"></a>
@@ -40,0 +157,0 @@ ### .escape.shellArg( str )

lib/string.js

@@ -42,25 +42,25 @@ /*
 
-// String formater, inspired by C's printf
+// String formater, inspired by C's sprintf
 
 /*
-	%s	string
-	%f	float
-	%d	integer
-	%i	integer, same as %d
-	%u	unsigned integer
-	%U	unsigned positive integer (>0)
-	%x	hexadecimal
-	%h	hexadecimal, same as %x
-	%o	octal
-	%b	binary
-	%D	drop
-	%[	filter function existing in the 'this' context, e.g. %[filter:%a%a]
-	%a	argument for a function
+	%%		a single %
+	%s		string
+	%f		float
+	%d	%i	integer
+	%u		unsigned integer
+	%U		unsigned positive integer (>0)
+	%h		hexadecimal
+	%x		hexadecimal, force pair of symbols (e.g. 'f' -> '0f')
+	%o		octal
+	%b		binary
+	%J		JSON.stringify()
+	%D		drop
+	%[		filter function existing in the 'this' context, e.g. %[filter:%a%a]
+	%a		argument for a function
 	
 	Candidate format:
-	%c	for char? (can receive a string or an integer translated into an UTF8 chars)
-	%C	for currency formating?
-	%O	for object? (using JSON.stringify() ?)
-	%B	for Buffer objects?
-	%e	for scientific notation?
+	%c		for char? (can receive a string or an integer translated into an UTF8 chars)
+	%C		for currency formating?
+	%B		for Buffer objects?
+	%e		for scientific notation?
 */
@@ -77,3 +77,3 @@
 	
-	var arg , autoIndex = 1 , args = arguments , length = arguments.length , self = this ;
+	var arg , value , autoIndex = 1 , args = arguments , length = arguments.length , self = this ;
 	
@@ -174,3 +174,8 @@ //console.log( 'format args:' , arguments ) ;
 					return '1' ;
-				case 'x' :
+				case 'x' :	// unsigned hexadecimal, force 
+					if ( typeof arg === 'string' ) { arg = parseInt( arg ) ; }
+					if ( typeof arg !== 'number' ) { return '0' ; }
+					value = '' + Math.max( Math.floor( arg ) , 0 ).toString( 16 ) ;
+					if ( value.length % 2 ) { value = '0' + value ; }
+					return value ;
 				case 'h' :	// unsigned hexadecimal
@@ -180,3 +185,3 @@ if ( typeof arg === 'string' ) { arg = parseInt( arg ) ; }
 					return '0' ;
-				case 'o' :	// unsigned hexadecimal
+				case 'o' :	// unsigned octal
 					if ( typeof arg === 'string' ) { arg = parseInt( arg ) ; }
@@ -189,2 +194,6 @@ if ( typeof arg === 'number' ) { return '' + Math.max( Math.floor( arg ) , 0 ).toString( 8 ) ; }
 					return '0' ;
+				case 'J' :
+					return JSON.stringify( arg ) ;
+				case 'D' :
+					return '' ;
 				default :
@@ -565,31 +574,27 @@ return '' ;
 
+			/* Polyfills for String.prototype */
 
 
 /*
-
-function dumpPrototypeChainStr( object , options )
+if ( ! String.prototype.repeat )
 {
-	if ( object === null || typeof object !== 'object' )  return '<bad type>' ;
-	
-	var str = '' ;
-	var current = Object.getPrototypeOf( object ) ;
-	
-	while ( typeof current === 'object' && current !== null )
+	// From: http://stackoverflow.com/questions/202605/repeat-string-javascript
+	String.prototype.repeat = function( count )
 	{
-		if ( str )  str += " --> " ;
-		str += current.constructor.name ;
-		current = Object.getPrototypeOf( current ) ;
-	}
-	
-	return str ;
+		if ( count < 1 ) { return '' ; }
+		
+		var result = '' , pattern = this.valueOf() ;
+		
+		while ( count > 1 )
+		{
+			if ( count & 1 ) { result += pattern ; }
+			count >>= 1 ;
+			pattern += pattern ;
+		}
+		
+		return result + pattern ;
+	} ;
 }
+//*/
 
 
-
-// Shortcut
-var dump = function( variable , options ) { console.log( dumpStr( variable , options ) ) ; } ;
-var dumpError = function( error , options ) { console.log( dumpErrorStr( error , options ) ) ; } ;
-var dumpPrototypeChain = function( object , options ) { console.log( dumpPrototypeChainStr( object , options ) ) ; } ;
-
-*/
-

package.json

 {
   "name": "string-kit",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "A string manipulation toolbox, featuring a string formater (inspired by printf), a variable inspector (output featuring ANSI color and HTML) and various escape function (shell argument, regexp, html, etc).",
@@ -29,2 +29,3 @@ "main": "lib/string.js",
     "format",
+    "sprintf",
     "printf",
@@ -31,0 +32,0 @@ "inspect",

README.md

@@ -24,16 +24,133 @@
 
-* [.escape.shellArg()](#ref.escape.shellArg)
-* [.escape.regExp()](#ref.escape.regExp)
-* [.escape.regExpPattern()](#ref.escape.regExp)
-* [.escape.regExpReplacement()](#ref.escape.regExpReplacement)
-* [.escape.html()](#ref.escape.html)
-* [.escape.htmlAttr()](#ref.escape.htmlAttr)
-* [.escape.htmlSpecialChars()](#ref.escape.htmlSpecialChars)
-* [.escape.control()](#ref.escape.control)
+* [.format()](#ref.format)
+* [.format.count()](#ref.format.count)
+* [.inspect()](#ref.inspect)
+* Escape functions collection
+	* [.escape.shellArg()](#ref.escape.shellArg)
+	* [.escape.regExp()](#ref.escape.regExp)
+	* [.escape.regExpPattern()](#ref.escape.regExp)
+	* [.escape.regExpReplacement()](#ref.escape.regExpReplacement)
+	* [.escape.html()](#ref.escape.html)
+	* [.escape.htmlAttr()](#ref.escape.htmlAttr)
+	* [.escape.htmlSpecialChars()](#ref.escape.htmlSpecialChars)
+	* [.escape.control()](#ref.escape.control)
 
 
 
+<a name="ref.format"></a>
+### .format( formatString , ... )
+
+* formatString `String` a string containing some `sprintf()`-like formating
+* ... `mixed` a 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.
+
+Basic usage:
+```js
+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 %
+* %s string
+* %f float
+* %d *or* %i integer
+* %u unsigned integer
+* %U unsigned positive integer (>0)
+* %h unsigned hexadecimal
+* %x unsigned hexadecimal, force pair of symbols (e.g. 'f' -> '0f')
+* %o unsigned octal
+* %b unsigned binary
+* %J JSON.stringify()
+* %D drop, the argument does not produce anything but is eaten anyway
+* %[ filter function existing in the *this* context, e.g. %[filter:%a%a]
+* %a argument for a filter function
+
+Few examples:
+```js
+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:
+```js
+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:
+```js
+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.
+```js
+console.log( format( '%+1s%-1s%s' , 'A' , 'B' , 'C' ) ) ; // 'BAC'
+```
+
+Use case: language.
+```js
+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.
+```
+
+The mysterious `%[` 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 `]` is encountered.
+
+Example:
+```js
+var filters = {
+	fxy: function( a , b ) { return '' + ( a * a + b ) ; }
+} ;
+
+console.log( format.call( filters , '%s%[fxy:%a%a]' , 'f(x,y)=' , 5 , 3 ) ) ;
+// Output: 'f(x,y)=28'
+
+console.log( format.call( filters , '%s%[fxy:%+1a%-1a]' , 'f(x,y)=' , 5 , 3 ) ) ;
+// Output: 'f(x,y)=14'
+```
+
+
+
+<a name="ref.format.count"></a>
+### .format.count( formatString )
+
+* formatString `String` a string containing some `sprintf()`-like formating
+
+It just counts the number of *format specifier* in the `formatString`.
+
+
+
 ## Escape functions collection
 
 
+
 <a name="ref.escape.shellArg"></a>
@@ -139,2 +256,8 @@ ### .escape.shellArg( str )
 expect( format( 'I have %i cookies.' , 3 ) ).to.be( 'I have 3 cookies.' ) ;
+expect( format( 'This company regains %d%% of market share.' , 36 ) ).to.be( 'This company regains 36% of market share.' ) ;
+expect( format( '11/8=%f' , 11/8 ) ).to.be( '11/8=1.375' ) ;
+expect( format( 'Binary %b %b' , 11 , 123 ) ).to.be( 'Binary 1011 1111011' ) ;
+expect( format( 'Octal %o %o' , 11 , 123 ) ).to.be( 'Octal 13 173' ) ;
+expect( format( 'Hexa %h %x %x' , 11 , 11 , 123 ) ).to.be( 'Hexa b 0b 7b' ) ;
+expect( format( 'JSON %J' , {hello:'world',here:'is',my:{wonderful:'object'}} ) ).to.be( 'JSON {"hello":"world","here":"is","my":{"wonderful":"object"}}' ) ;
 ```
@@ -141,0 +264,0 @@

test/string-test.js

@@ -52,2 +52,8 @@ /*
 		expect( format( 'I have %i cookies.' , 3 ) ).to.be( 'I have 3 cookies.' ) ;
+		expect( format( 'This company regains %d%% of market share.' , 36 ) ).to.be( 'This company regains 36% of market share.' ) ;
+		expect( format( '11/8=%f' , 11/8 ) ).to.be( '11/8=1.375' ) ;
+		expect( format( 'Binary %b %b' , 11 , 123 ) ).to.be( 'Binary 1011 1111011' ) ;
+		expect( format( 'Octal %o %o' , 11 , 123 ) ).to.be( 'Octal 13 173' ) ;
+		expect( format( 'Hexa %h %x %x' , 11 , 11 , 123 ) ).to.be( 'Hexa b 0b 7b' ) ;
+		expect( format( 'JSON %J' , {hello:'world',here:'is',my:{wonderful:'object'}} ) ).to.be( 'JSON {"hello":"world","here":"is","my":{"wonderful":"object"}}' ) ;
 	} ) ;
@@ -54,0 +60,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

62410

increased by17.49%

Lines of code

629

increased by2.44%

Number of lines in readme file

427

increased by40.46%

No dependency changes