Package: dice-notation
This notation is widely used on tabletop games, such as wargames or RPGs, and
was created on the late 70s for Dungeons & Dragons, as a way to allow generating
random values in specific distributions.With the pass of years it has evolved, and while it never underwent a formal
standarization process a core set of rules is kept among all the variations,
mostly representing dice in a format such as ‘1d6’, and the use of algebra
operations like addition and subtraction.This project aims to give support to the dice notation, allowing parsing and
operating with it on any Python application.FeaturesANTLR-based parser generates objects from dice notation (BNF grammar included)Easy-to-use model, just call the ‘roll’ methodClasses to support plain diceDocumentationDocumentation sources are included with the project, and used to generate the
documentation sites:Thelatest docsare always generated for the latest release, kept in the ‘master’ branchThedevelopment docsare generated from the latest code in the ‘develop’ branchThe source files for the docs, a smallSphinxproject, are kept in the ‘docs folder.These can be built if needed:python setup.py build_docsPrerequisitesThe project has been tested in the following versions of the interpreter:Python 3.6Python 3.7Python 3.8All other dependencies are indicated on the requirements.txt file.These can be installed with:pip install--upgrade-rrequirements.txtBuilding the grammarFirst of all install ANTLRas told here.Afterwards, followthese indications.The command to generate the parser will be:antlr4-Dlanguage=Python2DiceNotation.g4 DiceNotationLexer.g4InstallingThe project is offered as aPypi package, and using pip is the preferred way
to install it. For this use the following command;pip installdice-notationIf needed, manual installation is possible:python setup.py installUsageThe application has been coded in Python, and does not require any particular
framework.To use it just import the parser:from dice_notation.parser import DiceParserAnd then use it to parse a dice notation expression:parser = DiceParser()
dice = parser.parse('1d6+2')The result can be accessed just by calling the ‘value’ method as many times as
needed, which will generate a new random value each time it is called:print(dice.roll())
print(dice.roll())TestingThe tests included with the project can be run with:python setup.py testThis will delegate the execution to tox.It is possible to run just one of the test profiles, in this case the py36 profile:python setup.py test-p"py38"CollaborateAny kind of help with the project will be well received, and there are two main ways to give such help:Reporting errors and asking for extensions through the issues managementor forking the repository and extending the projectIssues managementIssues are managed at the GitHubproject issues tracker, where any Github
user may report bugs or ask for new features.Getting the codeIf you wish to fork or modify the code, visit theGitHub project page, where
the latest versions are always kept. Check the ‘master’ branch for the latest
release, and the ‘develop’ for the current, and stable, development version.LicenseThe project has been released under theMIT License.