Skip to content

Handeling Charmaps

theblackswitch edited this page Aug 6, 2026 · 3 revisions

Logo The char map is a key feeature of YAMP. On this page you'll learn how to handle the CHAR_MAP for your custom syntax.

Most parse functions come with a refrence to the main CharMap object. You can use this to modify it so everything works accordingly.

📄Table of contents

📦Char map data structure

Internally, the charmap is first stored as a width map. This map holds the width of each character.

Each line has their own width map array which itself is stored in a big array of lines.

A width of 0 means that the character acts as normal. A width of 2 means that there are 3 cursor positions in the generated html which all correspond to the same markdown character. When the width is set to 255 the character is considered 'discarded' this means that the charater has a width of 0 and thus will be skipped.

This width map makes it a lot easier to handle char maps as the index of each character never changes.

When parsing and generation is done, the full widthmap is converted to an absolute map which maps each html character's index to their corresponding markdown character.

🎚️Parameters

Most parse methods contain a refrence to the main charmap as an argument but there's also a bunch of other parameters related to the char map.

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. So modifying the charmap at this index will correspond to modifying the width of the first character within your input string.

Tip

Make sure to always account for this as it can have unintended effects if the index isn't exactly correct

🧰Methods

There are a bunch of methods which you can use to interact with the char map.

Discard immediately

CHAR_MAP.discard_immediately(line_idx: number, start: number, count: number);

Discard characters from the char map. This should for example be done on the ** in **bold** so they're essentially skipped from the char map.

Arguments

  • line_idx: the index of the line you want to edit. Most of the time this is just the char_map_line passed from your parser
  • start: the start index at which you want to start discarding characters. (remember to account for the char_map_idx parameter)
  • count: the number of characters to discard

Extend Immediately

CHAR_MAP.extend_immediately(line_idx: number, target_idx: number, amount: number);

Increase the width of a certain character within the char map.

Arguments

  • line_idx: the index of the line you want to edit. Most of the time this is just the char_map_line passed from your parser
  • target_idx: the index of the character which you want to extend. (remember to account for the char_map_idx parameter)
  • amoubt: The amount to increase the width of the character with

Que discard event

CHAR_MAP.que_discard_event(line_idx: number, start: number, count: number);

Adds a discard_immediately to the que. It works essentially the same except that you have to run the method apply_que() to fully apply this method. You can use this for example when you still aren't certain if parsing will even succeed.

The que is cleared between each parser so you shouldn't worry about that.

Que discard event

CHAR_MAP.que_extend_event(line_idx: number, target_idx: number, amount: number);

Adds an extend_immediately to the que. It works essentially the same except that you have to run the method apply_que() to fully apply this method. You can use this for example when you still aren't certain if parsing will even succeed.

The que is cleared between each parser so you shouldn't worry about that.

Apply que

CHAR_MAP.apply_que();

Runs all events applied to the que. Run this once you're certain that parsing won't fail anymore.`

Cancel que

CHAR_MAP.cancel_que();

Cancel the que. You shouldn't really need this as this is already called between each parser.parse() call but it's here for you anyways :P

🖼️Example

This is the current implementation of block quotes

static parse(line: string, all_lines: Array<string>, line_idx: number, CHAR_MAP: CharMap, char_map_line: number, charmap_idx: number, ast: ast, parsers: parsers, options: options) {
        if(line.length === 0 || !line.includes('>')) { // Small optimization
            this.check_ast_parsing(ast); // start child AST parsing once we're sure that we've got all lines
            return Parser.FAIL; // no parsing
        }

        let start_idx = 0;
        while(line.charAt(start_idx) === " ") { // Count the number of whitespaces in front
            start_idx++;
        }

        if(line.charAt(start_idx) !== ">") { // Check for the >
            this.check_ast_parsing(ast);
            return Parser.FAIL;
        }

        let blockquote_depth = 1;
        let char = line.charAt(1 + start_idx);

        while(char === ">") { // count the block quote depth
            blockquote_depth++;
            char = line.charAt(blockquote_depth + start_idx);
        }

        if(blockquote_depth === 0 || char !== " ") { // Veryfy a space after all >
            this.check_ast_parsing(ast);
            return Parser.FAIL;
        }
 
        // This is the character offset we were talking about. Each line of the block quote is parsed again
        // as an AST node so we can just parse child block quotes here too. This means that we do need to 
        // account for the offset of the leading spaces and a single > within the char map so each child node
        // is still editing the correct index of the char map.
        let new_charmap_idx = start_idx + 1 + charmap_idx; 

        CHAR_MAP.que_discard_event(char_map_line, start_idx + charmap_idx, 1); // all spaces and a single >

        let text = line.slice(start_idx + blockquote_depth === 1 ? 2 : 1); // remove only a single > for nesting

        if(blockquote_depth === 1) { // If this block quote is only 1 deep, we can also remove the trailing space after >
            CHAR_MAP.que_discard_event(char_map_line, start_idx + charmap_idx + blockquote_depth, 1);
            new_charmap_idx++;
        }

        if(text.length === 0) { // No block quote without text
            this.check_ast_parsing(ast);
            return Parser.FAIL;
        }

        let possible_next_line = all_lines[line_idx + 1]
        let next_line = possible_next_line ? possible_next_line : null;

        CHAR_MAP.apply_que(); // Now we're certain that parsing won't fail so finally apply the char map que
        if(!this.try_extend(ast, text, next_line)) {
            return new BlockQuote(text, next_line, CHAR_MAP, char_map_line, new_charmap_idx, parsers, options);
        }
        return Parser.EXTEND;
    }

Clone this wiki locally