Skip to content

Custom Multi Line Syntax

theblackswitch edited this page Aug 6, 2026 · 8 revisions

Logo 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 line

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

As you can see we'll also allow other parsers to run within our own text.

📄Table of contents

📝Creating the class

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

🥇Parsing the first line

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

➕Extending lines

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 return false if extending failed or true if extending succeeded
  • The static try_extend(ast, ...any_arguments). This method will try to extend the previous node. If will return trueif 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 extends 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);
  }
}

🧩Parsing Single lines

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

static parse_single_line(line: string, lines: Array<string>, 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:

  • line: the current line to be parsed
  • lines: a list of all lines within this sub ast
  • line_idx: the index of the current line within the lines array
  • CHAR_MAP: a refrence to the main CharMap object
  • char_map_line: 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.
  • ast: a refrence to our locally stored AST (which is just an array of node objects)
  • parsers: a list of all enabled parsers
  • options: a refrence to the main options object
  • allow_self: whether to allow parsing our own class within our sub ast. For example block quotes have this set to true since you can put blockquotes inside blockquotes.

Since we need to pass a list of all lines within the sub-ast, we have parse the ast after we know that our node can't be extended any more. For now let's start by making a method to parse our ast

class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];
  #ast = [];

  constructor(summary: string) {
    this.#summary = summary;
  }

  extend(line) {
    this.#lines.push(line);
  }

  parse_ast() {
    this.#ast = [];
        for(const [idx, line] of this.#lines.entries()) {
            let ast_node = Collapsible.parse_single_line(line, this.#lines, idx, CHAR_MAP ??, char_map_line ??, char_map_idx ??, this.#ast, parsers ??, options ??, false /* don't allow ourselves */);
            if(ast_ast_node !== Parser.EXTEND) {
                this.#ast.push(ast_node);
            }
        }
  }

  ...

}

As you can see, we're missing quite a few arguments. The only way to get them is to store them from our parse function so let's do that.

class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];
  #parsers: parsers = [];
  #options: options;
  #ast: ast = [];
  CHAR_MAP: CharMap;
  char_map_idx: number;
  char_map_line: number;

  constructor(summary: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers, options: options) {
    this.#summary = summary;
    this.#parsers = parsers;
    this.#options = options;
    this.CHAR_MAP = CHAR_MAP;
    this.char_map_idx = char_map_idx;
    this.char_map_line = char_map_line;
  }

  extend(line) {
    this.#lines.push(line);
  }

  parse_ast() {
    this.#ast = [];
        for(const [idx, line] of this.#lines.entries()) {
            let ast_node = Collapsible.parse_single_line(line, this.#lines, idx, this.CHAR_MAP, this.char_map_line + idx, this.char_map_idx, this.#ast, this.#parsers, this.#options, false /* don't allow ourselves */);
            if(ast_ast_node !== Parser.EXTEND) {
                this.#ast.push(ast_node);
            }
        }
  }

  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 {
    ...

    let new_charmap_idx = char_map_idx + 2; // one for the `|` and one for the ` `

    return new Collapsible(summary, CHAR_MAP, char_map_line, new_charmap_idx, parsers, options);
  }
}

Okay now that's out of the way we can start to implement the actual ast parsing when we're certain that we've got all lines. We'll do this by looking at the next line.

class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];
  #parsers: parsers = [];
  #options: options;
  #ast: ast = [];
  CHAR_MAP: CharMap;
  char_map_idx: number;
  char_map_line: number;

  constructor(summary: string, next_line: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers, options: options) {
    this.#summary = summary;
    this.#parsers = parsers;
    this.#options = options;
    this.CHAR_MAP = CHAR_MAP;
    this.char_map_idx = char_map_idx;
    this.char_map_line = char_map_line;
    if(next_line === null) this.parse_ast();
  }

  extend(line: string, next_line: string | null) {
    this.#lines.push(line);
    if(next_line === null) this.parse_ast(); // If there is no next line, parse the ast
  }

  ...

  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
      let possible_next_line = all_lines[line_idx + 1];
      let next_line = possible_next_line ? possible_next_line : null;

      if(this.try_extend(ast, line, next_line)) {
        return YAMP.Parser.Extend;
      }

      this.check_ast_parsing(ast);
      return YAMP.Parser.Fail;
    }

    if(input.charAt(0) !== "<" || input.charAt(input.length - 2 /* the last character is always a newline */) !== ">") {
      this.check_ast_parsing(ast);
      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);

    let new_charmap_idx = char_map_idx + 2; // one for the `|` and one for the ` `
    let possible_next_line = all_lines[line_idx + 1];
    let next_line = possible_next_line ? possible_next_line : null;

    return new Collapsible(summary, next_line, CHAR_MAP, char_map_line, new_charmap_idx, parsers, options);
  }

  // check if the previous node is a Collapsible and parse it's ast. We'll call this when we detect a parsing fail.
  static check_ast_parsing(ast: ast) {
    let prev_ast_node = ast[ast.length - 1];
    if(prev_ast_node instanceof BlockQuote) {
      prev_ast_node.parse_ast();
    }
  }
}

⚙️Generating

Nice, we're finally done with parsing. Now lets get that thing generating, shall we?

To get the output of each of our parsed ast nodes, we can just call the generate(options) method on them.

class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];
  #parsers: parsers = [];
  #options: options;
  #ast: ast = [];
  CHAR_MAP: CharMap;
  char_map_idx: number;
  char_map_line: number;

  ...
  
  generate(options) {
    let out = "<details>";
    out += `<summary>${this.#summary}</summary>`;
    for(const ast_node of this.#ast) {
      if(IsTypeOf.cachedAstNode(ast_node)) continue;
      out+=`${ast_node.generate(options)}`;
    }
    out += "</details>";
    return out;
  }
}

# ®️Registering escape chars
That'll look like this
```ts
class Collapsible extends YAMP.MultilineParser {
  ...

  static register_escape_chars() {
    return "<>|";
  }
}

✅Done!

Voila we're finally done. This is our finished code:

```ts
class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];
  #parsers: parsers = [];
  #options: options;
  #ast: ast = [];
  CHAR_MAP: CharMap;
  char_map_idx: number;
  char_map_line: number;

  constructor(summary: string, next_line: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers, options: options) {
    this.#summary = summary;
    this.#parsers = parsers;
    this.#options = options;
    this.CHAR_MAP = CHAR_MAP;
    this.char_map_idx = char_map_idx;
    this.char_map_line = char_map_line;
    if(next_line === null) this.parse_ast();
  }

  extend(line: string, next_line: string | null) {
    this.#lines.push(line);
    if(next_line === null) this.parse_ast(); // If there is no next line, parse the ast
  }

  parse_ast() {
    this.#ast = [];
        for(const [idx, line] of this.#lines.entries()) {
            let ast_node = Collapsible.parse_single_line(line, this.#lines, idx, this.CHAR_MAP, this.char_map_line + idx, this.char_map_idx, this.#ast, this.#parsers, this.#options, false /* don't allow ourselves */);
            if(ast_ast_node !== Parser.EXTEND) {
                this.#ast.push(ast_node);
            }
        }
  }

  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
      let possible_next_line = all_lines[line_idx + 1];
      let next_line = possible_next_line ? possible_next_line : null;

      if(this.try_extend(ast, line, next_line)) {
        return YAMP.Parser.Extend;
      }

      this.check_ast_parsing(ast);
      return YAMP.Parser.Fail;
    }

    if(input.charAt(0) !== "<" || input.charAt(input.length - 2 /* the last character is always a newline */) !== ">") {
      this.check_ast_parsing(ast);
      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);

    let new_charmap_idx = char_map_idx + 2; // one for the `|` and one for the ` `
    let possible_next_line = all_lines[line_idx + 1];
    let next_line = possible_next_line ? possible_next_line : null;

    return new Collapsible(summary, next_line, CHAR_MAP, char_map_line, new_charmap_idx, parsers, options);
  }

  // check if the previous node is a Collapsible and parse it's ast. We'll call this when we detect a parsing fail.
  static check_ast_parsing(ast: ast) {
    let prev_ast_node = ast[ast.length - 1];
    if(prev_ast_node instanceof BlockQuote) {
      prev_ast_node.parse_ast();
    }
  }
  
  generate(options) {
    let out = "<details>";
    out += `<summary>${this.#summary}</summary>`;
    for(const ast_node of this.#ast) {
      if(IsTypeOf.cachedAstNode(ast_node)) continue;
      out+=`${ast_node.generate(options)}`;
    }
    out += "</details>";
    return out;
  }

  static register_escape_chars() {
    return "<>|";
  }
}

Tip

If you'd like more examples, go take a look in the src/syntax folder of this repo. All yamp's syntax is also implemented like this.

Clone this wiki locally