# @elderjs/shortcodes

> An Shortcode parser with support of arguments, key-value attributes, nesting, and async.

Latest version **2.0.2** (published 2021-09-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @elderjs/shortcodes
pnpm add @elderjs/shortcodes
yarn add @elderjs/shortcodes
bun add @elderjs/shortcodes
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.2 |
| Published | 2021-09-13 |
| First published | 2020-09-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 36 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | META Platform team |
| Maintainers | nickreese, lukeed |
| Keywords | shortcode, shortcodes, shorttag, tag, parser, shortcode-parser |

## Links

- npm: https://www.npmjs.com/package/@elderjs/shortcodes
- Repository: https://github.com/Elderjs/shortcodes
- Issues: https://github.com/Elderjs/shortcodes/issues
- npm.io page: https://npm.io/package/@elderjs/shortcodes

## 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.0.2 (latest) — 2021-09-13
- 2.0.1 — 2021-09-13
- 2.0.0 — 2021-09-13
- 1.0.7 — 2020-09-22
- 1.0.6 — 2020-09-15
- 1.0.5 — 2020-09-15
- 1.0.4 — 2020-09-15

## README

# Elder.js Shortcode Parser

> This is a fork of [meta-shortcodes](https://github.com/metaplatform/meta-shortcodes) which adds async support and has updated the tests to support async.

Generic shortcodes parser with support of attributes and single/pair tags.

## Usage

```javascript
var should = require("should");
var ShortcodeParser = require("meta-shortcodes");

var parser = ShortcodeParser();

parser.add("test", async function (opts, content) {
  return content.toUpperCase();
});

parser.add("nested", async function (opts, content) {
  if (!opts.multiply) return "Missing multiply attribute!";

  var out = [];

  for (var i = 0; i < opts.length; i++)
    out.push(opts[i] * parseFloat(opts.multiply));

  return out.join(" ");
});

var input =
  "Sample [test]shortcode content [nested multiply=2 2 4/] is upper[/test] case!";
var output = await parser.parse(input);

output.should.eql("Sample SHORTCODE CONTENT 4 8 IS UPPER case!");
```

## Instalation

```sh
npm install meta-shortcodes
```

## API

### #constructor(opts)

```javascript
opts = {
  openPattern: "\\[",
  closePattern: "\\]",
};
```

### #add(shortcodeName, handlerFunction)

Registers new shortcode

| Param           | Type     | Description                                                                                                                    |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| shortcodeName   | string   | Name of shortcode tag                                                                                                          |
| handlerFunction | function | Function/async function that returns replacement for shortcode. Accepts two arguments - `options` object and `content` string. |

### #parse(inputStr)

Registers new shortcode

| Param    | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| inputStr | string | Input string where shortcodes should be replaced. |

## Shortcode examples

```text
#Self-closing
[name argument1 argument2 key=value key=value/]

#Pair
[name]content[/name]

#Quoted arguments
[name "argument 1" 'argument 2' "key is"="long value"/]

#Escaping quotes in arguments
[name "argu\"ment" "ke\"y"='val\'ue']

#Escaping of entire shortcode
\\[this shortcode is not processed /]
```

## Testing

```sh
npm install --dev
npm test
```

**Current code-coverage 97%**

## Using alternative brackets

```javascript
var should = require("should");
var ShortcodeParser = require("meta-shortcodes");

var parser = ShortcodeParser({
  openPattern: "\\{{",
  closePattern: "\\}}",
});

parser.add("test", function (opts, content) {
  return content.toUpperCase();
});

var output = parser
  .parse("Sample {{test}}upper{{/test}} case!")
  .should.eql("Sample UPPER case!");
```

## License

See License file.

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