README

A generic RPG dice roller syntax and library.

Getting started

php-dice is designed to work out of the box. It means that installation requires minimal steps.

Download

php-dice can be installed using composer. Run following command to download and install php-dice:

composer require "fr-esco/php-dice"

Usage

As shown in index.php, once required the library, you can instantiate the parser:

$parser = new dice\Parser;

Then, you can parse your expression:

$result = $parser->parse($expression);

Later in your code, you can evaluate the parsed result, where the returned object can be inspected for debugging purposes:

$result->evaluate();

Finally, you can print out either a raw string representation of the parsed expression or its beautified version by running respectively:

echo $result;
# or
echo $result->render();

The final result is stored in its value property.

$result->value;

Exception Handling

You should always wrap the parsing phase in a try / catch block:

try {
    $result = $parser->parse($expression);
} catch (dice\SyntaxError $ex) {
    $stack = ['Syntax error:', $ex->getMessage(),
        'At line', $ex->grammarLine,
        'column', $ex->grammarColumn,
        'offset', $ex->grammarOffset];
    echo implode(' ', $stack);
}

Customization

You can also optionally provide a custom scope with additional functions or variables that should be evaluated:

$result = $parser->parse($expression, [
    'foo' => 2,
    'bar' => function () {
        return 3;
    },
], '\custom\namespace\Scope');

You can provide an associative array using as key any at least 2 characters long string that could appear in your expression, and as value any number or function to execute (see DefaultScope implementation for examples).

You can also specify your Scope Class, that has to extend dice\Scope.

Example

• Expression (space-insensitive): d6 + foo * bar() / defaultSides + min(d12, 2d4) + rerollBelow(5, 3d6)
• Render after evaluation: { 1d6 : [ 2 ] } + { foo : 2 } * { bar ( ): 3 } / { defaultSides : 6 } + { min ( { 1d12 : [ 10 ] }, { 2d4 : [ 1, 2 ] } ): 3 } + { rerollBelow ( 5, { 3d6 : [ 6, 6, 4 ] } ): 18 }
• Stringified version: 1d6 + foo * bar() / defaultSides + min(1d12, 2d4) + rerollBelow(5, 3d6)
• Value (rolled): 24

Development

Technology Stack

The grammar is built with PEG.js. Its PHP version is generated by php-pegjs.

Customization

If you need to customize the grammar/dice.pegphp, you can regenerate src/Parser via Javascript:

# Install node modules
npm install

# Build dice\Parser for PHP
npm run build

Visual Test

Serve index.php with your favourite webserver and browse to http://localhost/php-dice/index.php.

You can enter the expression to parse in the textbox and submit the form by clicking on the "Roll" button.

Details and results will be shown below.

License

php-dice is released under the MIT License. See the bundled LICENSE.md for details.