GNOLL
An easy to integrate dice notation library for multiple programming languages. Use for instant support of common syntax and a library that can scale with your demands, rather than a sticky taped monstrousity of regular expressions and tears.
Here's an example of how you might use GNOLL:
**Grindon The Brave**: I want to steal from the goblin sitting at the bar.
**Dungeon Master**: Okay, give me a stealth check!
**Grindon The Brave**: Okay, that's a <1d20+5>
[GNOLL]: 21
**Dungeon Master**: Hurrah! You successfully pickpocket the goblin! However, all he had in there were some crummy dice...
You can follow Grindon's full adventure through the world of dice notation in our Documentation.
Many of our notation design decisions are explained in the documentation and compared to other dice notation parsers.
Current Status
🧑💻 Language Support
GNOLL was written to be the definitive solution to dice notation. The core has been written in C, but fear not! You can use GNOLL in many other programming languages too.
Primarily tested on Linux (Ubuntu), but functional in various forms on Windows (10, WSL) and Mac.
🎲 Dice Notation
- XdY notation
- Arithmetic
- Fate Dice
- Miscellaneous Symbolic Dice
- Shorthands & Macros
- Alternate Syntax
- Explosions
- Drop/Keep
- Rerolling
- Filtering
- Functions
There's so many different things, we'd bore you to list them all here. For the specific details of supported notation, check out our documentation.
Getting Started
Usage from a package manager
Python
pip3 install GNOLL
Then, in your code:
from gnoll import roll
roll("1d20")
>> (0, [[12]], None)
# (return code, final result, dice breakdown (if enabled))
🛠️ Installing From Source
Basic Requirements
sudo apt-get install bison flex make python3-pip -y
pip install -r reqs/requirements.txt
make all
To verify your setup, try our tests:
make test
Or, just try some commands yourself!
$ ./build/dice 1d20
20
If you would like to run the 'dice' command from anywhere, use make install to add the executable to your path.
(Note that not all commands may not be able to be used this way as some symbols are reserved for use by different terminal interfaces (e.g. bash uses ! and #))
For languages other than Python/C/C++ call the corresponding make target after the commands above.
🐛 Issues / Bugs / FAQs / Feature Requests
If you encounter any issues or have any ideas, please file them in our Issue Tracker.
✋ Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
🔢 Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
🤹 Authors / Contributers / Attributions
- Ian Hunter - Main Developer - Ianfhunter
See also the list of contributors who participated in this project.
📃 License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE.md file for details.
Individual licensing arrangements can be made if this is an issue for your project - Contact Me at LinkedIn to discuss.
👏 Acknowledgments
- Billie Thompson - README & Contribution Templates - PurpleBooth
- Markdown Badges
🏗️ Built With
- Flex & Bison - Grammar Lexing & Parsing
- uthash - C hashtable lib
- PCG - Random Number Generation
- Arc4Random - Random Number Generation (Cryptographically secure)
- Love! 💖
💰 Donate
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file gnoll-4.4.0-cp312-cp312-manylinux_2_17_x86_64.whl.
File metadata
- Download URL: gnoll-4.4.0-cp312-cp312-manylinux_2_17_x86_64.whl
- Upload date:
- Size: 234.4 kB
- Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/4.0.2 CPython/3.9.18
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
86cc642ebc5070b86c48b5d4d14b8c297c28857c353c7ee0562993333894789e
|
|
| MD5 |
37294ec5c351f128033337b3989af25d
|
|
| BLAKE2b-256 |
3d35162bdfc77281055311788ea423d200911b7189e340d493695f462f16a586
|
File details
Details for the file gnoll-4.4.0-cp311-cp311-macosx_12_0_universal2.whl.
File metadata
- Download URL: gnoll-4.4.0-cp311-cp311-macosx_12_0_universal2.whl
- Upload date:
- Size: 214.9 kB
- Tags: CPython 3.11, macOS 12.0+ universal2 (ARM64, x86-64)
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/4.0.2 CPython/3.11.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c3dca0dafc2706f83ebbd7cad35d3e45f7f41c815d363bceba673cc7788e3688
|
|
| MD5 |
6d4fe3ee5926c8b4e42c29140af67853
|
|
| BLAKE2b-256 |
5cb475503002ff07f2ccbd62a3013eeca6146ed8ef953338656b708e3886e4c6
|
File details
Details for the file gnoll-4.4.0-cp310-cp310-manylinux1_x86_64.whl.
File metadata
- Download URL: gnoll-4.4.0-cp310-cp310-manylinux1_x86_64.whl
- Upload date:
- Size: 234.9 kB
- Tags: CPython 3.10
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/4.0.2 CPython/3.10.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8ce6bca464ef47a1e44dbc06557af894090ab5d8b74ad118d8a35b613c8ab963
|
|
| MD5 |
69f53bda093fbfdc52ee5f0a082d9ed5
|
|
| BLAKE2b-256 |
c156c3731f9d5e619c70de6d355ee456dcabef9506046569ab272ce6966c01c0
|
