# regreplacer

> A library to facilitate regex matching, match/capture retrieval and string replacement

Latest version **1.1.13** (published 2021-12-25) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install regreplacer
pnpm add regreplacer
yarn add regreplacer
bun add regreplacer
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.1.13 |
| Published | 2021-12-25 |
| First published | 2017-09-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 17.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Alessandro Maclaine |
| Maintainers | almtechhub |
| Keywords | Regex, String, Replace, Matches, Captures |

## Links

- npm: https://www.npmjs.com/package/regreplacer
- Repository: https://github.com/ALMArchive/regreplacer
- Homepage: https://github.com/ALMArchive/regreplacer#readme
- Issues: https://github.com/ALMArchive/regreplacer/issues
- npm.io page: https://npm.io/package/regreplacer

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 1.1.13 (latest) — 2021-12-25
- 1.1.12 — 2021-01-16
- 1.1.11 — 2018-02-28
- 1.1.10 — 2018-02-16
- 1.1.9 — 2018-02-16
- 1.1.8 — 2018-02-16
- 1.1.7 — 2018-01-29
- 1.1.6 — 2018-01-27
- 1.1.5 — 2017-10-07
- 1.1.4 — 2017-10-07
- 1.1.3 — 2017-10-07
- 1.1.1 — 2017-10-07
- 1.1.0 — 2017-10-05
- 1.0.2 — 2017-10-05
- 1.0.1 — 2017-10-04
- … 2 more at https://npm.io/package/regreplacer/versions

## README

# RegReplacer
A library to facilitate **regex** matches and **replacing** matches.

```javascript
const regRep     = new RegReplacer(/Word/g);
const str        = "Word Word Word";
const regMatches = regRep.match(str);
console.log(regMatches.replace(["This", "is", "RegReplacer."], "matches"));
This is RegReplacer
```
*This is RegReplacer.*

## Installing
`npm install regreplacer`

## Main Example
Setup.
```javascript
import RegReplacer from "../regreplacer.js";

// Generate a RegReplacer object tied to a specific regex
const regRep = new RegReplacer(/\$(\S*)/g);

// Create a string to match on
let string = "$v1 $v2 $v3";

// Calling match function on string returns a RegRepMatches object
let regMatches = regRep.match(string);
```

Retrieve match data.
```javascript
// We can test whether any matches were found using hasMatches
let anyMatches = regMatches.hasMatches;
console.log(anyMatches); // true

// From the RegRepMatches object we can do several things
// First we can get the matches
let matches = regMatches.matches;
console.log(matches); // ['$v1', '$v2', '$v3']

// Next we can get the captures
let captures = regMatches.captures;
console.log(captures); // ['v1', 'v2', 'v3']

// Finally we can get the indices of matches
let indices = regMatches.indices;
console.log(indices); // [0, 4, 8]
```

Replace on matches.
```javascript
// After matching, we can replace the matches with an array of values
let newString1 = regMatches.replace(["This", "is", "cool."], "matches");
console.log(newString1); // This is cool

newString2 = regMatches.replace([1, 2, 3], "matches");
console.log(newString2); // 1 2 3
```

Replace on captures.
```javascript
// Or we can replace the captures
let newString3 = regMatches.replace(["This", "is", "cool."], "captures");
console.log(newString3); // $This $is $cool

newString4 = regMatches.replace([1, 2, 3], "captures");
console.log(newString4); // $1 $2 $3
```

Replacements can be done programmtically.
```javascript
let capMap = {'v1':'This', 'v2':'is', 'v3':'cool'};
let reaAr = [];

for(const match of captures) {
   reaAr.push(capMap[match]);
}

let newString5 = regMatches.replace(reaAr, "matches");
console.log(newString5); // This is cool
```

## API

### RegReplacer
Main class, constructor takes a valid regex and returns a RegReplacer object.
Invalid regexs will throw an error on construction.

#### Construction
```javascript
import RegReplacer from "../regreplacer.js";

const regRep  = new RegReplacer(/\S+/g);
const regReg2 = new RegReplacer(new RegExp("/s/g"));
```
Returns RegReplacer object.
#### Methods

##### Match
Match function takes a word and returns a RegRepMatches Object.
Will throw and error if passed anything other than a string.
```javascript
const regRep  = new RegReplacer(/Word/g);
const match   = regRep.match("Word");
```
Returns RepRapMatches Object.


##### isClass
Used to determine class type equality. Implemented internally using symbols.
```javascript
const regRep  = new RegReplacer(/\S+/g);
const regReg2 = new RegReplacer(new RegExp("/s/g"));
console.log(regRep.isClass(regReg2));
true
```
Returns boolean.

### RegRepMatches

#### Computed Properties

##### hasMatches
Returns boolean value for whether or not any matches were found.
```javascript
const regRep  = new RegReplacer(/W(ord)/g);
const match   = regRep.match("Word Word Word");
console.log(match.hasMatches);
true
```
Returns a boolean value.

##### matches
Returns the matches that would have been found after initializing RegReplacer and passing a string to match.
```javascript
const regRep  = new RegReplacer(/Word/g);
const match   = regRep.match("Word Word Word");
console.log(match.matches);
[Word, Word, Word]
```
Returns empty array if no matches found.

##### captures
Returns the captures that would have been found after initializing RegReplacer and passing a string to match.
```javascript
const regRep  = new RegReplacer(/W(ord)/g);
const match   = regRep.match("Word Word Word");
console.log(match.captures);
[ord, ord, ord]
```
Returns empty array if no matches/captures found.

##### indices
Returns the indices of the mathces that would have been found after initializing RegReplacer and passing a string to match.
```javascript
const regRep  = new RegReplacer(/W(ord)/g);
const match   = regRep.match("Word Word Word");
console.log(match.indices);
[0, 5, 10]
```
Returns empty array if no matches found.

#### Methods

##### isClass
Used to determine class type equality. Implemented internally using symbols.
```javascript
const regRep  = new RegReplacer(/Word/g);
const match   = regRep.match("Word");
const match2  = regRep.match("Word");
console.log(match.isClass(match2));
true
```
Returns boolean.

##### replace
Used to replace matches or captures with an array of values.
Extra values are ignored, and insufficient values will be replaced with undefined.
```javascript
// Simple replacement on matches
const regRep  = new RegReplacer(/Word/g);
const match   = regRep.match("Word Word Word");
console.log(match.replace(["This", "is", "cool"], "matches"));
"This is cool"

// Too few arguments, undefined in output
const regRep  = new RegReplacer(/Word/g);
const match   = regRep.match("Word Word Word");
console.log(match.replace([1,2], "matches"));
"1 2 undefined"

// Too many arguments, last argument ignored
const regRep  = new RegReplacer(/Word/g);
const match   = regRep.match("Word Word Word");
console.log(match.replace([1,2,3,4], "matches"));
"1 2 3"

// Add a capture group to regex and replace on captures instead
const regRep  = new RegReplacer(/W(ord)/g);
const match   = regRep.match("Word Word Word");
console.log(match.replace(["This", "is", "cool"], "captures"));
"WThis Wis Wcool"
```

##### replaceAll
Allows you to replace all matches with a single value or transform using a function.

```javascript
let regRep  = new RegReplacer(/Word/g);
let match   = regRep.match("Word Word Word");
console.log(match.replaceAll("Hey", "matches"));
"Hey Hey Hey"

let regRep  = new RegReplacer(/Word/g);
let match   = regRep.match("Word Word Word");
console.log(match.replaceAll(e => e.toLowerCase() + "@@", "matches"));
"word@@ word@@ word@@"
```

## Scripts

#### Testing
To run mocha/chai tests.
`npm run test`

#### Examples
To run the main example.
`npm run ex`

To run all examples.
`npm run exAll`

## License
RegReplace.js is released under the MIT license.

---
_Source: https://npm.io/package/regreplacer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._