batch-replace
Perform multiple str.replace() with one operation.
In some situations it's not possible to chain multiple calls of replace()
because you don't want to pass the result of the first operation to the second:
"ab" ; // returns "cc" instead of "bc"
With batch-replace it's possible to replace all patterns at once:
var replace = ; ; // returns bc
You can even create "replacement modules" for common tasks and to improve readability:
replace;
The chainable api creates a queue of replacement modules behind the scenes. If you need the same queue over and over again you can save a reference to the queue by calling .queue()
:
var enhanceMessage = replace; ;// returns 'Check out <a href="http://example.com" target="_blank">example.com</a> <img srg="/img/smilies/grin.jpg" />' ;// returns 'Check out <a href="http://nodejs.org" target="_blank">nodejs.org</a> <img srg="/img/smilies/grin.jpg" />'
Setup
Conflicts
If multiple patterns match the exact same string, the latter will succeed:
;// returns 'B'
If multiple patterns match parts of the same string, the match with the lower index succeeds:
// index = 0 // index = 0 // index = 1 // index = 2 // returns 'Alphabet'
Replacement modules
A replacement module is an object with a pattern
- and a replace
-property:
pattern: /abc/g replace: "ABC"
The replace
-property may also be a function which accepts the match
returned by pattern.exec()
and returns the new string:
pattern: /abc/g { return match0; }
You can add these modules by calling module()
:
replace;
After that you can chain them like this:
replace; // returns "ABCdefgh"
batch-replace comes with useful modules which are completely optional to use (see below). Please feel free to open a pull request if you implemented another useful replacement module.
hyperlinks
This module wraps all url-like patterns in a text with <a>
-tags:
replace; replace;// returns 'Hi, please take a look at <a href="http://example.com" target="_blank">example.com</a>'
In case you need to modify the generated html just overwrite the hyperlink
-function just like that:
var hyperlinks = ; // If the text was 'Hi, please take a look at example.com'// url will be 'http://example.com' and str will be 'example.com'hyperlinks { return '<a href="' + url + '">' + str + '</a>';};
html
This module escapes all special html characters like &
<
>
"
and '
with their save entity counterparts. Use this module if you need to escape user data to prevent XSS attacks.
replace; replace;// returns 'This is a mean <script>alert('XSS attack!')</script>'
API
replace(pattern: RegExp)
Creates a new queue where patterns and replacements can be registered. The given pattern
is pushed into the new queue.
.with(replacement: String|Function)
Registers the replacement
to the current pattern in the queue.
.and(pattern: RegExp)
Pushes a new pattern
into the queue.
.in(str: String)
Runs all replacement modules in the queue on the given string.
.queue(): Function
Returns a standalone function that takes a string and runs the configured replacement modules on it. Use this function if you need the same queue over and over again.
.module(name: String, module: Object)
Publishes the module
under replace[name]
. Write replacement modules for common replacement tasks and don't hesitate to create a pull-request so everyone benefits.
Compatibility
It is worth noting that the current api is not designed for ES3-environments (IE8 and Android 2.x) due usage of reserved keywords like with
and in
. If you need to support these environments and you don't want to use bracket notation (e.g. ["in"]
), you can also use the "ugly api":
replace(str: String, modules: Array): String
Applies all modules
on the given string and returns the result. Example:
; // returns 'bccd'
batch-replace requires several polyfills for ES5-features, so you should be sure to include es5-shims.
License
MIT