This is the documentation for the unsupported version 0.18. Please consider upgrading your code to the latest stable version

Block Parsing

Block parsers should extend from AbstractBlockParser and implement the following method:

parse()

When parsing a new line, the DocParser iterates through all registered block parsers and calls their parse() method. Each parser must determine whether it can handle the given line; if so, it should parse the given block and return true.

Parameters

Return value

parse() should return false if it’s unable to handle the current line for any reason. (The Cursor state should be restored before returning false if modified). Other parsers will then have a chance to try parsing the line. If all registered parsers return false, the line will be parsed as text.

Returning true tells the engine that you’ve successfully parsed the block at the given position. It is your responsibility to:

  1. Advance the cursor to the end of syntax indicating the block start
  2. Add the parsed block via $context->addBlock()

Tips

Block Elements

In addition to creating a block parser, you may also want to have it return a custom “block element” - this is a class that extends from AbstractBlock and represents that particular block within the AST.

Block elements also play a role during the parsing process as they tell the underlying engine how to handle subsequent blocks that are found.

AbstractBlockElement Methods

Method Purpose
canContain(...) Tell the engine whether a subsequent block can be added as a child of yours
acceptsLines() Whether this block can accept lines of text (inline nodes). If true, handleRemainingContents() may be called
handleRemainingContents(...) This is called when a block has been created but some other text still exists on that line
isCode() Returns whether this block represents <code>
matchesNextLine(...) Returns whether this block continues onto the next line (some blocks are multi-line)
shouldLastLineBeBlank() Returns whether the last line should be blank (primarily used by ListItem elements)
finalize(...) Finalizes the block after all child items have been added, thus marking it as closed for modification

For examples on how these methods are used, see the core block element classes included with this library.