From 27e4aa65ab1836fa075fa21c87276982d3a1d1b6 Mon Sep 17 00:00:00 2001 From: Naiyer <19614213+naiyerasif@users.noreply.github.com> Date: Tue, 16 Apr 2024 16:51:57 +0530 Subject: [PATCH] feat(docs): update README --- README.md | 137 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 84 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index ec4dc19..9581fcc 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,14 @@ 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) @@ -23,7 +25,7 @@ A metadata parser for code fences in markdown 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 @@ -46,7 +48,7 @@ In browsers, with [esm.sh](https://esm.sh/): ```html ``` @@ -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 @@ -107,48 +115,50 @@ 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, + ], } ``` @@ -156,41 +166,62 @@ Running the above example yields. ```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, + ] } ``` @@ -198,12 +229,12 @@ 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