Repository navigation
Custom Single Line Syntax

This page will learn you how you can implement your own custom markdown-like single line syntax.
To make it easier to understand, we'll use a small example. Let's say we want to use the syntax !> to implement a linkable refrence point. For example something like !> important part would turn into <span id="important-part"></span> and we can add #important-part to the url to link to this point.
To implement your syntax, start by extending the class YAMP.SingleLineParser
For example:
class RefrencePoint extends YAMP.SingleLineParser {
}This class has a couple of methods which we can override:
- The static property
static PRIORITY = 10;This is only rarely used to determine the order in which parsers are processed. The default value is 10. Higher values get parsed earlier. - The static method
static init() {}. This method will run once before parsing starts which can be useful to initialize a static variable for example. - The static method
static register_escape_chars(): string | null {}. This method may return a string of characters which may be escaped. More on that later. - The static method
static escape_text(text: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers): string {}Which is used to escape characters inside text using all registered escapable characters. More on that later. - The static method
static parse_inline(text: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers, options: options): string {}You can use this method to apply all inline parsers to a line of text. For example headers apply this to their heading text. More on that later.
And lastly the most important method
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 {}Warning
Even though this method has the same name, it's completely different from InlineParser.parse()
This method will be used to implement our actual syntax. It will run for every line inside the provided markdown input. Let's take a look at all available arguments:
- line: This is the current line in string form
- all_lines: An array containing all lines fomr the provided markdown input
-
line_idx: the index of the current line inside the
all_linesarray - CHAR_MAP: a refrence to the main char map object. More on that later
- char_map_line: The index of the line at which the input string is located. More on that later
- char_map_idx: An offset to the index of the current input string inside the char map. More on that later
- ast: An array containing all already parsed nodes. Log this to get a better idea of how the internal ast looks.
- parsers: An array containing all enabled features
- options: A way to access the options object. You can add any custom keys inside that object.
This method has basically 2 return options. It returns YAMP.Parser.FAIL to indicate that the syntax isn't complete to form this feature. Or it return s a new object from the current class. That means this class will both be used to parse the syntax and generate it.
The implementation may look like this for our example:
class RefrencePoint extends YAMP.SingleLineParser {
this.#id: string;
constructor(id) {
super(); // Js bullshit
this.#id = id;
}
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) {
if(!line.includes('>')) return Parser.FAIL; // We can't parse any lines that don't have the required characters
let start_idx = 0;
while(input.charAt(start_idx) === " ") { // Count the amount of leading whitespace
start_idx++;
}
if(input.charAt(start_idx) !== "!" || input.charAt(start_idx + 1) !== ">") return Parser.Fail; // Detect the right syntax
let id = input.slice(start_idx + 3); // 3 since we also have to ignore the space
id = YAMP.StringHelper.to_ascii(id);
return new RefrencePoint(id);
}
}Now we're succesfully parsing a line of text, checking if it contains our syntax and returning an object of our class for the custom syntax. From now on we'll call this object from any class an "AST node" or a "Node object".
Tip
You may have seen the usage of YAMP.StringHelper please refer to the String Utilities Page for more information about this class.
We've gor parsing working but that doesn't mean our syntax is generating. To generate our syntax, we can implement a (non static) generate(options) method. It also comes with the parameter options which is a refrence to the options object. You can add any custom keys here.
Each node must have this method implemented and the method should return a string.
For our example that would be:
class RefrencePoint extends YAMP.SingleLineParser {
this.#id: string;
constructor(id) {
super(); // Js bullshit
this.#id = id;
}
...
generate(options) {
return `<span id="${this.#id}"></span>`;
}
}In our syntax we'd also like to be able to just write a normal !> sequence. This can be done by allowing both characters to be escaped so people can write \!>, !\> or \!\> which all turn into !>
To register an escape character we can use the static register_escape_chars() {} method you've seen before. This will result in our code looking like this:
class RefrencePoint extends YAMP.SingleLineParser {
this.#id: string;
...
static register_escape_chars() {
return ">!"; // No need to put them in the right order
}
}Now the last thing we have to do is update the charmap according to our changes. Our syntax should be completely removed from the Char Map since we aren't producing any resulting characters in the html.
To do this we can interact with the provided CHAR_MAP argument. Please refer to Handeling Charmaps for more information.
This means our code would look something like this:
class RefrencePoint extends YAMP.SingleLineParser {
...
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) {
if(!line.includes('>')) return Parser.FAIL; // We can't parse any lines that don't have the required characters
let start_idx = 0;
while(input.charAt(start_idx) === " ") { // Count the amount of leading whitespace
start_idx++;
}
if(input.charAt(start_idx) !== "!" || input.charAt(start_idx + 1) !== ">") return Parser.Fail; // Detect the right syntax
// 3 since we also have to ignore the space
CHAR_MAP.discard_immediately(char_map_line, 0, char_map_idx + start_idx + 3);
let id = input.slice(start_idx + 3);
return new RefrencePoint(id);
}
}Inline parsing isn't done automatically. This is not possible because there are only certain parts where the inline syntax is even applicable. That's why you can use the method
static parse_inline(text: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers, options: options): string {}This method takes all required data, and processes the input string with all inline parsers and returns a modified string. This method will also escape the text with all registered escapable characters.
Warning
This method will return fully parsed html, that means that the index of the charaters does not align with the charmap anymore. Thus it's not a good idea to apply any more modifications to this string.
Arguments:
- text: This is the text that should be modified
- CHAR_MAP: A refrence to the main CharMap object.
- char_map_line: This is the index of the current line in the charmap and is required to make sure you're editing the correct part of the charmap.
- char_map_idx: This is the index offset of the first character of your input string within the char map. If you're only passing a part of the string, make sure to adjust this offset accordingly. Take a look at Handeling Charmaps for more information.
- parsers: An array of all enabled parsers
- options: A refrence to the main options object. This is needed so inline parsers can also access the options.
Return
- string: the modified output string from all inline parsers.
Much like inline parsing, escaping characters also isn't done automatically. If you want the characters in your string to be escaped but don't want any inline parsers to touch it, you can use this method:
static escape_text(text: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers)It works much the same as parse_inline, returning the modified string.
Warning
This method will remove characters from the output string, that means that the index of the charaters does not align with the charmap anymore. Thus it's not a good idea to apply any more modifications to this string.
Arguments:
- text: This is the text that should be modified
- CHAR_MAP: A refrence to the main CharMap object.
- char_map_line: This is the index of the current line in the charmap and is required to make sure you're editing the correct part of the charmap.
- char_map_idx: This is the index offset of the first character of your input string within the char map. If you're only passing a part of the string, make sure to adjust this offset accordingly. Take a look at Handeling Charmaps for more information.
- parsers: An array of all enabled parsers
~ wiki by theblackswitch