Skip to content

Custom Single Line Syntax

theblackswitch edited this page Aug 6, 2026 · 6 revisions

Logo

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.

📄Table of contents

📝Creating the class

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_lines array
  • 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.

🧩Parsing

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.

⚙️Generating

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>`;
  }
}

®️Registering Escapable Characters

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
  }
}

🗺️Char Maps

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);
  } 
}

🧩Parsing inline text

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.

🚫Escaping characters

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

Clone this wiki locally