fr-esco/php-dice

A generic RPG dice roller syntax and library.

php-dice

A generic RPG dice roller syntax and library., _(*1)

Getting started

php-dice is designed to work out of the box. It means that installation requires minimal steps., _(*2)

Download

php-dice can be installed using composer. Run following command to download and install php-dice:, _(*3)

composer require "fr-esco/php-dice"

Usage

As shown in index.php, once required the library, you can instantiate the parser:, _(*4)

$parser = new dice\Parser;

Then, you can parse your expression:, _(*5)

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

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

$result->evaluate();

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

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

The final result is stored in its value property., _(*8)

$result->value;

Exception Handling

You should always wrap the parsing phase in a try / catch block:, _(*9)

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:, _(*10)

$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)., _(*11)

You can also specify your Scope Class, that has to extend dice\Scope., _(*12)

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., _(*13)

Customization

If you need to customize the grammar/dice.pegphp, you can regenerate src/Parser via Javascript:, _(*14)

# 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., _(*15)

You can enter the expression to parse in the textbox and submit the form by clicking on the "Roll" button., _(*16)

Details and results will be shown below., _(*17)

License

php-dice is released under the MIT License. See the bundled LICENSE.md for details., _(*18)