Background

As outlined in issue #4481, the current implementation requires the use of complex regular expressions to match a transformer in Markdown. This solution can be quite convoluted and difficult to manage for more complex scenarios.

Purpose of this PR

This Pull Request proposes the introduction of a matcher property to both ElementTransformer and TextMatchTransformer, aiming to offer a more flexible and intuitive method for matching patterns. This is an optional property.

ElementTransformer

In the context of ElementTransformer, the matcher property is a function of type (textContent: string) => Array<string> | null. This function takes the textContent as input and finds all matching substrings or return null if none is found. It is an optional property of ElementTransformer.

When the matcher function is provided, the transformer will use it to find the matching patterns. If the matcher property is absent, the transformer will fall back to the existing regExp property to find matches.

TextMatchTransformer

As for TextMatchTransformer, the matcher property takes the form of a function (textContent: string) => {index: number; matchText: Array<string>} | null. This function operates similarly to the ElementTransformer's matcher, with the addition of an index property, mirroring the index property found in RegExpMatchArray. This is required by the runTextMatchTransformers function.

By implementing these changes, we anticipate a more versatile and user-friendly approach to finding matches within our Markdown transformers, reducing the reliance on complex regular expressions.

Usage

an example usage of the matcher property can be

export const HEADING: ElementTransformer = {
  dependencies: [HeadingNode],
  export: (node, exportChildren) => {
    if (!$isHeadingNode(node)) {
      return null;
    }
    const level = Number(node.getTag().slice(1));
    return '#'.repeat(level) + ' ' + exportChildren(node);
  },
  matcher: (textContent): string[] | null => {
    const headingPrefixes: string[] = ['# ', '## ', '### ', '#### ', '##### ', '###### '];
    const matches: string[] = [];

    for (const prefix of headingPrefixes) {
      if (textContent.startsWith(prefix)) {
        matches.push(prefix, prefix.trim());
      }
    }
    return matches.length > 0 ? matches : null;
  },
  regExp: /^(#{1,6})\s/,
  replace: createBlockNode((match) => {
    const tag = ('h' + match[1].length) as HeadingTagType;
    return $createHeadingNode(tag);
  }),
  type: 'element',
};      

where the matcher will handle the pattern finding.

Something To Note

In this PR, the type of the replace parameter in TextMatchTransformer has been updated from (node: TextNode, match: RegExpMatchArray) => void to (node: TextNode, match: Array<string>) => void. This change was made because it was determined that the additional properties provided by RegExpMatchArray are not necessary for the current usage of the function.

By aligning the type of the match parameter in TextMatchTransformer with the replace function in ElementTransformer, which is of type Array<string>, we ensure consistency and simplicity in the codebase.

Fixes #4481