Repository navigation
Custom Multi Line Syntax
This page will learn you how you can implement your own custom markdown-like multi-line syntax. This implementation is very similar to the Custom Single Line Synax so go take a look there.
To make it easier to understand, we'll use a small example. Let's say we want to implement the syntax
<This is expandable>
| # Heading
| text
| another linewhich allows us to write expandable sections that turn into the following html
<details>
<summary>This is expandable</summary>
<h1>Heading</h1>
<p>text<br>another line</p>
</details>To implement your syntax, start by extending the class YAMP.MultilineParser
For example:
class Collapsible extends YAMP.MultilineParser {
}Ontop of all methods from the SingleLineParser, there is one more method we can override:
- The (non static) method
extend(...any_paramenters). More on that later
Now we can start by parsing the first <This is expandable> just like you would do for a SingleLineParser.
That could look like:
class Collapsible extneds YAMP.MultilineParser {
#summary;
constructor(summary: string) {
this.#summary = summary;
}
static parse(line: string, all_lines: Array<string>, line_idx: number, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, ast: ast, parsers: parsers, options: options): parser_fail | parser_extend | ast_node | null {
if(input.charAt(0) !== "<" || input.charAt(input.length - 2 /* the last character is always a newline */) !== ">") return YAMP.Parser.FAIL;
// remove the < and > from the charmap as they aren't in the output html
CHAR_MAP.discard_immediately(char_map_line, char_map_idx, 1);
CHAR_MAP.discard_immediately(char_map_line, char_map_idx + input.length - 2, 1);
// Collect the actual summary text
let summary = input.splice(1, input.length - 3);
// Apply inline parsers to the summary text so we can also bold it
summary = this.parse_inline(summary, CHAR_MAP, char_map_line, char_map_idx + 1, parsers, options);
return new Collapsible(summary);
}
}Ontop of the AST nodeobject or YAMP.Parser.FAIL, the parse method of a multiline parser can also return YAMP.Parser.Extend This means that the current line got extended and thus added by the previous node.
We can use this feature to extend all sub-sequent lines below the summary and add them to the Collapsible node object we're already constructing.
For that we have 2 methods:
- The (non static)
extend(...any_arguments). This overridable method will be called on a previous node when the next line tries to extend this node. This function can returnfalseif extending failed ortrueif extending succeeded - The
static try_extend(ast, ...any_arguments). This method will try to extend the previous node. If will returntrueif extending succeeded andfalseif it failed. You can append any arguments here and they'll be passed to theextend(...any_arguments)`` method.
For our syntax this might look something like:
class Collapsible extneds YAMP.MultilineParser {
#summary: string;
#lines = [];
constructor(summary: string) {
this.#summary = summary;
}
extend(line) {
this.#lines.push(line);
}
static parse(line: string, all_lines: Array<string>, line_idx: number, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, ast: ast, parsers: parsers, options: options): parser_fail | parser_extend | ast_node | null {
if(input.charAt(0) === "|" && input.charAt(1) === " ") { // check for the `| ` syntax
let line = input.slice(2); // Account for the space too
if(this.try_extend(ast, line)) {
return YAMP.Parser.Extend;
}
return YAMP.Parser.Fail;
}
if(input.charAt(0) !== "<" || input.charAt(input.length - 2 /* the last character is always a newline */) !== ">") return YAMP.Parser.FAIL;
// remove the < and > from the charmap as they aren't in the output html
CHAR_MAP.discard_immediately(char_map_line, char_map_idx, 1);
CHAR_MAP.discard_immediately(char_map_line, char_map_idx + input.length - 2, 1);
// Collect the actual summary text
let summary = input.splice(1, input.length - 3);
// Apply inline parsers to the summary text so we can also bold it
summary = this.parse_inline(summary, CHAR_MAP, char_map_line, char_map_idx + 1, parsers, options);
return new Collapsible(summary);
}
}We'd also like to be able to add any other single line syntax inside of our collapsed blocks. This means we'll need to implement a sub-ast inside of our node. Luckly we can use the method ```ts static parse_single_line(line: string, lines: Array, line_idx: number, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, ast: ast, parsers: parsers, options: options, allow_self = false): parser_extend | ast_node {}
Let's break down it's arguments:
- <ins>line</ins>: the current line to be parsed
- <ins>lines</ins>: a list of all lines within this sub ast
- <ins>line_idx</ins>: the index of the current line within the lines array
- <ins>CHAR_MAP</ins>: a refrence to the main CharMap object
- <ins>char_map_line</ins>: the index of the current line in the charmap and is required to make sure you're editing the correct part of the charmap.
- <ins>
To start, let's make a method for parsing our ast.
class Collapsible extneds YAMP.MultilineParser { static parse() }
~ wiki by theblackswitch