roll-parser

    2.3.2 • Public • Published

    Roll Parser

    Parser for classic (2d6+1), simple (2 6 1), and WoD (4d10!>6f1) dice rolls.

    Travis Build Status AppVeyor Build Status Coverage Status devDependency Status

    Node.js version Project is on npm

    Documentation

    Please review the API documentation.

    Install

    Node:

    npm install roll-parser
    

    Then in the console or JS file:

    const rollParser = require('roll-parser');

    Browser:

    <script src="https://unpkg.com/roll-parser/dist/roll-parser.js"></script>

    Minified version:

    <script src="https://unpkg.com/roll-parser/dist/roll-parser.min.js"></script>

    Then access all functions from rollParser object.

    Console:

    $ roll-parser [options] [<rolls>]

    Run roll-parser --help for more details.

    Usage

    const { parse, roll, parseAndRoll, Roll } = require('roll-parser');
     
    // `parse()` function parses any notation and returns `Roll` or `WodRoll` object
    //=> { dice: 6, count: 4, modifier: 1 }
    const parsedRoll = parse('4d6+1');
     
    // `Roll` or `WodRoll` can be stringified
    //=> '4d6+1'
    const rollNotation = parsedRoll.toString();
     
    //=> { notation: '4d6+1', value: 16, rolls: [3, 1, 6, 5] }
    const result1 = roll(parsedRoll);
    //=> { notation: '2d20-3', value: 23, rolls: [11, 15] }
    const result2 = roll(new Roll(20, 2, -3));
    // Can also accept plain objects
    //=> { notation: '2d10>7', value: 1, rolls: [4, 8] }
    const result3 = roll({dice: 10, count: 2, success: 7});
     
    // `parseAndRoll()` function can parse any notation and then roll the dice
    // Any invalid arguments, except `null` or `undefined`, will be parsed as default `Roll`
    //=> { notation: '3d10!>8f1', value: 2, rolls: [3, 10, 7, 9] }
    const result4 = parseAndRoll('3d10!>8f1');
     
    //=> '(3d10!>8f1) 2 [3,10,7,9]'
    const resultNotation = result4.toString();

    Specific parsers can be used.

    Classic (D&D):

    const {
      parseClassicRoll,
      rollClassic,
      parseAndRollClassic,
      Roll 
    = require('roll-parser');
     
    //=> { dice: 10, count: 1, modifier: 0 }
    const parsedRoll = parseClassicRoll('d10');
     
    //=> { notation: 'd10', value: 7, rolls: [7] }
    const result1 = rollClassic(parsedRoll);
     
    //=> { notation: '2d20', value: 26, rolls: [11, 15] }
    const result2 = rollClassic(new Roll(20, 2));
     
    //=> { notation: '4d10+1', value: 22, rolls: [4, 6, 2, 9] }
    const result3 = rollClassic({ dice: 10, count: 4, modifier: 1 });
     
    //=> { notation: '3d6', value: 15, rolls: [6, 6, 3] }
    const result4 = parseAndRollClassic('3d6');

    WoD (World of Darkness):

    const {
      parseWodRoll,
      rollWod,
      parseAndRollWod,
      WodRoll 
    = require('roll-parser');
     
    //=> { dice: 10, count: 1, again: false, success: 6, fail: 0 }
    const parsedRoll = parseWodRoll('d10>6');
     
    // Returns notation, number of success rolls and list of all dice rolls
    //=> { notation: 'd10', value: 1, rolls: [7] }
    const result1 = rollWod(parsedRoll);
     
    //=> { notation: '4d10>6f1', value: 1, rolls: [4, 10, 5, 2] }
    const result2 = rollWod(new WodRoll(10, 4, false, 6, 1));
     
    //=> { notation: '4d10!>8f1', value: 22, rolls: [1, 8, 5, 10, 10, 4] }
    const result3 = rollWod({ dice: 10, count: 2, again: true, success: 8, fail: 1 });
     
    //=> { notation: '4d10>7f4', value: 1, rolls: [6, 3, 8, 4] }
    const result4 = parseAndRollWod('4d10>7f4');

    Simple (D&D, space-separated):

    const { parseSimpleRoll, parseAndRollSimple } = require('roll-parser');
     
    //=> { dice: 10, count: 1, modifier: 0 }
    const parsedRoll = parseSimpleRoll('10');
     
    //=> { notation: '4d10-1', value: 23, rolls: [3, 6, 8, 7] }
    const result = parseAndRollSimple('4 10 -1');

    Random number generator can be used to roll the dice.

    const { random } = require('roll-parser');
     
    //=> 84 - d100-like roll
    random(100);
     
    //=> 7 - d10-like roll
    random(10);
     
    //=> [2, 5, 2, 6] - 4d6-like roll
    [...Array(4)].map(() => random(6));

    Even so the parse&roll functions uses checks to convert non-standard objects to Roll or WodRoll, explicit conversion can be used in some cases:

    const { convert } = require('roll-parser');
     
    //=> new Roll(undefined, 4, -3)
    convert({ count: 4, modifier: -3 });
     
    //=> new WodRoll(10, 6, true, undefined, 2)
    convert({ dice: 10, count: 6, again: true, fail: 2 });

    Releases

    Please review the changelog.

    Contributing

    roll-parser and want to get involved?
    Please, check the guide first.

    License

    MIT © Mikita Taukachou

    Install

    npm i roll-parser

    DownloadsWeekly Downloads

    181

    Version

    2.3.2

    License

    MIT

    Last publish

    Collaborators

    • edloidas