Merge branch 'main' into Matlab

ianfhunter · Nov 25, 2023 · 1f61e22 · 1f61e22
2 parents 09eec0f + 8ff47ec
commit 1f61e22
Show file tree

Hide file tree

Showing 57 changed files with 1,064 additions and 366 deletions.
diff --git a/.github/workflows/publish_PyPi.yml b/.github/workflows/publish_PyPi.yml
@@ -27,25 +27,25 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install wheel
+        pip install wheel setuptools
         make python
         ls src/python
         echo "-------"
         ls src/python/code/gnoll/
     - name: Build package
       working-directory: ./src/python/
       run: |
-        python setup.py bdist_wheel --plat-name=manylinux1_x86_64
+        python setup.py bdist_wheel --plat-name=manylinux_2_17_x86_64
     - name: Publish package
       uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
       with:
         packages_dir: ./src/python/dist
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN_2022 }}
-        # password: ${{ secrets.TEST_PYPI_API_TOKEN }}
-        # repository_url: https://test.pypi.org/legacy/
-        
-  deploy_windows:
+        #password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        #repository_url: https://test.pypi.org/legacy/
+
+  deploy_wsl:
     runs-on: windows-2022
 
     steps:
@@ -70,18 +70,19 @@ jobs:
         export PATH="/root/.local/bin:$PATH"
         python3 -m pip install --upgrade pip
         python3 -m pip install wheel twine
+        python3 -m pip install --upgrade setuptools
         make python
         ls src/python
         echo "-------"
         ls src/python/code/gnoll/
     - name: Build package
+      shell: wsl-bash {0}
       working-directory: ./src/python/
       run: |
-        touch ~/.pypirc
-        export PATH="/root/.local/bin:$PATH"
-        python3 setup.py bdist_wheel
+        # touch ~/.pypirc
+        python3 setup.py bdist_wheel  --plat-name=manylinux1_x86_64
         python3 -m twine upload dist/* --non-interactive -u __token__ -p ${{ secrets.PYPI_API_TOKEN_2022 }}
-#        python3 -m twine upload dist/* --non-interactive -u __token__ -p ${{ secrets.TEST_PYPI_API_TOKEN }} -r https://test.pypi.org/legacy/
+        # python3 -m twine upload dist/* --non-interactive -u __token__ -p ${{ secrets.TEST_PYPI_API_TOKEN }} --repository-url https://test.pypi.org/legacy/
 
   deploy_mac:
     runs-on: macos-12
@@ -97,7 +98,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install wheel twine
+        pip install wheel twine setuptools
         make python
         ls src/python
         echo "-------"

diff --git a/.github/workflows/test_OS.yml b/.github/workflows/test_OS.yml
@@ -26,6 +26,8 @@ jobs:
       run: |
         make all
         ./build/dice d20
+        make install
+        dice d100
 
   build_win:
 

diff --git a/.github/workflows/test_core.yml b/.github/workflows/test_core.yml
@@ -30,3 +30,8 @@ jobs:
         make test USE_SECURE_RANDOM=1
     - name: Lex/Yacc Fallback
       run: make test LEX_FALLBACK=1 YACC_FALLBACK=1
+    - name: Test installation
+      run: |
+        make install
+        dice --version
+        dice --help
diff --git a/.github/workflows/test_language_bindings.yml b/.github/workflows/test_language_bindings.yml
@@ -83,14 +83,8 @@ jobs:
       run: |
         sudo apt update
         sudo apt install cabal-install haskell-stack ghc
-        # curl -O https://downloads.haskell.org/~ghc/8.10.7/ghc-8.10.7-x86_64-deb10-linux.tar.xz
-        #  tar xvf ghc-8.10.7-x86_64-deb10-linux.tar.xz
-        #  cd ghc-8.10.7 && ./configure
-        # cd ghc-8.10.7 && make install
         ghc --version
         cabal update
-        # stack init
-        # stack --resolver lts-18 build
     - name: make haskell
       run: |
           make haskell
@@ -124,14 +118,26 @@ jobs:
         version: "10.0"
     - name: python deps
       run: python3 -m pip install -r reqs/requirements.txt
+    - name: apt prerequisites
+      run: |
+        sudo apt install clang-14 lld-14 llvm-14 libjs-d3 python3-numpy
+        sudo apt install llvm -y
     - name: javascript prerequisites
       run: |
-        sudo apt install clang-14 lld-14 llvm-14 nodejs libjs-d3 python3-numpy
-        sudo apt install nodejs llvm -y
-        wget -c http://archive.ubuntu.com/ubuntu/pool/universe/e/emscripten/emscripten_3.1.6~dfsg-5_all.deb
-        sudo apt install ./emscripten_3.1.6~dfsg-5_all.deb
+        # NodeJS
+        curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+        sudo apt-get install -y nodejs
+        # Acorn-Node
+        git clone https://github.com/acornjs/acorn.git
+        cd acorn ; npm install ; cd -
+        # Emscripten
+        git clone https://github.com/emscripten-core/emsdk.git
+        cd emsdk ; ./emsdk install latest ; cd - 
+        # wget --no-verbose -c http://archive.ubuntu.com/ubuntu/pool/universe/e/emscripten/emscripten_3.1.6~dfsg-5_all.deb
+        # sudo apt install -f ./emscripten_3.1.6~dfsg-5_all.deb nodejs- node-acorn- # ignore nodejs acorn max version
     - name: make js
       run: |
+        cd emsdk ; ./emsdk activate latest ; source ./emsdk_env.sh ; cd -
         emcc -v
         make js
         node ./build/js/a.out.js 1d20

diff --git a/.github/workflows/test_packages.yml b/.github/workflows/test_packages.yml
@@ -19,9 +19,8 @@ jobs:
     - uses: actions/checkout@v2
     - name: Test PyPi
       run: |
-        python3 -m pip install gnoll 
-        # --index-url https://test.pypi.org/simple/
-        python3 -c "from gnoll.parser import roll; roll('d34')"
+        python3 -m pip install gnoll # --index-url https://test.pypi.org/simple/
+        python3 -c "from gnoll import roll; roll('d34')"
 
   pypi_windows:
     name: "PyPi: Windows"
@@ -43,8 +42,8 @@ jobs:
     - name: Test Windows
       shell: wsl-bash {0}
       run: |
-        python3 -m pip install gnoll --index-url https://test.pypi.org/simple/
-        python3 -c "from gnoll.parser import roll; roll('d34')"
+        python3 -m pip install gnoll # --index-url https://test.pypi.org/simple/
+        python3 -c "from gnoll import roll; roll('d34')"
 
   pypi_mac:
     name: "PyPi: MacOS"
@@ -54,7 +53,6 @@ jobs:
       - name: Build
         run: make all
       - name: Test
-        run: |       
-          python3 -m pip install gnoll 
-          # --index-url https://test.pypi.org/simple/
-          python3 -c "from gnoll.parser import roll; roll('d34')"
+        run: |
+          python3 -m pip install gnoll # --index-url https://test.pypi.org/simple/
+          python3 -c "from gnoll import roll; roll('d34')"
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,22 +1,41 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
 cff-version: 1.2.0
-message: "If you use this software, please cite it as below."
+title: >-
+  GNOLL: Efficient Multi-Lingual Software for Real-World
+  Dice Notation and Extensions
+message: 'If you use this software, please cite it using the following metadata'
+type: software
 authors:
-- family-names: "Hunter"
-  given-names: "Ian Frederick Vigogne Goodbody"
-  orcid: "https://orcid.org/0000-0003-3408-8138"
-title: "GNOLL"
-version: 1.0.0
-date-released: 2022-05-30
-url: "https://github.com/ianfhunter/GNOLL"
-preferred-citation:
-  type: unpublished
-  authors:
-  - family-names: "Hunter"
-    given-names: "Ian Frederick Vigogne Goodbody"
-    orcid: "https://orcid.org/0000-0003-3408-8138"
-  year: 2022
-  month: 5
-  start: 1 # First page number
-  end: 11 # Last page number
-  title: "GNOLL: Efficient Software for Real-World Dice Notation and Extensions"
-
+  - given-names: Ian Frederick Vigogne Goodbody
+    family-names: Hunter
+    email: [email protected]
+    name-particle: Ian
+    orcid: 'https://orcid.org/0000-0003-3408-8138'
+identifiers:
+  - type: doi
+    value: 10.21105/joss.04816
+    description: JOSS Paper
+repository-code: 'https://github.com/ianfhunter/GNOLL'
+url: 'https://www.ianhunter.ie/GNOLL/'
+abstract: >-
+  GNOLL is an open-source library for parsing commonly used
+  dice notations in gaming system
+
+  research and/or software development. GNOLL is performant,
+  supports most popular and obscure
+
+  notations, has permissive licensing, and is integratable
+  into many other systems due to it being
+
+  written in C
+keywords:
+  - dice notation
+  - dice
+  - board games
+  - tabletop roleplaying games
+license: GPL-3.0
+commit: 3bd126678e4c87b652eabe535701faec8d0fab04
+version: v4.3.2
+date-released: '2023-01-17'
diff --git a/GNOLL.ini b/GNOLL.ini
@@ -1,4 +1,4 @@
 ; Placeholder file for future configuration setting. Currently unused
 [Meta Information]
-version = v3.2.0
+version = v4.4.0
 ttrpg_compatibility_rate = 98.66
diff --git a/Makefile b/Makefile
@@ -11,7 +11,7 @@ else
    STANDARD= -std=c99
 endif
 
-
+.DEFAULT_GOAL := all
 
 OPT=-O3 \
     $(STANDARD) -Wall -Wextra -Werror -pedantic -Wcast-align \
@@ -114,6 +114,10 @@ CFILE_SUBDIRS=rolls util operations external
 all: clean yacc lex compile shared
 	echo "== Build Complete =="
 
+install: all
+	mkdir -p /usr/local/bin/
+	cp build/dice /usr/local/bin/dice
+
 yacc:
 	mkdir -p build
 	$(foreach BD,$(CFILE_SUBDIRS),mkdir -p build/$(BD))

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@
 ![GitHub last commit](https://img.shields.io/github/last-commit/ianfhunter/GNOLL.svg)  [![Donate](https://img.shields.io/badge/Donate-Paypal-yellow.svg)](https://paypal.me/ianfhunter)
 
 <p align="center">
- <img src="https://raw.githubusercontent.com/ianfhunter/GNOLL/main/media/gnoll_xmas.png" height="200">
+ <img src="https://raw.githubusercontent.com/ianfhunter/GNOLL/main/media/gnoll.png" height="200">
 </p>
 
 An easy to integrate [dice notation](https://en.wikipedia.org/wiki/Dice_notation) library for multiple programming languages.
@@ -77,9 +77,19 @@ pip3 install GNOLL
 
 Then, in your code:
 ```python
-from gnoll.parser import roll
+from gnoll import roll
 roll("1d20")
->> 7
+>> (0, [[12]], None)
+# (return code, final result, dice breakdown (if enabled))
+```
+
+Or, use the command-line interface (see `--help`):
+```sh
+$ python3 -m gnoll 2d4
+6
+$ function gnoll() { python3 -m gnoll --breakdown "$@" ; }
+$ gnoll 3d6 + 10
+[5, 5, 4] --> 24
 ```
 
 ### 🛠️ Installing From Source
@@ -97,9 +107,11 @@ make test
 Or, just try some commands yourself!
 
 ```bash
-$ ./dice 1d20
+$ ./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.

diff --git a/doc/JOSS/paper.bib b/doc/JOSS/paper.bib
@@ -5,7 +5,7 @@ @inproceedings{Mogensen2006DiceRollingMI
 }
 
 @misc{DNDDemographics2019,
-    title={a History Check on 2019 | D\&D's best year ever\_2019},
+    title={a History Check on 2019 | {D}\&{D}'s best year ever\_2019},
     year={2020},
     author={{Natalt Design}},
     publisher={Wizards of The Coast}
@@ -32,7 +32,7 @@ @inproceedings{TROLL
     language = "English",
     isbn = "978-1-60558-166-8",
     pages = "1910--1915",
-    booktitle = "Proceedings of the 2009 ACM symposium on Applied Computing",
+    booktitle = "Proceedings of the 2009 ACM Symposium on Applied Computing",
     publisher = "Association for Computing Machinery",
     note = "null ; Conference date: 09-03-2009 Through 12-03-2009",
 }
@@ -44,3 +44,11 @@ @online{pypi
   year={2021},
   publisher={Python Software Foundation}
 }
+@techreport{pep301,
+  author  = {Richard Jones},
+  title   = {Package Index and Metadata for Distutils},
+  year    = {2002},
+  type    = {PEP},
+  number  = {301},
+  url     = {https://www.python.org/dev/peps/pep-0301/},
+}
diff --git a/doc/JOSS/paper.md b/doc/JOSS/paper.md
@@ -26,37 +26,34 @@ bibliography: paper.bib
 
 # Summary
 
-Dice Notation is a system for describing how to roll collections of dice. It is often used to assist understanding of rules of games - particularly tabletop roleplaying games (TTRPGs). Existing research software in this space has been primarily designed for other researchers and statisticians despite the fact that a large population of those actually playing these games are young [@DNDDemographics2019] or not involved in statistical research.
+Dice Notation is a system for describing how to roll collections of dice. It is often used to assist in understanding the rules of games - particularly tabletop roleplaying games (TTRPGs). Existing research software in this space has been primarily designed for other researchers and statisticians despite the fact that a large population of those actually playing these games are young [@DNDDemographics2019] or not involved in statistical research.
 
-`GNOLL` is an open-source library for parsing commonly used dice notations - for use in gaming system research and/or software development. `GNOLL` is performant, supports most popular and obscure notations, has permissive licensing and is integratable into many other systems due to it being written in C. At present, the repository has working examples of integration into 13 different programming languages such as Go, Java, Julia, Python, Perl and R.
+`GNOLL` is an open-source library for parsing commonly used dice notations in gaming system research and/or software development. `GNOLL` is performant, supports most popular and obscure notations, has permissive licensing, and is integratable into many other systems due to it being written in C. At present, the repository has working examples of integration into 13 different programming languages, such as Go, Java, Julia, Python, Perl and R.
 
 # Statement of Need
-Whilst there are several dice rolling utilities on the market for research/commercial use there is no current solution which:
+While there are several dice-rolling utilities on the market for research/commercial use, there is no current solution that:
 
 - is open source / permissively licensed.
 - can be easily integrated into other software despite language differences.
-- provides reference for other implementations.
+- provides a reference for other implementations.
 - supports such a diverse set of dice notation.
 
 While some solutions may offer one or two of these points, GNOLL addresses all of them.
 
-Without a larger project for reference/integration, many software developers have created their own dice notation parsers (for a simple subset is not too difficult to develop). These are usually sufficient for their immediate needs, but often create discrepencies in notation standards and do little to change this path for future developers.
+Without a more extensive project for reference/integration, many software developers have created their own dice notation parsers (because a parser for a simple subset is not too difficult to develop). These are usually sufficient for their immediate needs but often create discrepancies in notation standards and do little to change this path for future developers.
 
 # Related Reading
 
-There are not many publications that specifically discuss dice notation. The most prominent papers are named `ROLL`[@ROLL] and `TROLL` [@TROLL]. To distinguish this research and still pay homage to the original work, GNOLL is a recursive acronym expanded from "GNOLL's Not *OLL". The reason for its distinction is that `GNOLL`'s notation is focused on real-world gaming usage of dice notation, whereas `ROLL` and `TROLL` are notations targetted at statistics research.
+Few publications specifically discuss dice notation. The most prominent papers are named `ROLL` [@ROLL] and `TROLL` [@TROLL]. GNOLL is a recursive acronym expanded from "GNOLL's Not *OLL" to distinguish this research and still pay homage to the original work. The reason for its distinction is that `GNOLL`'s notation is focused on real-world gaming usage of dice notation, whereas `ROLL` and `TROLL` are notations targeted at statistics research.
 
 # Example Notation
 
-There are too many different operations and combinations of dice notation to fit into the space constraints of this paper, but are discussed at length in the project's [documentation](https://ianhunter.ie/GNOLL/), including rationale for each of the notation choices. A sample of the base dice notation has been described below.
-
+There are too many different operations and combinations of dice notation to describe within the space constraints of this paper but they are discussed at length in the project's [documentation](https://ianhunter.ie/GNOLL/), including the rationale for each of the notation choices. We describe a sample of the base dice notation below.
 
 The most basic dice roll in dice notation can be expressed as $$ x\textbf{d}y,\ where\ x,y\ \in{} \mathbb{Z}^{+}. $$ `x` dice are rolled with values from 1 to `y`. Where `x` is not specified, it is assumed that its value is 1. the exclusion of `y` produces an error (It is ambiguous to have a dice with no sides).
 
 # Performance
-`GNOLL` performs well against other dice rolling libraries available online both in terms of performance and functional coverage. In the Figures section below we show some simple benchmarking results against the `TROLL` system and a C++ parser and also test `GNOLL`'s Python interface against popular python packages and find that `GNOLL` is generally more performant. 
-
-# Citations
+`GNOLL` performs well against other dice-rolling libraries available online both in terms of performance and functional coverage. In the Figures section below, we show some simple benchmarking results against the `TROLL` system and a C++ parser and also test `GNOLL`'s Python interface against popular Python packages, and find that `GNOLL` is generally more performant. 
 
 # Figures
 ## Figure 1 - GNOLL Performance (C)
@@ -67,9 +64,9 @@ Comparison of `GNOLL`'s performance against other C/C++/SmallTalk dice notation
 
 ## Figure 2 - GNOLL Performance (Python)
 
-Comparison of `GNOLL`'s performance against other Python dice notation parsers. (Chosen from popular dice rollers on PyPi[@pypi] - ["Dice"](https://pypi.org/project/dice/), ["RPG Dice"](https://pypi.org/project/rpg-dice/), ["Python Dice"](https://pypi.org/project/python-dice/), ["d20"](https://pypi.org/project/d20/)). Unplotted points either were non-functional or exceeded a set timeout.
+Comparison of `GNOLL`'s performance against other Python dice notation parsers. (Chosen from popular dice rollers on PyPi [@pep301] - ["Dice"](https://pypi.org/project/dice/), ["RPG Dice"](https://pypi.org/project/rpg-dice/), ["Python Dice"](https://pypi.org/project/python-dice/), ["d20"](https://pypi.org/project/d20/)). Unplotted points either were non-functional or exceeded a set timeout.
 
-![A graph showing GNOLL's performance (via Python binding) on different sizes of dice rolls. It slightly underperforms for small sizes, but is faster than other python libraries for large sizes.](py.PNG)
+![A graph showing GNOLL's performance (via Python binding) on different sizes of dice rolls. It slightly underperforms for small sizes, but is faster than other Python libraries for large sizes.](py.PNG)
 
 # Acknowledgments
 Thanks to my dog for the desk-side companionship and the demand for healthy stick-fetching breaks.