https://github.com/peerigon/batch-replace
Perform multiple str.replace() with one operation.
https://github.com/peerigon/batch-replace
Last synced: 11 months ago
JSON representation
Perform multiple str.replace() with one operation.
- Host: GitHub
- URL: https://github.com/peerigon/batch-replace
- Owner: peerigon
- License: mit
- Created: 2014-03-04T00:31:20.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2020-08-27T12:54:48.000Z (almost 6 years ago)
- Last Synced: 2025-07-10T23:41:26.205Z (12 months ago)
- Language: JavaScript
- Size: 39.1 KB
- Stars: 7
- Watchers: 12
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```javascript
"ab".replace(/a/g, "b").replace(/b/g, "c"); // returns "cc" instead of "bc"
```
With **batch-replace** it's possible to replace all patterns at once:
```javascript
var replace = require("batch-replace");
replace(/a/g).with("b").and(/b/g).with("c").in("ab"); // returns bc
```
You can even create "replacement modules" for common tasks and to improve readability:
```javascript
replace.hyperlinks().emoticons().in(message);
```
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()`:
```javascript
var enhanceMessage = replace.hyperlinks().emoticons().queue();
enhanceMessage("Check out example.com :)");
// returns 'Check out example.com ![]()
'
enhanceMessage("Check out nodejs.org :)");
// returns 'Check out nodejs.org ![]()
'
```
## Setup
[](https://npmjs.org/package/batch-replace)
[](http://travis-ci.org/peerigon/batch-replace)
[](http://david-dm.org/peerigon/batch-replace)
[](https://david-dm.org/peerigon/batch-replace#info=devDependencies)
[](https://coveralls.io/r/peerigon/peerigon/batch-replace?branch=master)
[
](https://ci.testling.com/peerigon/batch-replace)
## Conflicts
If multiple patterns match the exact same string, the latter will succeed:
```javascript
replace(/./g).with(" ").and(/b/g).with("B").in("b");
// returns 'B'
```
If multiple patterns match parts of the same string, the match with the lower index succeeds:
```javascript
replace(/abc/g)
.with("ABC") // index = 0
.and(/abc/g)
.with("Alphabet") // index = 0
.and(/b/g)
.with("B") // index = 1
.and(/c/g)
.with("C") // index = 2
.in("abc");
// returns 'Alphabet'
```
## Replacement modules
A replacement module is an object with a `pattern`- and a `replace`-property:
```javascript
{
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:
```javascript
{
pattern: /abc/g,
replace: function (match) {
return match[0].toUpperCase();
}
}
```
You can add these modules by calling `module()`:
```javascript
replace.module("abcToUppercase", {
pattern: /abc/g,
replace: "ABC",
});
```
After that you can chain them like this:
```javascript
replace.abcToUppercase().in("abcdefgh"); // 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 ``-tags:
```javascript
replace.use(require("batch-replace/plugins/hyperlinks"));
replace.hyperlinks().in("Hi, please take a look at example.com");
// returns 'Hi, please take a look at example.com'
```
In case you need to modify the generated html just overwrite the `hyperlink`-function just like that:
```javascript
var hyperlinks = require("batch-replace/plugins/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.hyperlink = function (url, str) {
return '' + str + "";
};
```
### 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.
```javascript
replace.use(require("batch-replace/plugins/html"));
replace.html().in("This is a mean alert('XSS attack!')");
// 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:
```javascript
replace("abcd", [
{
pattern: /a/g,
replace: "b",
},
{
pattern: /b/g,
replace: "c",
},
]); // returns 'bccd'
```
**batch-replace** requires several polyfills for ES5-features, so you should be sure to include [es5-shims](https://github.com/es-shims/es5-shim).
## License
MIT
## Sponsors
[
](https://peerigon.com)