{"id":16580033,"url":"https://github.com/brianbruggeman/dice","last_synced_at":"2026-05-31T02:31:47.095Z","repository":{"id":146698863,"uuid":"99988655","full_name":"brianbruggeman/dice","owner":"brianbruggeman","description":"A DSL for rolling dice build in python","archived":false,"fork":false,"pushed_at":"2021-03-05T16:44:07.000Z","size":36,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-16T09:37:51.111Z","etag":null,"topics":["dice","dsl","notation","python","python3"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brianbruggeman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-11T03:40:55.000Z","updated_at":"2022-07-27T05:35:57.000Z","dependencies_parsed_at":"2023-04-03T10:31:09.539Z","dependency_job_id":null,"html_url":"https://github.com/brianbruggeman/dice","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbruggeman%2Fdice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbruggeman%2Fdice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbruggeman%2Fdice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbruggeman%2Fdice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brianbruggeman","download_url":"https://codeload.github.com/brianbruggeman/dice/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242117717,"owners_count":20074438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dice","dsl","notation","python","python3"],"created_at":"2024-10-11T22:19:52.937Z","updated_at":"2026-05-31T02:31:47.087Z","avatar_url":"https://github.com/brianbruggeman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dice\nA [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for dice notation built in python using [Lark](https://github.com/erezsh/lark).\n\n## Motivation\n\nI wanted a chance to build a meaningful DSL using a library (Lark) that\nI haven't tried previously.\n\n\n## Usage\n\n\n### CLI\n\nThe following represents how to run the parser from the command-line\ninterface:\n\n    $ roll 6x4d6M3\n    --------------------------------------------------\n     Formula: 6x4d6M3\n    --------------------------------------------------\n     10\n     10\n     12\n     8\n     10\n     11\n    --------------------------------------------------\n     Sum: 61\n     Ave: 10\n    --------------------------------------------------\n\n\n### API\n\nThe following represents an example usage of using this package's programmatic API:\n\n\n    #!/usr/bin/env python3\n    from dice import parse\n\n\n    def roll(formula, seed=10):\n        \"\"\"Rolls dice based on formula\n\n        Args:\n            formula (str): formula to roll [e.g. 3d6]\n            seed (int): random number generator seed\n\n        Returns:\n            List[int]: values rolled\n\n        \"\"\"\n        values = [value for value in parse(formula=formula, seed=seed)]\n        return values\n\n\n## Installation\n\nThis can be installed directly into a virtual environment using pip:\n\n    pip install -e git://github.com/brianbruggeman/dice.git@main#egg=dice\n\n\n\n## Dice Notation Rules\n\nThere's a nice [wiki page](https://en.wikipedia.org/wiki/Dice_notation) on dice notation.\n\nThe current grammar (in case this document doesn't get updated well) can be found\nunder [dice/dice.lark](dice/dice.lark).\n\n### Math\n\nBasic math operations are as follows\n\n| Rule     | Notation | Example | Description                                               |\n|----------|----------|---------|-----------------------------------------------------------|\n| dice     | d        | 3d6     | Rolls a dice (e.g. 6) a specific number of times (e.g. 3) |\n| percent  | d%       | d%      | Rolls a 100-sided die                                     |\n| plus     | +        | 1 + 2   | Simple add                                                |\n| minus    | -        | 1 - 2   | Simple subtraction                                        |\n| multiply | *        | 1 * 2   | Simple multiplication                                     |\n| division | /        | 2 / 2   | Simple division                                           |\n\n\n### Filtering\n\nAdditionally, the following provides a mechanism for filtering data\n\n| Rule       | Notation | Example | Description                                                        |\n|------------|----------|---------|--------------------------------------------------------------------|\n| maximum    | M        | 4d6M3   | Pick the highest rolls from formula (e.g. best 3 rolls out of 4)   |\n| minimum    | m        | 4d6m3   | Pick the lowest rolls from formula (e.g. worst 3 rolls out of 4)   |\n| over       | \u003e        | 4d6\u003e3   | Pick only the rolls over a threshold from formula                  |\n| under      | \u003c        | 4d6\u003c4   | Pick only the rolls under a threshold from formula                 |\n| equal      | ==       | 4d6==5  | Pick only the rolls that equal a value from formula                |\n| notequal   | !=       | 4d6!=5  | Pick only the rolls that don't equal a value from formula          |\n| overequal  | \u003e        | 4d6\u003e=3  | Pick only the rolls over or equal to a threshold from formula      |\n| underequal | \u003c=       | 4d6\u003c=3  | Pick only the rolls under or equal to a threshold from formula     |\n\n\n### Control\n\nFinally, there are ways of controlling output\n\n| Rule       | Notation | Example | Description                                                             |\n|------------|----------|---------|-------------------------------------------------------------------------|\n| iteration  | x        | 6x4d6M3 | Repeat the formula multiple times (e.g. create 6 values using 4d6M3 )   |\n\n\n## Testing\n\nThis package uses [pytest](https://github.com/pytest-dev/pytest).\n\n### Testing Setup\n\nTo setup, simply clone the repo and run:\n\n    pip install -e .[all]\n    \n### Running tests\n\nTo run the tests, at the top of the repo run:\n\n    pytest\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrianbruggeman%2Fdice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrianbruggeman%2Fdice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrianbruggeman%2Fdice/lists"}