# stringd

> A string variable parser for JavaScript

Latest version **2.2.0** (published 2022-07-06) · Apache-2.0 license · 0 weekly downloads

## Install

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

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2022-07-06 |
| First published | 2019-02-19 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=12 |
| Dependencies | 0 |
| Unpacked size | 21.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Miraculous Owonubi |
| Maintainers | miraclx |
| Keywords | print, printf, sprintf, string, output, parser, format, variable, string variable, formatting |

## Links

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

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 2.2.0 (latest) — 2022-07-06
- 2.1.0 — 2020-06-26
- 2.0.0 — 2020-04-21
- 1.7.1 — 2020-04-21
- 1.7.0 — 2020-01-24
- 1.6.0 — 2020-01-24
- 1.5.1 — 2019-07-15
- 1.5.0 — 2019-05-07
- 1.4.1 — 2019-03-12
- 1.4.0 — 2019-03-12
- 1.3.2 — 2019-03-11
- 1.3.1 — 2019-03-11
- 1.2.2 — 2019-03-10
- 1.2.1 — 2019-03-10
- 1.1.5 — 2019-02-20
- … 5 more at https://npm.io/package/stringd/versions

## README

# STRING-D

> NodeJS String Variable Parser

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]

Create parsable strings using template formats by argument mapping.

Similar to [printf][printf] but supports nesting and exclusive recursions

[![NPM][npm-image-url]][npm-url]

## Installing

Via [NPM][npm]:

``` bash
npm install stringd
```

## Usage

``` javascript
import stringd from 'stringd';

stringd('Hello :{name}', {name: 'World'});
// Hello World

stringd(':{last}, :{first} :{last}', {last: 'Doe', first: 'John'});
// Doe, John Doe
```

## API

### stringd(template, object[, ignore])

* `tmp`: <[string][]>
* `props`: <[object][]>
* `ignore`: <[string][][]>
* Returns: <[string][]>

Parse the `tmp` string, replacing variable sections with flexibly defined values within the `props` object
String tags within the `ignore` array are skipped in the process. (used specifically to avoid repetition/recursion)

## Features

### Multi parse methods

Whichever is more comfortable for you would work just fine

``` javascript
stringd('Hello :{name}', {name: 'World'});  // Hello World
stringd('Hello %{name}', {name: 'World'});  // Hello World
stringd('Hello ${name}', {name: 'World'});  // Hello World
stringd('Hello :{name%}', {name: 'World'}); // Hello World
stringd('Hello %{name%}', {name: 'World'}); // Hello World
stringd('Hello ${name%}', {name: 'World'}); // Hello World
```

### Nesting

``` javascript
assert.equal('John Davis', stringd(':{name}', {
  name: ':{first} :{last}',
  last: 'Davis',
  first: 'John',
}));
```

### Extended, Variable Passing

``` javascript
assert.equal(
  'Age Difference = [32 + 25]  = [57]',
  stringd(
    stringd('Age Difference = [:{age1} + :{age2}]  = [:{add(:{age1}, :{age2})}]', {
      age1: 32,
      age2: 25,
    }),
    {add: (_, data) => data.args.reduce((a, v) => a + +v.trim(), 0)},
  ),
);
```

``` javascript
assert.equal(
  'Hello, Guys; Hello, World. How are you doing?',
  stringd(':{greet(Guys, post=How are you doing?, World)}', {
    greet: (_, names) =>
      names.args
        .map(name => `Hello, ${name.trim()}`)
        .join('; ')
        .concat('. ', names.matched.post),
  }),
);
```

### Functional Evaluation

``` javascript
assert.equal(
  'Hello John Davis, you have contributed $585 in the span of 13 months',
  stringd(':{name:parsed}', {
    name: ':{first} :{last}',
    last: 'Davis',
    first: 'John',
    greeting: 'Hello :{name}',
    months: 13,
    duration: ':{months} months',
    contribution: 45,
    // Functions get the entire template object as an argument
    // so you can do advanced processing
    cash: ({contribution, months}) => contribution * months,
    'name:parsed': `:{greeting}, you have contributed $:{cash} in the span of :{duration}`,
  })
);
```

### Forward Padding, Space

``` javascript
assert.equal('   10', stringd(':5{val}', {val: 10}));
```

### End Padding, Space

``` javascript
assert.equal('10   ', stringd(':-5{val}', {val: 10}));
```

### Forward Padding, Zero

``` javascript
assert.equal('00010', stringd(':05{val}', {val: 10}));
```

### End Padding, Zero

``` javascript
assert.equal('10000', stringd(':-05{val}', {val: 10}));
```

### Complex Nesting with exclusive recursion

Recursive nesting is unparsed at the second level, otherwise, it continues until its done parsing the entire string

``` javascript
assert.equal(
  'James:{name} :{name} :{data} :{data} :{all} :{name} :{data}Jack James:{data}Jack James:{data}Jack :{misc} :{data} :{all} James:{data}Jack :{misc}',
  stringd(':{name} :{misc}', {
    name: ':{first}:{data}:{last}',
    first: 'James',
    last: 'Jack',
    misc: ':{data}',
    data: ':{name} :{all}',
    all: ':{name} :{misc} :{data} :{all} :{name} :{misc}',
  })
);
```

### Iterative processing

``` javascript
assert.equal('      2364', stringd(stringd('::{pad}{price}', {pad: 10}), {price: 2364}))
```

### Precedence

`stringd` replaces keys in order precedence. Keys that appear first are replaced first

``` javascript
stringd( // str key appears first
  stringd(':{tro:{str}}', {str: 'y', 'tro:{str}': ':{tron}'}),
  { tron: 'Movie', troy: 'Dude' }
); // Dude

stringd( // str key appears later
  stringd(':{tro:{str}}', {'tro:{str}': ':{tron}', str: 'y'}),
  { tron: 'Movie', troy: 'Dude' }
); // Movie
```

## Development

Feel free to clone, use in adherance to the [license](#license). Pull requests are very much welcome.

``` bash
git clone https://github.com/miraclx/stringd.git
cd stringd
npm install
# hack on code
npm test
```

### Testing

Tests are executed with [Jest][jest]. To use it, simple run `npm install`, it will install
Jest and its dependencies in your project's `node_modules` directory and finally `npm test`.

To run the tests:

```bash
npm install
npm test
```

## License

[Apache 2.0][license] © **Miraculous Owonubi** ([@miraclx][author-url]) <omiraculous@gmail.com>

[npm]:  https://github.com/npm/cli "The Node Package Manager"
[jest]:  https://github.com/facebook/jest "Delightful JavaScript Testing"
[printf]:  https://github.com/adaltas/node-printf
[license]:  LICENSE "Apache 2.0 License"
[author-url]: https://github.com/miraclx

[npm-url]: https://npmjs.org/package/stringd
[npm-image]: https://badgen.net/npm/node/stringd
[npm-image-url]: https://nodei.co/npm/stringd.png?stars&downloads
[downloads-url]: https://npmjs.org/package/stringd
[downloads-image]: https://badgen.net/npm/dm/stringd

[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object

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