Cursor
A Cursor is essentially a fancy string wrapper that remembers your current position as you parse it. It contains a set of highly-optimized methods making it easy to parse characters, match regular expressions, and more.
Supported Encodings
As of now, only UTF-8 (and, by extension, ASCII) encoding is supported.
Usage
Instantiating a new Cursor is as simple as:
use League\CommonMark\Parser\Cursor;
$cursor = new Cursor('Hello World!');
Or, if you’re creating a custom block parser or inline parser, a pre-configured Cursor will be provided to you with (with the Cursor already set to the current position trying to be parsed).
Methods
You can then call any of the following methods to parse the string within that Cursor:
| Method | Purpose |
|---|---|
getPosition() |
Returns the current position/index of the Cursor within the string |
getColumn() |
Returns the current column (used when handling tabbed indentation) |
getIndent() |
Returns the current amount of indentation |
isIndented() |
Returns whether the cursor is indented to INDENT_LEVEL |
getCharacter(int $index) |
Returns the character at the given absolute position |
getCurrentCharacter() |
Returns the character at the current position |
peek() |
Returns the next character without changing the current position of the cursor |
peek(int $offset) |
Returns the character $offset chars away without changing the current position of the cursor |
getNextNonSpacePosition() |
Returns the position of the next character which is not a space or tab |
getNextNonSpaceCharacter() |
Returns the next character which isn’t a space (or tab) |
advance() |
Moves the cursor forward by 1 character |
advanceBy(int $characters) |
Moves the cursor forward by $characters characters |
advanceBy(int $characters, true) |
Moves the cursor forward by $characters characters, handling tabs as columns |
advanceBySpaceOrTab() |
Advances forward one character (and returns true) if it’s a space or tab; returns false otherwise |
advanceToNextNonSpaceOrTab() |
Advances forward past all spaces and tabs found, returning the number of such characters found |
advanceToNextNonSpaceOrNewline() |
Advances forward past all spaces and newlines found, returning the number of such characters found |
advanceToEnd() |
Advances the position to the very end of the string, returning the number of such characters passed |
match(string $regex) |
Attempts to match the given $regex; returns null if matching fails, otherwise it advances past and returns the matched text |
getPreviousText() |
Returns the text that was just advanced through during the last advance__() or match() operation |
getRemainder() |
Returns the contents of the string from the current position through the end of the string |
isBlank() |
Returns whether the remainder is blank (we’re at the end or only space characters remain) |
isAtEnd() |
Returns whether the cursor has reached the end of the string |
saveState() |
Encapsulates the current state of the cursor into an array in case you need to restoreState() later |
restoreState($state) |
Pass the result of saveState() back into here to restore the original state of the Cursor |
getLine() |
Returns the entire string (not taking the position into account) |