easy-replace3.8.0

Replace strings with optional lookarounds, but without regexes

§ Quick Take

import { strict as assert } from "assert";
import er from "easy-replace";

assert.equal(
  er(
    "&nBsp; NBsp &nbSP NbsP;",
    {
      leftOutsideNot: "",
      leftOutside: "",
      leftMaybe: ["&", "&"],
      searchFor: "nbsp",
      rightMaybe: ";",
      rightOutside: "",
      rightOutsideNot: "",
      i: {
        searchFor: true,
      },
    },
    " "
  ),
  "       "
);

§ Purpose

It's an alternative to JS regexes.

§ API

er(source_string, options_object, replacement_string)

In other words, it's a "string-in, string-out" function with three input arguments, see them below.

§ API - Input

Input argumentTypeObligatory?Description
source_stringStringyesOriginal string
options_objectPlain ObjectyesSettings
replacement_stringStringnoReplace all the findings with this. If missing, library runs on delete-only mode, it won't replace, just delete.

§ Options object:

Options object's keyTypeObligatory?Description
leftOutsideNotString/Array of stringsnoEquivalent of regex negative lookbehind. This/these string(s) must not be present to the left of searchFor (plus any "maybe's" strings, see below), in order for searchFor to be counted as "found". This input's contents are not replaced/deleted.
leftOutsideString/Array of stringsnoEquivalent of regex positive lookbehind. This/these string(s) must be present to the left of searchFor (plus any "maybe's" strings, see below), in order for searchFor to be counted as "found". This input's contents are not replaced/deleted.
leftMaybeString/ArraynoIf this is present on the left side of the searchFor, replace/delete it together with searchFor, but don't fret if it's not found.
searchForString onlyyesThe keyword to look for in the source_string
rightMaybeString/Array of stringsnoIf this is present on the right side of the searchFor, replace/delete it together with searchFor, but don't fret if it's not found.
rightOutsideString/Array of stringsnoEquivalent of regex positive lookahead. This/these string(s) must be present to the right of searchFor (plus any "maybe's" strings, see higher), in order for searchFor to be counted as "found". This input's contents are not replaced/deleted.
rightOutsideNotString/Array of stringsnoEquivalent of regex negative lookahead. This/these string(s) must not be present to the right of searchFor (plus any "maybe's" strings, see higher), in order for searchFor to be counted as "found". This input's contents are not replaced/deleted.
iPlain objectnoEach key mentioned above can be set to a Boolean true/false to optionally be case-insensitive. Same thing as i flag in regexes.

§ API - Output

TypeDescription
StringString with things replaced

§ Examples

Simple replace:

  • Example replacement recipe in words — replace all instances of x with 🦄.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"a x c x d",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "",
searchFor: "x",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: "",
},
"🦄"
);
console.log(res);
//=> 'a 🦄 c 🦄 d'

Case insensitive setting — set each and every key you want to ignore the case via opts.i:

const er = require("easy-replace");
const res = er(
"a X c x d",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "",
searchFor: "x",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: "",
i: {
searchFor: true,
},
},
"🦄"
);
console.log(res);
//=> 'a 🦄 c 🦄 d'

§ "Maybes" — optional surrounding strings to be replaced as well

  • Example replacement recipe in words — Replace all instances of i. If there are 🐴 or 🦄 characters on the left, count them as part of found i and replace together as one thing. If there are 🐴 or 🦄 characters on the right, count them as part of found i and replace together as one thing.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"🐴i🦄 🐴i i🦄 i",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: ["🐴", "🦄"],
searchFor: "i",
rightMaybe: ["🐴", "🦄"],
rightOutside: "",
rightOutsideNot: "",
},
"x"
);
console.log(res);
//=> 'x x x x'

By the way, notice, how the values can be strings or arrays! The easy-replace doesn't accept array only for searchFor values — create a loop from the outside of this library, then call this library many times if you want to search for multiple values.

Case-insensitive setting will cover more surroundings' cases:

const er = require("easy-replace");
const res = er(
"Ai ib Aib i",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: ["a", "z"],
searchFor: "i",
rightMaybe: ["y", "b"],
rightOutside: "",
rightOutsideNot: "",
i: {
leftMaybe: true,
},
},
"x"
);
console.log(res);
//=> 'x x x x'

§ Negative lookahead - if you want to match something not followed by something else

  • Example replacement recipe in words — Replace all instances of 🦄, but only ones that don't have c or d on the right.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"a🦄c x🦄x",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "",
searchFor: "🦄",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: ["c", "d"],
},
"🐴"
);
console.log(res);
//=> 'a🦄c x🐴x'

Case insensitive setting will narrow-down the amount of findings/replacements:

const er = require("easy-replace");
const res = er(
"a🦄C x🦄x",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "",
searchFor: "🦄",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: ["c", "d"],
i: {
rightOutsideNot: true,
},
},
"🐴"
);
console.log(res);
//=> 'a🦄c x🐴x'

§ Positive lookbehind - if you want to match something that is preceded by something else

For example, search for space characters that have another space right to their left, and delete them

  • Example replacement recipe in words — Replace all occurencies of space character, but only those that have another space character in front of them.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"zzzzz zzzzzz zzzzzz",
{
leftOutsideNot: "",
leftOutside: " ", // <- space
leftMaybe: "",
searchFor: " ", // <- space
rightMaybe: "",
rightOutside: "",
rightOutsideNot: "",
},
"" // <- empty string
);
console.log(res);
//=> 'zzzzz zzzzzz zzzzzz'

§ Negative lookbehind - if you want to match something that is NOT preceded by something else

For example, our <br /> sometimes look like <br/>. Replace all occurencies of /> with {{space character}}/> (disregard curly braces, it's only to make it more visible here) if they are not preceded with space already:

  • Example replacement recipe in words — Add missing spaces before closing slashes on tags. Do not add spaces where they exist already.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"<br /><br/><br />",
{
leftOutsideNot: " ",
leftOutside: "",
leftMaybe: "",
searchFor: "/>",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: "",
},
" />"
);
console.log(res);
//=> '<br /><br /><br />'

§ Real life scenario

  • Example replacement recipe in words — Add a missing semicolon and/or ampersand on &nbsp;, but only where they are missing.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"&nbsp; nbsp &nbsp nbsp;",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "&",
searchFor: "nbsp",
rightMaybe: ";",
rightOutside: "",
rightOutsideNot: "",
},
"&nbsp;"
);
console.log(res);
//=> '&nbsp; &nbsp; &nbsp; &nbsp;'

If you want to cover cases of random letter capitalisation of n, b, s and p, just set case-insensitive flag for searchFor:

const er = require("easy-replace");
const res = er(
"&nBsp; NBsp &nbSP NbsP;",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "&",
searchFor: "nbsp",
rightMaybe: ";",
rightOutside: "",
rightOutsideNot: "",
i: {
searchFor: true,
},
},
"&nbsp;"
);
console.log(res);
//=> '&nbsp; &nbsp; &nbsp; &nbsp;'

§ Licence

MIT opens in a new tab

Copyright © 2010–2020 Roy Revelt and other contributors

Related packages:

📦 edit-package-json 0.1.36
Edit package.json without parsing, as string, to keep the formatting intact
📦 str-indexes-of-plus 2.10.11
Like indexOf but returns array and counts per-grapheme
📦 email-all-chars-within-ascii 2.9.72
Scans all characters within a string and checks are they within ASCII range
📦 js-row-num 2.7.28
Update all row numbers in all console.logs in JS code