Update docs with recent Joss feedback (#429)

* Update installation.md Signed-off-by: Ian Hunter <[email protected]> * Update README.md Signed-off-by: Ian Hunter <[email protected]> * Update __init__.py Signed-off-by: Ian Hunter <[email protected]> * Delete parser.py Signed-off-by: Ian Hunter <[email protected]> * Update util.py Signed-off-by: Ian Hunter <[email protected]> * Format code with black, gofmt, yapf, autopep8, isort and gofumpt * Update test_package.py Signed-off-by: Ian Hunter <[email protected]> * Update histogram.py Signed-off-by: Ian Hunter <[email protected]> * Format code with black, gofmt, yapf, autopep8, isort and gofumpt * Update benchmark_cmd.py Signed-off-by: Ian Hunter <[email protected]> * Format code with black, gofmt, yapf, autopep8, isort and gofumpt * Update benchmark_gnoll_versions.py Signed-off-by: Ian Hunter <[email protected]> * Format code with black, gofmt, yapf, autopep8, isort and gofumpt * Update benchmark_python.py Signed-off-by: Ian Hunter <[email protected]> * Format code with black, gofmt, yapf, autopep8, isort and gofumpt * Update yatzy.py Signed-off-by: Ian Hunter <[email protected]> * Format code with black, gofmt, yapf, autopep8, isort and gofumpt * Update critical_highlights.py Signed-off-by: Ian Hunter <[email protected]> * Format code with black, gofmt, yapf, autopep8, isort and gofumpt * Update FAQ.md Signed-off-by: Ian Hunter <[email protected]> * Update installation.md Signed-off-by: Ian Hunter <[email protected]> * Update dice.yacc Signed-off-by: Ian Hunter <[email protected]> * Update test_core.yml Signed-off-by: Ian Hunter <[email protected]> * Update dice.yacc Signed-off-by: Ian Hunter <[email protected]> * --version and --help available anywhere Signed-off-by: Ian Hunter <[email protected]> * Update installation.md Signed-off-by: Ian Hunter <[email protected]> * Update installation.md Signed-off-by: Ian Hunter <[email protected]> * Update installation.md Signed-off-by: Ian Hunter <[email protected]> * Update installation.md Signed-off-by: Ian Hunter <[email protected]> * Update installation.md Signed-off-by: Ian Hunter <[email protected]> * Update target.mk Signed-off-by: Ian Hunter <[email protected]> * Update dice.yacc Signed-off-by: Ian Hunter <[email protected]> * Update FAQ.md Signed-off-by: Ian Hunter <[email protected]> * Update setup.cfg Signed-off-by: Ian Hunter <[email protected]> * Update README.md Signed-off-by: Ian Hunter <[email protected]> * Update test_packages.yml Signed-off-by: Ian Hunter <[email protected]> * Update target.mk Signed-off-by: Ian Hunter <[email protected]> Signed-off-by: Ian Hunter <[email protected]> Co-authored-by: deepsource-autofix[bot] <62050782+deepsource-autofix[bot]@users.noreply.github.com>
ianfhunter · Dec 29, 2022 · 872f309 · 872f309
1 parent 7e15cdd
commit 872f309
Show file tree

Hide file tree

Showing 19 changed files with 408 additions and 222 deletions.
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_packages.yml b/.github/workflows/test_packages.yml
@@ -21,7 +21,7 @@ jobs:
       run: |
         python3 -m pip install gnoll
         # --index-url https://test.pypi.org/simple/
-        python3 -c "from gnoll.parser import roll; roll('d34')"
+        python3 -c "from gnoll import roll; roll('d34')"
 
   pypi_windows:
     name: "PyPi: Windows"
@@ -44,7 +44,7 @@ jobs:
       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 -c "from gnoll import roll; roll('d34')"
 
   pypi_mac:
     name: "PyPi: MacOS"
@@ -57,4 +57,4 @@ jobs:
         run: |
           python3 -m pip install gnoll
           # --index-url https://test.pypi.org/simple/
-          python3 -c "from gnoll.parser import roll; roll('d34')"
+          python3 -c "from gnoll import roll; roll('d34')"
diff --git a/README.md b/README.md
@@ -77,9 +77,10 @@ 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))
 ```
 
 ### 🛠️ Installing From Source

diff --git a/doc/gh-pages/developers/FAQ.md b/doc/gh-pages/developers/FAQ.md
@@ -22,16 +22,32 @@ GNOLL does not support tracking the state of internal counters between execution
 {: .question }
 > GNOLL uses a slightly different syntax than what I would like
 
-While we have put a lot of thought into GNOLL's choices of characters, You may change which characters are used for operations in the 'dice.lex' file.
+While we have put a lot of thought into GNOLL's choices of characters, You may change which characters are used for operations in the [dice.lex](https://github.com/ianfhunter/GNOLL/blob/main/src/grammar/dice.lex) file.
+
+For example, to allow using the full word 'reroll' instead of the shorthand 'r' you would make this change:
+```lex
+// old
+[r] {
+    return(REROLL);
+}
+// new
+[r|reroll] {
+    return(REROLL);
+}
+```
+Note you will need to manage conflicts in grammar yourself. (e.g. if you wanted to use the 'x' symbol for multiplication, you would need to also find a new symbol for the `REPEAT` token.
+For more complicated statements you will need to become familiar with [Regular Expressions](https://en.m.wikipedia.org/wiki/Regular_expression)
+
 
 {: .question }
 > GNOLL produces an overall result, but I need to know what each dice value was!
 
 This is possible! Just enable introspection or "dice breakdown" and you'll get the individual results as well as the final ones.
+This can be enabled either via a command line switch (where available) or as a parameter to the [main GNOLL roll function](https://www.ianhunter.ie/GNOLL/developers/installation.html).
 
 {: .question }
 > I wish to cite GNOLL. What is the most appropriate item to use?
 
 Please cite one of our publications.
-- [GNOLL: Efficient Multi-Lingual Software for Real-World Dice Notation and Extensions](https://joss.theoj.org/papers/c704c5148e622d32403948320c5e96a1)
-- [Application of the Central Limit Theorem to dice notation parsing](https://beta.briefideas.org/ideas/fc25de499b44d47685188df4d09e144f)
+- [GNOLL: Efficient Multi-Lingual Software for Real-World Dice Notation and Extensions (Not yet Published)](https://joss.theoj.org/papers/c704c5148e622d32403948320c5e96a1)
+- [Application of the Central Limit Theorem to dice notation parsing (Not yet Published)](https://beta.briefideas.org/ideas/fc25de499b44d47685188df4d09e144f)
diff --git a/doc/gh-pages/developers/installation.md b/doc/gh-pages/developers/installation.md
@@ -6,7 +6,48 @@ nav_order: 0
 ---
 
 # Setup
-## OS Information
+
+## Rolling with GNOLL 
+### The core function
+
+Each language binding example below will call the `roll_full_options` function, though some older examples may call deprecated functions which call that function internally.
+If you are creating your own binding to GNOLL, use this function 
+
+```c
+int roll_full_options(
+    char* roll_request, 
+    char* log_file, 
+    int enable_verbosity, 
+    int enable_introspection,
+    int enable_mocking,
+    int enable_builtins,
+    int mocking_type,
+    int mocking_seed
+);
+```
+The first parameter is the dice notation to be understood and computed. The result of which will be written into a file in the location `log_file`.
+Then follows various optional values, which you should set to False (0) unless you wish to take advantage of the feature.
+
+- `verbosity` is mostly useful for debugging a dice notation statement or for information during development. It will cause the execution to be slightly slower and is not recommended for release environments.
+- `introspection` provides a per-dice breakdown of values rolled during the dice notation parsing. This is useful if you wish to display individual dice results and not just the final total. These values (if enabled) are added to the output file before the total.
+- `mocking` is a feature allowing developers to generate predictable dice rolls for reproducible tests. This should only ever be used in a testing scenario.
+- `builtins` are a collection of predefined [Macros](bad link) provided by GNOLL for ease of use. This comes with a performance trade-off of loading these macros prior to the given dice notation.
+
+`mocking_type` is [an enum defining the behaviour of the Mocking logic](https://github.com/ianfhunter/GNOLL/blob/22b2f9248417cb756818cb5850dc20c4f77fde0e/src/grammar/util/mocking.h#L6). The `mocking_seed` provides the initial value to this logic, whether it be a random seed or an initialization of a predictably modified variable.
+
+The return value of this function is one of the defined GNOLL [error codes](developers/errors.html).
+
+### The output file
+
+The output of GNOLL is a file which can be injected by a subsequent program, wether that be within the language binding itself to bind to more suitable structures or direct usage in downstream applications.
+It is recommended that developers using GNOLL delete output files after they no longer need them 
+
+The file consists of two parts:
+
+- Dice introspection results (if enabled). The value for different dice are separated by commas and grouped by newlines (e.g. 3d6+2d6 would have 3 comma-seperated value on the first line, 2 comma-seperated value on the second line, followed by the final result)
+- The final result of the dice notation, where discrete results are separated by a semicolon (e.g. 5d6;d6)
+
+## OS Support 
 
 | OS | Version | Tested (From Source) | Tested (PyPi) |
 | -- | ------- | -------------------- | ------------- |
@@ -15,88 +56,175 @@ nav_order: 0
 | Windows | Win11 | No | No |
 | MacOS | 12 | Yes | Yes |
 
-## Common Pre-requisites
+## Common System Pre-requisites
 ```bash
 sudo apt-get install bison flex make python3-pip -y
 ```
 
+## Commandline Installation 
+
+GNOLL can be installed into your user path for convenience. 
+This will allow parsing of dice notation from the command line.
+
+```bash
+make install
+dice "1d20"
+```
+
+**Note:** Some command line syntax may conflict with tokens used in Dice Notation (e.g. >). Please escape or quote your notation to avoid this issue.
+
 ## Language Bindings 
 
-We have tested several language bindings to GNOLL. 
-The intention is not to be exhaustively compatible with every version, but a useful reference to help you set up GNOLL for your own software.
+We have tested binding GNOLL for use in several programming languages.
+
+The following documentation intention is not to be exhaustively compatible with every revision of a programming language (as that is a large overhead to maintain), but to be used as a helpful reference for setting up GNOLL for your own software.
 
 ### C
-This is the default build target.
-Tested with GCC and Clang Compilers and is C99 compliant.
+C is the default build target and what GNOLL is written in.
 
-```bash
-make all
-./build/dice "1d20
-```
+Tested with GCC and Clang Compilers and C99 compliant.
 
-Or, more conveniently;
+- Your application's build scripts should be modified to link against the shared object created with `make all` and to include the path to the folder containing `shared_header.h`
+- In your C code, include the "shared_header.h" file and the `roll_full_options` function will be available to use as described above.
 
+To make the example C application:
 ```bash
-make install
-dice "1d20"
+make all
+./build/dice "1d20"
+> Result: 14;
 ```
 
+The sourcecode for the C application is in the [grammar folder under src](https://github.com/ianfhunter/GNOLL/tree/main/src/grammar). It contains the core GNOLL logic as well as the application logic.
+
 ### C++
-Tested with Clang Compiler, Ubuntu 22.04
+Tested with Clang Compiler, Ubuntu 22.04.
 
+- Your application's build scripts should be modified to link against the shared object created with `make all` and to include the path to the folder containing `shared_header.h`
+- In your C++ code, include the "shared_header.h" file and the `roll_full_options` function will be available to use as described above.
+
+[An example application](https://github.com/ianfhunter/GNOLL/tree/main/src/C%2B%2B) is available (hardcoded to roll a d20):
 ```bash
 make cpp
+...
+> 19 
 ```
 
 ### CSharp
 Tested with Mono Compiler, Ubuntu 22.04
+
+The [C# example](https://github.com/ianfhunter/GNOLL/tree/main/src/CSharp) expects that the shared object libdice.so is generated under `build/`.
+The `build/` directory may need to be added to the environment variable `LD_LIBRARY_PATH`.
+
+The library is imported and the `char *`s of the C function are managed to consume C# Strings ([via marshalling Unmanaged LPStrs](https://github.com/ianfhunter/GNOLL/blob/22b2f9248417cb756818cb5850dc20c4f77fde0e/src/CSharp/main.cs#L7))
+
+The example application creates a RollWithGNOLL function which handles all the file parsing. The application calls this function with a hardcoded '1d20'.
+
 ```bash
 make cs
+...
+> 4
+```
+
+Function example:
+```cs
+RollWithGNOLL("1d20")
+...
+5
 ```
 
 ### Go
 Tested with Golang 1.18, Ubuntu 22.04
+
+The Go setup is very similar to the C# example, in that we must ensure the build directory has the libdice.so file and that the build directory is in `LD_LIBRARY_PATH`.
+Apart from this, the steps to execute your go application (e.g. `go build` and `go run`) should remain unchanged.
+The application is hardcoded to parse a d20 roll.
 ```bash
 make go
+...
+> 17
 ```
 
+The code itself creates "CStrings" which the developer must be careful to free after use. 
+
 ### Haskell
 Tested with ghc 9.4.3, cabal 3.0.0.0-3build1.1, Ubuntu 22.04
+
+In [this example](https://github.com/ianfhunter/GNOLL/tree/main/src/haskell), libdice.so is installed to /usr/lib/ and the cabal build configuration points to it's location via the 'extra-libraries' field.
+In the main application, GNOLL is imported via the Foreign Function Interface (`foreign import`). You must use the CStrings structures rather than native haskell strings.
+
 ```
 make haskell
+cabal run src [dice roll e.g. d20]
 ```
 
 ### Python
 Available from [PyPi](https://pypi.org/project/gnoll/)
 Tested with Python3.10, Ubuntu 22.04
+
+Install via Pip:
 ```bash
 pip install gnoll
 ```
+Then you can import the `roll` function and the custom Exceptions `GNOLLExceptions` which the function can raise.
+```python
+from gnoll import roll
+roll("2d100")
+> (0, [[108]] ,None)
+```
+The roll function takes the form:
+```python
+def roll(s,
+         verbose=False,
+         mock=None,
+         mock_const=3,
+         breakdown=False,
+         builtins=False):
+```
+Where `s` is the string containing the dice notation and the other optional fields correspond with the optional features as mentioned above.
+File management is handled internally and is hidden from the caller.
+
+Exceptions are all of the Exception type `GNOLLException` and follow the [list of errors](developers/errors.html)
+
 If you are running from sourcecode:
 ```bash
 make python
 ```
+will build the application to expose the same interface.
 
 ### Perl
 Tested on Perl 5.30, Ubuntu 20.04
+
+The [Perl example](https://github.com/ianfhunter/GNOLL/tree/main/src/perl) uses the SWIG framework to create its bindings.
+The Perl libraries must be linked at build time ($PERL_VERSION can be set to configure this (default: 5.30)).
+GNOLL's notation parsing is then exposed via a `gnoll::roll_and_write` function (a wrapper around roll_full_options which has all options set to False).
+
 ```bash
 make perl
+...
+> 20
 ```
-To make for another version, $PERL_VERSION must be set (default: 5.30)
+
 
 ### Java
 Tested with openjdk-8, Ubuntu 22.04
+
+Java, like Perl, must have GNOLL compiled with its language headers.
+
+This can be done with the make command:
 ```bash
 make java
 ```
 
+Afterwards, GNOLL'S functionality is available via a `DiceNotationParser.roll` function which takes a dice notation string and a filename and performs as usual.
+
 ### Julia
 Tested on Ubuntu 20.04, Julia 1.4.1
 
-Available from [JuliaHub](https://juliahub.com/ui/Packages/GnollDiceNotation/WetJc/)
+Whether installing from [JuliaHub](https://juliahub.com/ui/Packages/GnollDiceNotation/WetJc/) or from source with 
 ```
 make julia
 ```
+The function `GnollDiceNotation.roll` is available to use, which simply takes in a dice notation string.
 
 ### JavaScript Setup
 
@@ -119,20 +247,50 @@ make javascript
 node a.out.js
 ```
 
+As the c code is being compiled to JavaScript, it operates in the same way
+
 ### PHP
 Tested on PHP 8.1.13, Ubuntu 22.04
+
+As long as the shared object is in LD_LIBRARY_PATH, you can use the functions from c with PHP's cdef
+```
+FFI::cdef(
+    "int roll_and_write(char * roll, char *fn );",
+    "libdice.so"
+);
+```
+
+The [PHP Example] (https://github.com/ianfhunter/GNOLL/blob/main/src/PHP/index.php) parses a hardcoded 3d6 roll.
 ```bash
 make php
 ```
 
 ### R
 Tested on R 4.2.2, Ubuntu 22.04
+
+
+#### Setup 
+Generate the shared object file that R can consume.
 ```bash
 make r
 ```
 
+Inside `main.r` we show an example of GNOLL usage.
+
+- Load in the shared object
+- Delete the temporary file that contains GNOLL output
+- Call GNOLL
+- Parse result
+
+#### Notes
+This example uses the .C function which is usually not recommended. The recommended way to call C code in R is through the .Call() function. See [#368](https://github.com/ianfhunter/GNOLL/issues/368)
+
+
 ### Ruby
-Tetsed on Ruby 3.0, Ubuntu 22.04
+Tested on Ruby 3.0, Ubuntu 22.04
+
+Using Ruby's native FFI code, the [demo application](https://github.com/ianfhunter/GNOLL/blob/main/src/ruby/main.rb) creates a namespaces function for usage. `DiceNotation.roll([dice notation string])`
+
 ```bash
 make ruby
 ```

diff --git a/scripts/benchmark/benchmark_cmd.py b/scripts/benchmark/benchmark_cmd.py
@@ -7,9 +7,8 @@
 # ======= Benchmark Imports ==========
 
 SRC_DIR = os.path.abspath(
-    os.path.join(os.path.dirname(__file__), "../../src/python/code/gnoll/")
-)
-m = os.path.join(SRC_DIR, "parser.py")
+    os.path.join(os.path.dirname(__file__), "../../src/python/code/gnoll/"))
+m = os.path.join(SRC_DIR, "__init__.py")
 spec = iu.spec_from_file_location("dt", m)
 dt = iu.module_from_spec(spec)
 spec.loader.exec_module(dt)
@@ -22,7 +21,8 @@
 def troll_roll(_):
     # test.t is generated inside the benchmark core
     v = subprocess.run([troll_exec, "0", "test.t"],
-                       capture_output=True, check=True)
+                       capture_output=True,
+                       check=True)
     if v.returncode:
         raise ValueError