Repository navigation
Handeling Charmaps
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.
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.
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.
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.
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
There are a bunch of methods which you can use to interact with the char map.
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_linepassed from your parser -
start: the start index at which you want to start discarding characters. (remember to account for the
char_map_idxparameter) - count: the number of characters to discard
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_linepassed from your parser -
target_idx: the index of the character which you want to extend. (remember to account for the
char_map_idxparameter) - amoubt: The amount to increase the width of the character with
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.
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.
CHAR_MAP.apply_que();Runs all events applied to the que. Run this once you're certain that parsing won't fail anymore.`
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
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;
}~ wiki by theblackswitch