Skip to content

Commit

Permalink
feat(docs): update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@naiyerasif
naiyerasif committed Apr 16, 2024
1 parent 26fd647 commit 27e4aa6
Showing 1 changed file with 84 additions and 53 deletions.
137 changes: 84 additions & 53 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,22 @@ A metadata parser for code fences in markdown
- [Install](#install)
- [Use](#use)
- [API](#api)
- [Options](#options)
- [Syntax](#syntax)
- [Examples](#examples)
- [Example: single range](#example-single-range)
- [Example: multiple ranges](#example-multiple-ranges)
- [Example: ranges with custom annotations](#example-ranges-with-custom-annotations)
- [Example: key-value pairs](#example-key-value-pairs)
- [Example: customizing the default range's key](#example-customizing-the-default-ranges-key)
- [Development](#development)
- [License](#license)

## What’s this?

Many markdown processors can parse the language token associated with a code fence. `fenceparser` is meant for parsing other metadata besides language token. It supports

- ranges, (e.g., `{1} {3, 7} ins{9-11, 88} del{90, 101..167}`) and
- ranges, (e.g., `{1} {3, 7} ins{9..11, 88} del{90, 101..167}`) and
- key-value pairs (e.g., `caption='Hello, World'`)

## Install
Expand All @@ -46,7 +48,7 @@ In browsers, with [esm.sh](https://esm.sh/):

```html
<script type="module">
import fenceparser from "https://esm.sh/@microflash/fenceparser?bundle";
import fenceparser from "https://esm.sh/@microflash/fenceparser?bundle";
</script>
```

Expand All @@ -55,48 +57,54 @@ In browsers, with [esm.sh](https://esm.sh/):
Say, you have the following code fence

```
```js {1} {3, 7} {9-11, 88} {90, 101..112} text-color='--text-default' syntax_theme="nord" css=`{ *: { display: none }}`
```js {1} {3, 7} {9..11, 88} {90, 101..112} textColor='--text-default' syntax_theme="nord" css=`{ *: { display: none }}`
```

[remark](https://github.com/remarkjs/remark) will provide the `meta` and `lang` for the above code fence.

```json
{
"lang": "js",
"meta": "{1} {3, 7} {9-11, 88} {90, 101..112} text-color='--text-default' syntax_theme=\"nord\" css=`{ *: { display: none }}`"
"lang": "js",
"meta": "{1} {3, 7} {9..11, 88} {90, 101..112} textColor='--text-default' syntax_theme=\"nord\" css=`{ *: { display: none }}`"
}
```

Use the `fenceparser` to parse the `meta` as follows.

```js
import parse from "@microflash/fenceparser";
import FenceParser from "@microflash/fenceparser";

console.log(parse("{1} {3, 7} {9-11, 88} ins{90, 101..112} text-color='--text-default' syntax_theme=\"nord\" css=`{ *: { display: none }}`"));
const parser = new FenceParser();
console.log(parser.parse("{1} {3, 7} {9..11, 88} {90, 101..112} textColor='--text-default' syntax_theme=\"nord\" css=`{ *: { display: none }}`"));
```

Running the above example yields.

```js
{
'text-color': '--text-default',
syntax_theme: 'nord',
css: '{ *: { display: none }}',
highlight: [
1, 3, 7, 9, 10, 11,
88,
],
ins: [
90, 101, 102, 103, 104, 105,
106, 107, 108, 109, 110, 111,
112,
]
textColor: '--text-default',
syntax_theme: 'nord',
css: '{ *: { display: none }}',
highlight: [
1, 3, 7, 9, 10, 11, 88,
],
ins: [
90, 101, 102, 103, 104, 105,
106, 107, 108, 109, 110, 111,
112,
]
}
```

## API

The default export is `parse`.
The default export is `FenceParser` class.

### Options

The following options are available. All of them are optional.

- `rangeKey` (default: `highlight`): specifies the key for the default range of numbers

### Syntax

Expand All @@ -107,103 +115,126 @@ The default export is `parse`.

#### Ranges

- A range can be a single number, or a pair of numbers denoting the start and end values separated by either a hyphen `-` or double-dots `..`.
- A range must be wrapped in curly braces.
- Multiple ranges can be wrapped in a single pair of curly braces. They should be separated by comma `,`.
- Ranges can also be annotated; the annotation should be prefixed before the starting curly brace. The default annotation is `highlight`.
- Multiple ranges will be grouped in a single array by their annotations.
- A range can be a single number, or a pair of numbers denoting the start and end values separated by double-dots `..`.
- A range must be specified in curly braces.
- Multiple ranges can be specified in a single pair of curly braces. They should be separated by comma `,`.
- Ranges can also be annotated; the annotation should be prefixed before the starting curly brace. The default annotation is `highlight`. You can customize this annotation by passing `rangeKey` value in the parser options.
- Ranges will be grouped in a single array by their annotations.

## Examples

### Example: single range

```js
import parse from "@microflash/fenceparser";
import FenceParser from "@microflash/fenceparser";

console.log(parse("{100}"));
const parser = new FenceParser();
console.log(parser.parse("{100}"));
```

Running the above example yields.

```js
{
highlight: [
100,
]
highlight: [
100,
]
}
```

### Example: multiple ranges

```js
import parse from "@microflash/fenceparser";
import FenceParser from "@microflash/fenceparser";

console.log(parse("{3, 7} {9-11, 101..105}"));
const parser = new FenceParser();
console.log(parse("{3, 7} {9..11, 101..105}"));
```

Running the above example yields.

```js
{
highlight: [
1, 3, 7, 9, 10, 11,
101, 102, 103, 104, 105,
],
highlight: [
1, 3, 7, 9, 10, 11,
101, 102, 103, 104, 105,
],
}
```

### Example: ranges with custom annotations


```js
import parse from "@microflash/fenceparser";
import FenceParser from "@microflash/fenceparser";

console.log(parse("{3, 7} ins{9-11, 13} del{101..105}"));
const parser = new FenceParser();
console.log(parse("{3, 7} ins{9..11, 13} del{101..105}"));
```

Running the above example yields.

```js
{
highlight: [
3, 7,
],
ins: [
9, 10, 11, 13,
],
del: [
101, 102, 103, 104, 105,
],
highlight: [
3, 7,
],
ins: [
9, 10, 11, 13,
],
del: [
101, 102, 103, 104, 105,
],
}
```

### Example: key-value pairs

```js
import parse from "@microflash/fenceparser";
import FenceParser from "@microflash/fenceparser";

const parser = new FenceParser();
console.log(parse("dataTheme='synthwave' callback=`(code) => copyToClipboard(code)`"));
```

Running the above example yields.

```js
{
dataTheme: 'synthwave',
callback: '(code) => copyToClipboard(code)',
}
```

### Example: customizing the default range's key

```js
import FenceParser from "@microflash/fenceparser";

console.log(parse("data-theme='synthwave' callback=`(code) => copyToClipboard(code)`"));
const parser = new FenceParser({ rangeKey: "mark" });
console.log(parser.parse("{100}"));
```

Running the above example yields.

```js
{
'data-theme': 'synthwave',
callback: '(code) => copyToClipboard(code)',
mark: [
100,
]
}
```

Check the [fixtures](./test/fixtures.js) for more examples on the syntax.

## Development

Any changes in the lexer or parser should have corresponding tests.
Any changes in the parser should have corresponding tests.

Run the tests with the following command.

```sh
npm test
pnpm test
```

## License
Expand Down

0 comments on commit 27e4aa6

Please sign in to comment.