GNOLL

Test: Functionality Test: Language Bindings Test: OS Support

CodeFactor Codacy Badge

status TTRPG compatibility rate GitHub license GitHub last commit Donate

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.

C C++ C# Go Haskell Java JavaScript Julia Perl PHP Python R Ruby

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

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

🏗️ Built With

  • Flex & Bison - Grammar Lexing & Parsing
  • uthash - C hashtable lib
  • PCG - Random Number Generation
  • Arc4Random - Random Number Generation (Cryptographically secure)
  • Love! 💖

💰 Donate

Keep this project alive

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.5.5)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ianfhunter from gravatar.com ianfhunter

Credits

Author: Ian Frederick Vigogne Goodbody Hunter

License

GNU General Public License v3 (GPLv3), MIT License

Requires

Python >=3.6

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

gnoll-4.3.4-cp312-cp312-manylinux_2_17_x86_64.whl (234.4 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

gnoll-4.3.4-cp312-cp312-macosx_12_0_universal2.whl (214.9 kB view details)

Uploaded CPython 3.12macOS 12.0+ universal2 (ARM64, x86-64)

gnoll-4.3.4-cp311-cp311-manylinux_2_17_x86_64.whl (233.1 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

gnoll-4.3.4-cp311-cp311-macosx_12_0_universal2.whl (213.6 kB view details)

Uploaded CPython 3.11macOS 12.0+ universal2 (ARM64, x86-64)

gnoll-4.3.4-cp310-cp310-manylinux1_x86_64.whl (233.6 kB view details)

Uploaded CPython 3.10

File details

Details for the file gnoll-4.3.4-cp312-cp312-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for gnoll-4.3.4-cp312-cp312-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 63a871efe9be998b9d6f4470994b232c6b4a410deb431fc1f4acd99f412e5ed7
MD5 73b14ad922380142c7c6acd7c75ae448
BLAKE2b-256 3830ea99c533a0f674ace41f0de003fe9feb3092f77e3e1f9ce8aead8afc7bf3

See more details on using hashes here.

File details

Details for the file gnoll-4.3.4-cp312-cp312-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for gnoll-4.3.4-cp312-cp312-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 fb67e3f1ecaf2a22160746f2b3c2dede78170731459c70cd8e1bc5218a5be716
MD5 8617450113fb0e4b37b77f717f717707
BLAKE2b-256 fd3a7b04f137726bfff08e5b89a16ceedb7ef0a5f18228cb67a056738c1c9420

See more details on using hashes here.

File details

Details for the file gnoll-4.3.4-cp311-cp311-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for gnoll-4.3.4-cp311-cp311-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 1cb6b41a7ba5a47b12eba21f84bc19c44b729288c8e9de7ea41dcbc9deae2138
MD5 7b2d62c2a0f90b8507c94018c4246e67
BLAKE2b-256 095d8f43c9dfdd653a50f3b1ac6f8ad7241f08aad8d29fc38345e253a88a6097

See more details on using hashes here.

File details

Details for the file gnoll-4.3.4-cp311-cp311-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for gnoll-4.3.4-cp311-cp311-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 414f71f91f26cce17c82d73e2e57f7ef9df87e8cadcc91751c389b5e78f1b9e5
MD5 6df10c1afe5af92eb160d2ce1703fced
BLAKE2b-256 65a30d04cc143d1c579b760b26a47fcadaa3b6b6381d20943db842144104830d

See more details on using hashes here.

File details

Details for the file gnoll-4.3.4-cp310-cp310-manylinux1_x86_64.whl.

File metadata

File hashes

Hashes for gnoll-4.3.4-cp310-cp310-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 58d0f841aac6f1b628974c01d408b3a6ab40ed47d0a11b1c021d781028d98ec0
MD5 129e9c9078466c611ecea86600164adb
BLAKE2b-256 18b3ef9fd35b365e6500a5716041d4c77a899fc4580d5adf424cde0fd4d06a83

See more details on using hashes here.

Release history Release notifications | RSS feed

4.5.5

2 files

4.5.3

1 file

4.5.2

1 file

4.4.0

3 files

This release

4.3.4 This release

5 files

4.3.0

3 files

4.2.7

2 files

4.2.5

2 files

4.2.0

2 files

4.1.0

2 files

4.0.1

2 files

3.2.0

2 files

3.1.0

2 files

3.0.0

2 files

2.12.0

2 files

2.11.1

2 files

2.11.0

2 files

2.10.0

2 files

2.9.0

2 files

2.8.9

2 files

2.8.8

2 files

2.8.7

2 files

2.8.5

2 files

2.8.4

2 files

2.8.3

2 files

2.8.2

2 files

2.8.1

2 files

2.7.2

2 files

2.7.0

2 files

2.6.0

2 files

2.5.0

2 files

2.4.2

2 files

2.4.1

2 files

2.4.0

2 files

2.3.7

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page