Download the PHP package phug/reader without Composer

Phug Reader

What is Phug Reader?

The Reader-class is a small utility that can parse and scan strings for specific entities.

It's mostly based on Regular Expressions, but also brings in tools to scan strings and expressions of any kind (e.g. string escaping, bracket counting etc.)

The string passed to the reader is swallowed byte by byte through consume-mechanisms. When the string is empty, the parsing is done (usually).

This class is specifically made for lexical analysis and expression-validation.

Installation

Install via Composer

Usage

Basics

The process of reading with the Phug\Reader involves peeking and consuming. You peek, check, if it's what you wanted and if it is, you consume.

read-methods on the Reader will peek and consume automatically until they found what you searched for. match-methods work like peek, but work with regular expressions.

Lets create a small example code to parse:

Now we create a reader for that code

If you want a fixed encoding, use the second $encoding parameter.

Now we can do our reading process. First we want to read our identifier. We can do that easily with readIdentifier() which returns null if no identifier has been encountered and the identifier found otherwise. It will stop on anything that is not an identifier-character (The space after the identifier, in this case)

To get to our =-character directly, we can just skip all spaces we encounter. This also allows for any spacing you want (e.g. you can indent the above with tabs if you like)

If we need the spaces, we can always catch the returned result. If no spaces are encountered, it just returns null.

Now we want to parse the assignment-operator (=) (or rather, validate that it's there)

Skip spaces again

and read the string. If no quote-character (" or ') is encountered, it will return null. Otherwise, it will return the (already parsed) string, without quotes. Notice that you have to check null explicitly, since we could also have an empty string ("") which evaluates to true in PHP

The quote-style encountered will be escaped by default, so you can scan "some \" string" correctly. If you want to add other escaping, use the first parameter of readString.

Now you have all parts parsed to make up your actual action

and it was validated on that way.

This was just a small example, Phug Reader is made for loop-parsing.

Build a small tokenizer

Keep expressions intact

Sometimes you want to keep expressions intact, e.g. when you allow inclusion of third-party-code that needs to be parsed separately.

The Reader brings a bracket-counting-utility that can do just that exactly. Let's take Jade as an example:

To parse this, let's do the following:

You now got a parser for (really, really basic) Jade-elements! It can handle as many attributes as you like with all possible values you could think of without ever breaking the listing, regardless of contained commas and brackets.

Digging deeper, the Phug Reader is actually able to lex source code and text of any kind.