Download the PHP package kuria/parser without Composer

Parser ######

Character-by-character string parsing library.

:depth: 2

Features

• line number tracking (can be disabled for performance)
• supports CR, LF and CRLF line endings
• verbose exceptions
• many methods to navigate and operate the parser
• forward / backward peeking and seeking
• forward / backward character consumption
• state stack
• character types
• expectations

Requirements

• PHP 7.1+

Usage

Creating a parser

Create a new parser instance with string input.

The parser begins at the first character.

$input = 'foo bar baz';

$parser = new Parser($input);

Parser properties

The parser has several public properties that can be used to inspect its current state:

• $parser->i - current position
• $parser->char - current character (or NULL at the end of input)
• $parser->lastChar - last character (or NULL at the start of input)
• $parser->line - current line (or NULL if line tracking is disabled)
• $parser->end - end of input indicator (TRUE at the end, FALSE otherwise)
• $parser->vars - user-defined variables attached to the current state

Parser method overview

Refer to doc comments of the respective methods for more information.

Also see Character types.

Static methods

• getCharType($char): int - determine character type
• getCharTypeName($charType): string - get human-readable character type name

Instance methods

• getInput(): string - get the input string
• setInput($input): void - replace the input string (this also resets the parser)
• getLength(): int - get length of the input string
• isTrackingLineNumbers(): bool - see if line number tracking is enabled
• type(): int - get type of the current character
• is(...$types): bool - check whether the current character is of one of the specified types
• atNewline(): bool - see if the parser is at the start of a newline sequence
• eat(): ?string - go to the next character and return the current one (returns NULL at the end)
• spit(): ?string - go to the previous character and return the current one (returns NULL at the beginning)
• shift(): ?string - go to the next character and return it (returns NULL at the end)
• unshift(): ?string - go to the previous character and return it (returns NULL at the beginning)
• peek($offset, $absolute = false): ?string - get character at the given offset or absolute position (does not affect state)
• seek($offset, $absolute = false): void - alter current position
• reset(): void - reset states, vars and rewind to the beginning
• rewind(): void - rewind to the beginning
• eatChar($char): ?string - consume specific character and return the next character
• tryEatChar(): bool - attempt to consume specific character and return success state
• eatType($type): string - consume all characters of the specified type
• eatTypes($typeMap): string - consume all characters of the specified types
• eatWs(): string - consume whitespace, if any
• eatUntil($delimiterMap, $skipDelimiter = true, $allowEnd = false): string - consume all characters until the specified delimiters
• eatUntilEol($skip = true): string - consume all character until end of line or input
• eatEol(): string - consume end of line sequence
• eatRest(): string - consume reamaining characters
• getChunk($start, $end): string - get chunk of the input (does not affect state)
• detectEol(): ?string - find and return the next end of line sequence (does not affect state)
• countStates(): int - get number of stored states
• pushState(): void - store the current state
• revertState(): void - revert to the last stored state and pop it
• popState(): void - pop the last stored state without reverting to it
• clearStates(): void - throw away all stored states
• expectEnd(): void - ensure that the parser is at the end
• expectNotEnd(): void - ensure that the parser is not at the end
• expectChar($expectedChar): void - ensure that the current character matches the expectation
• expectCharType($expectedType): void - ensure that the current character is of the given type

Example INI parser implementation

/ INI parser (example) / class IniParser { / Parse an INI string / public function parse(string $string): array { // create parser $parser = new Parser($string);

// prepare variables $data = []; $currentSection = null;

// parse while (!$parser->end) { // skip whitespace $parser->eatWs(); if ($parser->end) { break; }

// parse the current thing if ($parser->char === '[') { // a section $currentSection = $this->parseSection($parser); } elseif ($parser->char === ';') { // a comment $this->skipComment($parser); } else { // a key=value pair [$key, $value] = $this->parseKeyValue($parser);

// add to output if ($currentSection === null) { $data[$key] = $value; } else { $data[$currentSection][$key] = $value; }

}

}

return $data;

arse a section and return its name

ate function parseSection(Parser $parser): string

// we should be at the [ character now, eat it $parser->eatChar('[');

// eat everything until ] $sectionName = $parser->eatUntil(']');

return $sectionName;

kip a commented-out line

ate function skipComment(Parser $parser): void

// we should be at the ; character now, eat it $parser->eatChar(';');

// eat everything until the end of line $parser->eatUntilEol();

arse a key=value pair

ate function parseKeyValue(Parser $parser): array

// we should be at the first character of the key // eat characters until = is found $key = $parser->eatUntil('=');

// eat everything until the end of line // that is our value $value = trim($parser->eatUntilEol());

return [$key, $value];

}

Using the parser

$iniString = <<<INI ; An example comment name=Foo type=Bar

[options] size=150x100 onload= INI;

$data = $iniParser->parse($iniString);

print_r($data);

Output:

Array
(
    [name] => Foo
    [type] => Bar
    [options] => Array
        (
            [size] => 150x100
            [onload] =>
        )

)

Character types

The table below lists the default character types.

These types are available as constants on the Parser class:

• Parser::C_NONE - no character (NULL)
• Parser::C_WS - whitespace (tab, linefeed, vertical tab, form feed, carriage return and space)
• Parser::C_NUM - numeric character (0-9)
• Parser::C_STR - string character (a-z, A-Z, _ and any 8-bit char)
• Parser::C_CTRL - control character (ASCII 127 and ASCII < 32 except whitespace)
• Parser::C_SPECIAL - !"#$%&'()*+,-./:;<=>?@[\\]^\`{|}~

Customizing character types

Character types can be customized by extending the base Parser class.

The following example changes "-" and "." from CHAR_SPECIAL to CHAR_STR and inherits everything else.

var_dump($parser->eatType(CustomParser::C_STR));

Output:

string(11) "foo-bar.baz"