Skip to content

Latest commit

 

History

History
75 lines (56 loc) · 3.27 KB

parsing_inline.md

File metadata and controls

75 lines (56 loc) · 3.27 KB
Raw

Inline rules

The inline rules are responsible for parsing inline Markdown syntax formatting only part of a line of text and emitting the tokens required to represent them. For example, a link, bold, emphasis, super/sub scripts, inline code, and so on.

An inline rule is a function expecting two argumnents:

  1. state: an instance of StateInline
  2. checkMode: a flag indicating whether we should simply check if the current position marks the begining of the syntax we are trying to parse.

The checkMode is here for optimization, if it's set to true, we can return true as soon as we are sure the present position marks the beginning of an inline syntax we are trying to parse (For example, in the case of emphasized (italic) text, the check would be "Is the current position a '*' or a '_'?").

State inline

The definition for StateInline prototype is in rules_inline/state_inline.js and its data consists of:

  • src: the complete string the parser is currently working on (i.e. the current line/block content).
  • parser: The current inline parser (here to make nested calls easier)
  • env: a namespaced data key-value store to allow core rules to exchange data
  • tokens: the tokens generated by the parser up to now
  • pos: the current position in src reached by the parser
  • posMax: the last position available in src
  • level: the nested level for the current inline rule

The most important methods are:

  • push(token): adds a new token to the (end of the) output
  • cacheSet(key, value): adds a new value to the cache key-value store. key MUST be a non-negative integer (>= 0) and value MUST a positive integer (> 0)
  • cacheGet(key): fetches a value from the cache key-value store. key MUST be a non-negative integer (>= 0)

Rule parser behaviour

If checkMode is set to true, simply return a boolean depending on whether the current position should be considered has the begining of your syntax. Otherwise, proceed with the complete parsing.

NB: It is your responsibility to make sure you have reached the maximum nesting level allowed by comparing state.level and state.options.maxNesting.

NB: If for any reason, the syntax you are trying to parse is incorrectly formated and you are unable to parse it, you must abort and return false without modifying state in any way.

To completely parse a block, you will need to push new tokens by calling state.push(token).

Once you are sure the current position marks the beginning of the syntax you are trying to parse, you should push an open tag token corresponding to the begining of your inline section. You will also need to find its end.

Your next decision should be whether you wish to allow other inline syntaxes to be nested in your content or not. If you do, you will need to invoke state.parser.tokenize(state) with an updated state accordingly to allow the next batch of rules to run smoothly (incl. updating pos, posMax and level). Don't forget to restore the previous values afterward.

The last token you will need to emit is the end tag token for your inline section.

Finally, you will need to update state.pos to the first position after the part of src you processed and return true.