Download the PHP package hiqdev/hoa-compiler without Composer

Reasons to fork

The Hoa project was archived, and no upgrades or patches are neither provided nor accepted by merge requests.

HOA Packages include some code that is Deprecated for PHP 8.0 and PHP 8.1, but we needed these packages to run on modern PHP versions.

What's changed in from?

The changes mainly affected the return data type hinting in methods declaration, access to uninitialized properties.

How to use

We've currently forked the following packages, primarily to make hoa/ruler work with PHP 8.1:

You can simply replace requirements in composer.json from hoa packages to the corresponding forked packages: there is no need to change something in the codebase.

If you use someone's package, that requires hoa – simply add forks to your project root composer.json: we have marked forks as a replacement, so composer will install them instead of the original packages.

Versions

We've forked from the latest hoa package versions and bump own versions starting from 1.0.

Testing

Before running the test suites, the development dependencies must be installed:

Then, to run all the test suites:

For more information, please read the contributor guide.

Quick usage

As a quick overview, we will look at the PP language and the LL(k) compiler compiler.

The PP language

A grammar is constituted by tokens (the units of a word) and rules (please, see the documentation for an introduction to the language theory). The PP language declares tokens with the following construction:

The default namespace is default. The value of a token is represented by a PCRE. We can skip tokens with the %skip construction.

As an example, we will take the simplified grammar of the JSON language. The complete grammar is in the hoa://Library/Json/Grammar.pp file. Thus:

We can see the PP constructions:

• rule() to call a rule;
• <token> and ::token:: to declare a token;
• | for a disjunction;
• (…) to group multiple declarations;
• e? to say that e is optional;
• e+ to say that e can appear at least 1 time;
• e* to say that e can appear 0 or many times;
• e{x,y} to say that e can appear between x and y times;
• #node to create a node the AST (resulting tree);
• token[i] to unify tokens value between them.

Unification is very useful. For example, if we have a token that expresses a quote (simple or double), we could have:

So, the data "foo" and 'foo' will be valid, but also "foo' and 'foo"! To avoid this, we can add a new constraint on token value by unifying them, thus:

All quote[0] for the rule instance must have the same value. Another example is the unification of XML tags name.

LL(k) compiler compiler

The Hoa\Compiler\Llk\Llk class provide helpers to manipulate (load or save) a compiler. The following code will use the previous grammar to create a compiler, and we will parse a JSON string. If the parsing succeed, it will produce an AST (stands for Abstract Syntax Tree) we can visit, for example to dump the AST:

Pretty simple.

Compiler in CLI

This library proposes a script to parse and apply a visitor on a data with a specific grammar. Very useful. Moreover, we can use pipe (because Hoa\File\Read —please, see the Hoa\File library— supports 0 as stdin), thus:

You can apply any visitor classes.

Errors

Errors are well-presented:

Samplers

Some algorithms are available to generate data based on a grammar. We will give only one example with the coverage-based generation algorithm that will activate all branches and tokens in the grammar:

Research papers

• Grammar-Based Testing using Realistic Domains in PHP, presented at A-MOST 2012 (Montréal, Canada) (article, presentation, details).

Documentation

The hack book of Hoa\Compiler contains detailed information about how to use this library and how it works.

To generate the documentation locally, execute the following commands:

More documentation can be found on the project's website: hoa-project.net.

Getting help

There are mainly two ways to get help:

• On the #hoaproject IRC channel,
• On the forum at users.hoa-project.net.

Contribution

Do you want to contribute? Thanks! A detailed contributor guide explains everything you need to know.

License

Hoa is under the New BSD License (BSD-3-Clause). Please, see LICENSE for details.