@c-syn/regext v0.0.7

RegExp to Template Converter

This package provides a class to convert regular expressions into template strings. It currently supports both a Mustache and plain style. The underlying function is strongly dependent on the regexp-tree package, which is used to parse the regular expression into an abstract syntax tree (AST). Its parser module is generated from the regexp grammar, which is based on the regular expressions grammar used in ECMAScript. After parsing, the AST is then traversed to generate the template string.

Installation

npm install @c-syn/regext

Usage

import RegExT from "@c-syn/regext" 

const regexp = /.../ // Your regular expression
const type = "Mustache" // or "plain"

const template = new RegExT(regexp, type).template

!TIP Try this code in the RegExT Playground.

RegExT is a class that takes two parameters: a regular expression and a type. The class has a toString method that returns the template string, it contains the following properties. The convert function that is used to generate the template string is also exposed import { convert } from 'regex-template'.

type

The type parameter is a string that specifies the type of template string that should be generated. The following types are supported. If no type, or an unknown type, is specified, type is set to Mustache.

Example

/(?:(?<=[^`\\])|^)\[(?=[^@\n\]]+\]\([^@)]*@[:a-z0-9_-]*\))(?<showtext>[^@\n\]]+)\]\((?:(?:(?<type>[a-z0-9_-]*):)?)(?:(?<term>[^@\n:#)]*?)?(?:#(?<trait>[^@\n:#)]*))?)?@(?<scopetag>[a-z0-9_-]*)(?::(?<vsntag>[a-z0-9_-]*))?\)/g

The regular expression above is used to match a markdown link with a specific format. Depending on the specified type, the regular expression will be converted into the following templates.

Mustache

[{{showtext}}]({{#type}}{{type}}:{{/type}}{{term}}{{#trait}}#{{trait}}{{/trait}}@{{scopetag}}{{#vsntag}}:{{vsntag}}{{/vsntag}})

Plain

[showtext](type:term#trait@scopetag:vsntag)

Use Cases

The generated template string can be used to convert any texts into texts that match the regular expression. Conversion can be done by replacing the template string with the corresponding values. For instance, after interpreting a text, it is converted using Handlebars to match another regular expression.

The generated template string can also be used to quickly visualize the structure of the regular expression. This can be useful when debugging or when trying to understand the structure of a regular expression.

Process

After the regular expression is parsed into an abstract syntax tree (AST), the AST is traversed to generate the template string. The following steps are walked through on every node, mostly depending on the specific type.

1. Certain types of nodes are removed (i.e., ClassRange, Disjunction, Assertion) as they may contain Char nodes that should not be included in the template string. For instance: ranges of characters that the regular expression is supposed to match are removed.
2. Repetition nodes are changed to Alternative nodes if the Quantifier's from and to properties are identical. Within the changed node, the Repetition node is repeated n times.
3. Group nodes are checked for their capturing property. If it is set to true, the group is converted into a Char node based on the specified template string type. Either the name, if it exists, or the number property is used to identify the group in the template string.
4. Alternative (or concatenation) nodes are handled according to the specified template string type. For instance, in the case of using the Mustache type, the Alternative node is wrapped in a section block (e.g., {{#person}}{{person}} exists{{/person}}).

After these steps halve been walked through, every Char node its value is concatenated, resulting in the template string.

Limitations

Due to the nature of the process used to generate the template string, the following limitations apply.

1. Nodes of types ClassRange, Disjunction, and Assertion are removed from the AST. This means that the template string will not contain any information about these nodes.
2. Backreferences are not (yet) supported. This means that the template string will not contain any information about backreferences.
3. Quantifiers (repetitions) are only handled if the from and to properties of the node are identical. In this case, the number of times the expressions is supposed to be repeated is clear. If the Quantifier applies to a Character class, it is ignored; as this means 'one of' a list of Chars is supposed to picked, which can't be assumed. If the from and to properties are different, the corresponding expression is not repeated in the template string.
4. Meta characters representing ranges of characters (e.g., ., \s, \w) are ignored. This means that the template string will not contain any information about these nodes.