Question: Two characters for parsing (move cursor backward?)

[joshbruce]

I apologize if this is covered somewhere, haven't seen it.

I'm working on a custom extension. The pattern is: [.]()

I'm using the footnote extension as reference for implementation, specifically the FootnoteReParser.php as I believe it's the inline parser portion.

// FootnoteRefParser.php
public function getCharacters(): array
{
    return ['['];
}

public function parse(InlineParserContext $inlineContext): bool
{
    $container = $inlineContext->getContainer();
    $cursor = $inlineContext->getCursor();
    $nextChar = $cursor->peek();
    if ($nextChar !== '^') {
        return false;
    }

    ...
}

// Should translate to something like
public function getCharacters(): array
{
    return ['['];
}

public function parse(InlineParserContext $inlineContext): bool
{
    $container = $inlineContext->getContainer();
    $nextChar = $cursor->peek();
    if ($nextChar !== '.') {
        return false;
    }

    ...
}

This isn't working, the parser for my extension is not being called, apparently.

Question

1. Why is the return of getCharacters an array?
2. Is it possible to use multiple characters?
3. Is there a way to move the cursor backward?
4. What am I missing with the following?

When I do the following, it kind of works, but because I don't know how (or if possible) to move the cursor back one character, I'm not able to complete the implementation (at least not with current understanding).

public function getCharacters(): array
{
    return ['.'];
}

public function parse(InlineParserContext $inlineContext): bool
{
    $container = $inlineContext->getContainer();
    $nextChar = $cursor->peek(-1);
    if ($nextChar !== '[') {
        return false;
    }

     $previousCursor = $cursor->saveState();

    // This is where I'd like to move the cursor back one

    $regex = '/^\[\..+?\]\(.+?\)/';
    $abbr = $cursor->match($regex);
    if (empty($abbr)) {
        $cursor->restoreState($previousCursor);
        return false;
    }
    ...
}

When I let this go and finish thing, I'm left with the starting square bracket [ - everything else works fine.

[colinodell]

This isn't working, the parser for my extension is not being called, apparently.

This suggests that a different parser with a higher priority (or with the same priority) is running before your parser and basically returning true to say that "I handled this, nobody else needs to."

For example, FootnoteRefParser is added with a priority of 51:

commonmark/src/Extension/Footnote/FootnoteExtension.php

Line 41 in 09e9079

$environment->addInlineParser(new FootnoteRefParser(), 51);

Try adding your parser to the environment with a higher priority so it is checked sooner.

Why is the return of getCharacters an array?

The purpose of getCharacters() is to provide a performance optimization to the engine so that it only checks the parsers which match the current character (instead of trying to check with all parsers when we know most will fail to match). It's an array because some parsers (like QuoteParser) are interested in trying to handle multiple characters.

Is it possible to use multiple characters?

Each string in the array must be a single character. #492 (comment) talks a little more about some of the limitations with this approach and new ideas that I'd like to try implementing in 2.0.

Is there a way to move the cursor backward?

No, unfortunately not :-/ You can't advance the cursor backward, but you can peek() backward (relative positioning) or use getCharacter() (absolute positioning). But I don't think that would be the best approach in this particular situation - I think adjusting the priority would be the better approach.

[joshbruce]

Thanks, you're awesome!

Here's the project: https://github.com/8fold/commonmark-abbreviations

That's where priority goes. I saw it mentioned in the docs but didn't quite understand where and whether it was higher or lower number.