<commit_before># roll

Roll is a node.js package for rolling dice and adding modifiers (such as "2d6+1").

## Installation

    $ npm install roll

## How To Use

Rolling dice:

    var roll = require('roll');
    var twoTwenties = roll.roll('2d20');
    console.log(twoTwenties.result); //random number between 2 and 40 (inclusive)

Rolling a percentage:

    var roll = require('roll');
    var chance = roll.roll('d%'); //same as '1d100', 'd100', or '1d%'
    console.log(chance.result); //random number between 1 and 100 (inclusive)

Simple calculation (+, -, *, /):

    var roll = require('roll');
    var attack = roll.roll('2d6+2');
    console.log(attack.result); //random number between 3 and 8 (inclusive)

Seeing what was rolled, rather than the sum:

    var roll = require('roll');
    var yahtzee = roll.roll('5d6');
    console.log(yahtzee.rolled); //yahtzee.rolled will return something like [5, 2, 4, 6, 1] rather than the sum

Getting the highest three dice of the set:

    var roll = require('roll');
    var pickBestTwo = roll.roll('6d20b3'); //roll 6 dice and give me the 3 highest
    console.log(pickBestTwo.calculations[1]); //pickBestTwo.calculations[0] is the same as .result, .calculations[1] is prior to the sum operation

Processing rolls without parsing a string:

    var roll = require('roll');
    var attack = roll.roll({
        quantity: 2,
        sides: 6,
        transformations: [ //can list n-number of pipeline operations to perform on the result
          'sum', //take the array of rolled dice and sum them together
          ['add', 2] //add 2 to the sum
        ]
    });
    console.log(attack.result); //random number between 3 and 8 (inclusive)

Using custom transformations:

    var roll = require('roll');
    var dropOnes = function(result){
      var nextResult = [];
      for(var i = 0; i < result.length; i++)
        if(result[i] !== 1)
          nextResult.push(result[i]);
      return nextResult;
    };
    var noOnes = roll.roll({
      quantity: 5,
      sides: 4,
      transformations: [
        dropOnes, // remove any 1s because we have teh lucky bootz
        'sum'
      ]
    });

Using a custom seed:

    var srand = require('srand'); //https://github.com/isaacs/node-srand (npm install srand)
    srand.seed(1000);
    
    var roll = require('roll');
    roll.random = function(){ return srand.rand(); };
    
    console.log(roll.roll('2d6+5').result);

## Credits

Inspired by [<NAME>'s Games::Dice](http://search.cpan.org/~pne/Games-Dice-0.02/Dice.pm).

## License

[MIT License](http://www.opensource.org/licenses/mit-license.php)

## Author

[<NAME>](https://github.com/TroyGoode) ([<EMAIL>](mailto:<EMAIL>))<commit_msg>added support for GitHub's syntax highlighting to README<commit_after># roll

Roll is a node.js package for rolling dice and adding modifiers (such as "2d6+1").

## Installation

```bash
$ npm install roll
```

## How To Use

Rolling dice:

```javascript
var roll = require('roll');
var twoTwenties = roll.roll('2d20');
console.log(twoTwenties.result); //random number between 2 and 40 (inclusive)
```

Rolling a percentage:

```javascript
var roll = require('roll');
var chance = roll.roll('d%'); //same as '1d100', 'd100', or '1d%'
console.log(chance.result); //random number between 1 and 100 (inclusive)
```

Simple calculation (+, -, *, /):

```javascript
var roll = require('roll');
var attack = roll.roll('2d6+2');
console.log(attack.result); //random number between 3 and 8 (inclusive)
```

Seeing what was rolled, rather than the sum:

```javascript
var roll = require('roll');
var yahtzee = roll.roll('5d6');
console.log(yahtzee.rolled); //yahtzee.rolled will return something like [5, 2, 4, 6, 1] rather than the sum
```

Getting the highest three dice of the set:

```javascript
var roll = require('roll');
var pickBestTwo = roll.roll('6d20b3'); //roll 6 dice and give me the 3 highest
console.log(pickBestTwo.calculations[1]); //pickBestTwo.calculations[0] is the same as .result, .calculations[1] is prior to the sum operation
```

Processing rolls without parsing a string:

```javascript
var roll = require('roll');
var attack = roll.roll({
    quantity: 2,
    sides: 6,
    transformations: [ //can list n-number of pipeline operations to perform on the result
      'sum', //take the array of rolled dice and sum them together
      ['add', 2] //add 2 to the sum
    ]
});
console.log(attack.result); //random number between 3 and 8 (inclusive)
```

Using custom transformations:

```javascript
var roll = require('roll');
var dropOnes = function(result){
  var nextResult = [];
  for(var i = 0; i < result.length; i++)
    if(result[i] !== 1)
      nextResult.push(result[i]);
  return nextResult;
};
var noOnes = roll.roll({
  quantity: 5,
  sides: 4,
  transformations: [
    dropOnes, // remove any 1s because we have teh lucky bootz
    'sum'
  ]
});
```

Using a custom seed:

```javascript
var srand = require('srand'); //https://github.com/isaacs/node-srand (npm install srand)
srand.seed(1000);
    
var roll = require('roll');
roll.random = function(){ return srand.rand(); };
    
console.log(roll.roll('2d6+5').result);
```

## Credits

Inspired by [<NAME>'s Games::Dice](http://search.cpan.org/~pne/Games-Dice-0.02/Dice.pm).

## License

[MIT License](http://www.opensource.org/licenses/mit-license.php)

## Author

[<NAME>](https://github.com/TroyGoode) ([<EMAIL>](mailto:<EMAIL>))
{'fraction_non_alphanumeric': 0.15303673620084918, 'fraction_numerical': 0.023260107070334133, 'mean_word_length': 3.4702970297029703, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 11, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6562311', 'n_tokens_mistral': 1873, 'n_tokens_neox': 1757, 'n_words': 555}