We should group together all the contexts for «one-liner constructs» in order to disentangle the Syntax, on the one hand, and to optimize its performance, on the other.
The obvious place to start is by grouping those constructs which consist of a single line within square brackets ([ … ]).
Since AsciiDoc supports many such constructs, it would probably make sense to add a «top-level interceptor context» that matches — without consuming — any line which begins with an opening square bracket and end with a matching closing bracket, and in case of a match then push a dedicated context that will attempt all the pertaining pattern-matching contexts for such one-liners.
This should increase the performance of the Syntax, since it will only attempt a single RegEx at each non-matching input line, instead of trying each and every one-liner context.
[x] Find and list here all the square-bracketed one-liner contexts\:
special_section (recently added)
block_id_legacy (recently renamed from block_id)
attribute_list_line
[x] Check if Asciidoctor tolerates trailing whitespace after the closing bracket, so that we can account for it in the «interceptor pattern»\:
Asciidoctor simply ignores spaces or tabs following the bracketed element.
Note: If non-WS characters are found (leading or trailing) then the construct is treated as text instead of an element. A single leading space or tab, on the other hand, results in the line being treated as a verbatim block (along with any following lines until an empty line is found).
This is rather expected, but is worth keeping into account in case we decide to also handle in our dedicated context those inline square-bracketed elements which may also occur on a line of their own (i.e. bear in mind that our filtering RegEx will only pass-on lines which start with a [ and end with a ] which might contain trailing spaces or tabs).
[ ] Add a «top-level interceptor context» that matches one-liners within square brackets without consuming them, and the push a context that will include all the pertaining contexts.
[ ] Note1: some square-bracketed inline-constructs might also occur in a single line, effectively resembling elements of this category. We could just include: them within the dedicated context, since we'd already already know that the line contains a bracketed element.
[ ] Note2: we should account for multiple occurrences of bracketed elements in a single line (e.g. [#myid][.myrole]), which are malformed but can nevertheless occur — Asciidoctor tends to parse them as if they were a single bracketed group, with the middle ][ ending up in the first parsed parameter, but results are unpredictable: sometimes one of the two elements is preserved, other times both are rejected, or the result is corrupted parsing.
In any case, we should at least scope any extra bracketed groups after the first one as invalid, to signal to the user that there's a problem in the source doc. If we don't account for such multiple occurrences, the risk is that the whole line is ignored by the RegEx or, worst, it gets handled poorly (with the risk of breaking the document).
[ ] Ensure that there are enough syntax tests to properly cover each context, so that any breaking changes are detected immediately.
[x] Move all pertaining contexts within a same group — done: it's titled "SQUARE-BRACKETED ONE-LINERS"
[ ] Include the pertaining contexts in order of importance, so that more frequently occurring constructs are given higher priority during execution.
We should group together all the contexts for «one-liner constructs» in order to disentangle the Syntax, on the one hand, and to optimize its performance, on the other.
The obvious place to start is by grouping those constructs which consist of a single line within square brackets (
[ … ]).Since AsciiDoc supports many such constructs, it would probably make sense to add a «top-level interceptor context» that matches — without consuming — any line which begins with an opening square bracket and end with a matching closing bracket, and in case of a match then push a dedicated context that will attempt all the pertaining pattern-matching contexts for such one-liners.
This should increase the performance of the Syntax, since it will only attempt a single RegEx at each non-matching input line, instead of trying each and every one-liner context.
[x] Find and list here all the square-bracketed one-liner contexts\:
special_section(recently added)block_id_legacy(recently renamed fromblock_id)attribute_list_line[x] Check if Asciidoctor tolerates trailing whitespace after the closing bracket, so that we can account for it in the «interceptor pattern»\:
Note: If non-WS characters are found (leading or trailing) then the construct is treated as text instead of an element. A single leading space or tab, on the other hand, results in the line being treated as a verbatim block (along with any following lines until an empty line is found).
This is rather expected, but is worth keeping into account in case we decide to also handle in our dedicated context those inline square-bracketed elements which may also occur on a line of their own (i.e. bear in mind that our filtering RegEx will only pass-on lines which start with a
[and end with a]which might contain trailing spaces or tabs).[ ] Add a «top-level interceptor context» that matches one-liners within square brackets without consuming them, and the push a context that will include all the pertaining contexts.
include:them within the dedicated context, since we'd already already know that the line contains a bracketed element.[ ] Note2: we should account for multiple occurrences of bracketed elements in a single line (e.g.
[#myid][.myrole]), which are malformed but can nevertheless occur — Asciidoctor tends to parse them as if they were a single bracketed group, with the middle][ending up in the first parsed parameter, but results are unpredictable: sometimes one of the two elements is preserved, other times both are rejected, or the result is corrupted parsing.In any case, we should at least scope any extra bracketed groups after the first one as
invalid, to signal to the user that there's a problem in the source doc. If we don't account for such multiple occurrences, the risk is that the whole line is ignored by the RegEx or, worst, it gets handled poorly (with the risk of breaking the document).