dicey 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b23d3fe347080f349190417819aba5f2778a6196569ab39e38d79049f7557f02
-  data.tar.gz: 5bd9295a6bb1a15fe33fe3b967fd1d2c0784a19e713977f57da7910589687ebe
+  metadata.gz: a269ac8baf4bf849781175b605d92c23ff95fae3e53baa540519ece9947cec0d
+  data.tar.gz: af8f74b92b35a2818d18dc91d9917d8af6e91e16f8674f02eebfb5e56b1759fd
 SHA512:
-  metadata.gz: 778d6f36d896b5db19411bedf0bf272082310eb2c9a1403b57962932979ec0da863b6d408c9245b49bbfb914c99cc2bfa9e8443e0a02d732d2723f93f8b1f6bb
-  data.tar.gz: 694960b274505249fc705e0a61bb1452b6efed062d8b183c154734a9677cc9c28309cf859917443fd997a60de70e00c7f45abc9f9e36e96007949c1bdbee7e0f
+  metadata.gz: 1b031d4ee67b9c3b1ebe0ba23ac2289f7d14536af4fda1b98b7f481fd9e027ef3b57d8911f7d3c78ca46da0554b63226312e7ae4fa136fc34431bf7f86b7f349
+  data.tar.gz: ac52115c59f846e4662ed055e871bf31f2e87b2080acb07042730698d5fa6d107daaf64792645752b47bced701ace913b58464a7a96e56dffe6d3aba3a0af2d8

data/README.md

@@ -14,15 +14,18 @@ In seriousness, this program is mainly useful for calculating total frequency (p
 
 ## Table of contents
 
-- [No installation](#no-installation)
+- [Online (no installation)](#online-no-installation)
+  - [Recommended](#recommended)
+  - [For those who want the full command line experience](#for-those-who-want-the-full-command-line-experience)
 - [Installation](#installation)
   - [Requirements](#requirements)
-- [Usage / CLI (command line interface)](#usage--cli-command-line-interface)
-  - [Example 1 — Basic distribution](#example-1--basic-distribution)
-  - [Example 2 — Complex distribution with different dice](#example-2--complex-distribution-with-different-dice)
-  - [Example 3 — Custom dice](#example-3--custom-dice)
-  - [Example 4 — Rolling even more custom dice](#example-4--rolling-even-more-custom-dice)
-- [Usage / API](#usage--api)
+- [Usage: CLI (command line)](#usage-cli-command-line)
+  - [Example 1: Basic distribution](#example-1-basic-distribution)
+  - [Example 2: Complex distribution with different dice](#example-2-complex-distribution-with-different-dice)
+  - [Example 3: Custom dice](#example-3-custom-dice)
+  - [Example 4: Rolling even more custom dice](#example-4-rolling-even-more-custom-dice)
+  - [All ways to define dice](#all-ways-to-define-dice)
+- [Usage: API](#usage-api)
   - [Dice](#dice)
   - [Rolling](#rolling)
   - [Calculators](#calculators)
@@ -31,13 +34,24 @@ In seriousness, this program is mainly useful for calculating total frequency (p
 - [Contributing](#contributing)
 - [License](#license)
 
-## No installation
+## Online (no installation)
 
-Thanks to the efforts of Ruby developers, you can try **Dicey** online!
-1. Head over to https://runruby.dev/gist/476679a55c24520782613d9ceb89d9a3
-2. Make sure that "*-main.rb*" is open
-3. Input arguments between "ARGUMENTS" lines, separated by spaces.
+### Recommended
+
+Use online version of **Dicey** on its own website: [dicey.bulancov.tech](https://dicey.bulancov.tech)!
+
+It does not provide quite all features, but it's easy to use and quick to get started.
+
+### For those who want the full command line experience
+
+Thanks to the efforts of Ruby developers, you can run full **Dicey** online!
+1. Head over to the prepared [RunRuby page](https://runruby.dev/gist/476679a55c24520782613d9ceb89d9a3).
+2. Make sure that "*-main.rb*" is open.
+3. Input arguments between "ARGUMENTS" lines, separated by spaces. Refer to [Usage / CLI](#usage--cli-command-line) section.
 4. Click "**Run code**" button below the editor.
+5. Results will be printed to the "Logs" tab.
+
+If familiar with Ruby, you can also use **RunRuby** to explore the API. Refer to [Usage / API](#usage--api) section for documentation.
 
 ## Installation
 
@@ -48,7 +62,7 @@ gem install dicey
 
 Or, if using Bundler, add it to your `Gemfile`:
 ```rb
-gem "dicey", "~> 0.13"
+gem "dicey", "~> 0.14"
 ```
 
 > [!TIP]
@@ -65,14 +79,14 @@ gem "dicey", "~> 0.13"
 
 Otherwise, there are no direct dependencies.
 
-## Usage / CLI (command line interface)
+## Usage: CLI (command line)
 
-Following examples assume that `dicey` (or `dicey-to-gnuplot`) is executable and is in `$PATH`. You can also run it with `ruby dicey` instead.
+Following examples assume that `dicey` (or `dicey-to-gnuplot`) is executable and is in `$PATH`.
 
 > [!NOTE]
 > 💡 Run `dicey --help` to get a list of all possible options.
 
-### Example 1 — Basic distribution
+### Example 1: Basic distribution
 
 Let's start with something simple. Imagine that your Bard character has Vicious Mockery cantrip with 2d4 damage, and you would like to know the distribution of possible damage rolls. Run **Dicey** with two 4s as arguments:
 ```sh
@@ -81,7 +95,7 @@ $ dicey 4 4
 
 It should output the following:
 ```sh
-# ⚃;⚃
+# D4+D4
 2 => 1
 3 => 2
 4 => 3
@@ -96,7 +110,7 @@ First line is a comment telling you that calculation ran for two D4s. Every line
 If probability is preferred, there is an option for that:
 ```sh
 $ dicey 4 4 --result probabilities # or -r p for short
-# ⚃;⚃
+# D4+D4
 2 => 0.0625
 3 => 0.125
 4 => 0.1875
@@ -108,13 +122,13 @@ $ dicey 4 4 --result probabilities # or -r p for short
 
 This shows that 5 will probably be rolled a quarter of the time.
 
-### Example 2 — Complex distribution with different dice
+### Example 2: Complex distribution with different dice
 
 During your quest to end all ends you find a cool Burning Sword which deals 1d8 slashing damage and 2d4 fire damage on attack. You run **Dicey** with these dice:
 ```sh
 # Note the shorthand notation for two dice!
 $ dicey 8 2d4
-# [8];⚃;⚃
+# D8+D4+D4
 3 => 1
 4 => 3
 5 => 6
@@ -133,30 +147,30 @@ $ dicey 8 2d4
 
 Results show that while the total range is 3–16, it is much more likely to roll numbers in the 6–13 range. That's pretty fire, huh?
 
-#### Example 2.1 — Graph
+#### Example 2.1: Graph
 
 If you downloaded `dicey-to-gnuplot` and have [gnuplot](http://gnuplot.info) installed, it is possible to turn these results into a graph with a somewhat clunky command:
 ```sh
-$ dicey 8 2d4 --format gnuplot | dicey-to-gnuplot
-# `--format gnuplot` can be abbreviated as `-f g`
+$ dicey 8 2d4 -f g | dicey-to-gnuplot
+# `--format gnuplot` is shortened to `-f g`
 ```
 
-This will create a PNG image named `[8];⚃;⚃.png`:
-![Graph of damage roll frequencies for Burning Sword]([8];⚃;⚃.png)
+This will create a PNG image named "*D8+D4+D4.png*":
+![Graph of damage roll frequencies for Burning Sword](D8+D4+D4.png)
 
-#### Example 2.2 — JSON and YAML
+#### Example 2.2: JSON and YAML
 
 If you find that you need to export results for further processing, it would be great if a common data interchange format was used. **Dicey** supports output as JSON and YAML with `--format json` (or `-f j`) and `--format yaml` (or `-f y`) respectively.
 
 JSON via `dicey 8 2d4 --format json`:
 ```json
-{"description":"[8];⚃;⚃","results":{"3":1,"4":3,"5":6,"6":10,"7":13,"8":15,"9":16,"10":16,"11":15,"12":13,"13":10,"14":6,"15":3,"16":1}}
+{"description":"D8+D4+D4","results":{"3":1,"4":3,"5":6,"6":10,"7":13,"8":15,"9":16,"10":16,"11":15,"12":13,"13":10,"14":6,"15":3,"16":1}}
 ```
 
 YAML via `dicey 8 2d4 --format yaml`:
 ```yaml
 ---
-description: "[8];⚃;⚃"
+description: D8+D4+D4
 results:
   3: 1
   4: 3
@@ -174,14 +188,14 @@ results:
   16: 1
 ```
 
-### Example 3 — Custom dice
+### Example 3: Custom dice
 
 While walking home from work you decide to take a shortcut through a dark alleyway. Suddenly, you notice a die lying on the ground. Looking closer, it turns out to be a D4, but its 3 side was erased from reality. You just have to learn what impact this has on a roll together with a normal D4. Thankfully, you know just the program for the job.
 
 Having ran to a computer as fast as you can, you sic **Dicey** on the problem:
 ```sh
 $ dicey 1,2,4 4
-# (1,2,4);⚃
+# (1,2,4)+D4
 2 => 1
 3 => 2
 4 => 2
@@ -193,13 +207,10 @@ $ dicey 1,2,4 4
 
 Hmm, this looks normal, doesn't it? But wait, why are there two 2s in a row? Turns out that not having one of the sides just causes the roll frequencies to slightly dip in the middle. Good to know.
 
-> [!TIP]
-> 💡 A single positive integer argument N practically is a shorthand for listing every side from 1 to N.
-
 But what if you had TWO weird D4s?
 ```sh
 $ dicey 2d1,2,4
-# (1,2,4);(1,2,4)
+# (1,2,4)+(1,2,4)
 2 => 1
 3 => 2
 4 => 1
@@ -210,45 +221,61 @@ $ dicey 2d1,2,4
 
 Hah, now this is a properly cursed distribution!
 
-### Example 4 — Rolling even more custom dice
+> [!TIP]
+> 💡 A single positive integer argument N practically is a shorthand for listing every side from 1 to N.
+
+### Example 4: Rolling even more custom dice
 
 You have a sudden urge to roll dice while only having boring integer dice at home. Where to find *the cool* dice though?
 
 Look no further than **roll** mode introduced in **Dicey** 0.12:
 ```sh
 $ dicey 0.5,1.5,2.5 4 --mode roll # As always, can be abbreviated to -m r
-# (0.5e0,0.15e1,0.25e1);⚃
+# (0.5e0,0.15e1,0.25e1)+D4
 roll => 0.35e1 # You probably will get a different value here.
 ```
 
 > [!NOTE]
-> 💡 Roll mode is compatible with `--format`, but not `--result`.
+> 💡 Roll mode is compatible with `--format` option.
+
+### All ways to define dice
 
-## Usage / API
+There are three *main* ways to define dice:
+- *"5", "25", or "525"*: a single positive integer makes a regular die (like a D20).
+- *"3-6", "-5..5", "(0-1)"*: a pair of integers with a separator, possibly in round brackets, makes a numeric die with integers in the range.
+  - Accepted separators: "-", "..", "...", "–" (en dash), "—" (em dash), "…" (ellipsis).
+- *"1,2,4", "(-1.5,0,1.5)", or "2,"*: a list of any numbers separated by commas, possibly in round brackets, makes an arbitrary numeric die.
+  - Lists can end in a comma, allowing single-number lists.
+
+*"D6", "d(-1,3)", or "d2..4"*: any definitions can be prefixed with "d" or "D". While this doesn't do anything on its own, it can be useful to not start a definition with "-".
+
+*"2D6", "5d-1,3", or "277D(2..4)"*: any definitions can be prefixed with "*N*d" or "*N*D", where *N* is a positive integer. This creates *N* copies of the die.
+
+## Usage: API
 
 > [!Note]
-> - Latest documentation from `main` branch is automatically deployed to [GitHub Pages](https://trinistr.github.io/dicey).
+> - Latest API documentation from `main` branch is automatically deployed to [GitHub Pages](https://trinistr.github.io/dicey).
 > - Documentation for published versions is available on [RubyDoc](https://rubydoc.info/gems/dicey).
 
 ### Dice
 
 There are 3 classes of dice currently:
 - `Dicey::AbstractDie` is the base class for other dice, but can be used on its own. It has no restrictions on values of sides. For now, it is *only* useful for rolling and can't be used for distribution calculations.
-- `Dicey::NumericDie` behaves much the same as `Dicey::AbstractDie`, except for checking that all values are instances of `Numeric`. It can be initialized with an Array or Range.
-- `Dicey::RegularDie` is a subclass of `Dicey::NumericDie`. It is defined by a single integer which is expanded to range (1..N).
+- `Dicey::NumericDie` behaves much the same as `Dicey::AbstractDie` (being its subclass), except for checking that all values are instances of `Numeric`. It can be initialized with an Array or Range.
+- `Dicey::RegularDie` is a specialized subclass of `Dicey::NumericDie`. It is defined by a single integer *N* which is expanded to a range (1..*N*).
 
 All dice classes have constructor methods aside from `.new`:
 - `.from_list` takes a list of definitions and calls `.new` with each one;
 - `.from_count` takes a count and a definition and calls `.new` with it specified number of times.
 
-See [Diving deeper](#diving-deeper) for more information.
+See [Diving deeper](#diving-deeper) for more theoretical information.
 
 > [!NOTE]
 > 💡 Using `Float` values is liable to cause precision issues. Due to in-built result verification, this **will** raise errors. Use `Rational` or `BigDecimal` instead. 
 
 #### DieFoundry
 
-`Dicey::DieFoundry#call` provides the string interface for creating dice as available in CLI:
+`Dicey::DieFoundry#call` provides the interface for creating dice from Strings as available in CLI:
 ```rb
 Dicey::DieFoundry.new.call("100")
   # same as Dicey::RegularDie.new(100)
@@ -262,7 +289,7 @@ It only takes a single argument and may return both an array of dice and a singl
 ```rb
 foundry = Dicey::DieFoundry.new
 %w[8 2d4].flat_map { foundry.call(_1) }
-  # same as [Dicey::RegularDie.new(8), Dicey::RegularDie.new(4), Dicey::RegularDie.new(4)]
+  # same as [Dicey::RegularDie.new(8), *Dicey::RegularDie.from_count(2, 4)]
 ```
 
 ### Rolling
@@ -303,17 +330,19 @@ die.roll
   # => 1
 ```
 
-Randomness source is *global*, shared between all dice and probably not thread-safe.
+> [!NOTE]
+> 💡 Randomness source is *global*, shared between all dice and probably not thread-safe.
 
 ### Calculators
 
-Frequency calculators live in `Dicey::SumFrequencyCalculators` module. There are three implemented calculators:
+Frequency calculators live in `Dicey::SumFrequencyCalculators` module. There are four calculators currently:
 - `Dicey::SumFrequencyCalculators::KroneckerSubstitution` is the recommended calculator, able to handle all `Dicey::RegularDie`. It is very fast, calculating distribution for *100d6* in about 0.1 seconds on my laptop.
 - `Dicey::SumFrequencyCalculators::MultinomialCoefficients` is specialized for repeated numeric dice, with performance only slightly worse. However, it is currently limited to dice with arithmetic sequences.
-- `Dicey::SumFrequencyCalculators::BruteForce` is the most generic and slowest one, but can handle any dice. Currently, it is also limited to `Dicey::NumericDie`, as it's unclear how to handle other values.
+- `Dicey::SumFrequencyCalculators::BruteForce` is the most generic and slowest one, but can in principle work with any dice. Currently, it is also limited to `Dicey::NumericDie`, as it's unclear how to handle other values.
+- `Dicey::SumFrequencyCalculators::Empirical`. This is more of a tool than a calculator. It can be interesting to play around with and see how practical results compare to theoretical ones.
 
 Calculators inherit from `Dicey::SumFrequencyCalculators::BaseCalculator` and provide the following public interface:
-- `#call(dice, result_type: {:frequencies | :probabilities}) : Hash`
+- `#call(dice, result_type: {:frequencies | :probabilities}, **options) : Hash`
 - `#valid_for?(dice) : Boolean`
 
 See [next section](#diving-deeper) for more details on limitations and complexity considerations.
@@ -321,10 +350,7 @@ See [next section](#diving-deeper) for more details on limitations and complexit
 ## Diving deeper
 
 For a further discussion of calculations, it is important to understand which classes of dice exist.
-- **Regular** die — a die with N sides with sequential integers from 1 to N,
-  like a classic cubic D6, D20, or even a coin if you assume that it rolls 1 and 2.
-  These are dice used for many tabletop games, including role-playing games.
-  Most probably, you will only ever need these and not anything beyond.
+- **Regular** die — a die with N sides with sequential integers from 1 to N, like a classic cubic D6, D20, or even a coin if you assume that it rolls 1 and 2. These are dice used for many tabletop games, including role-playing games. Most probably, you will only ever need these and not anything beyond.
 
 > [!TIP]
 > 💡 If you only need to roll **regular** dice, this section will not contain anything important.
@@ -335,11 +361,11 @@ For a further discussion of calculations, it is important to understand which cl
 - **Abstract** die is not limited by anything other than not having partial sides (and how would that work anyway?).
 
 > [!NOTE]
-> 💡 If your die starts with a negative number or only has a single natural side, brackets can be employed to force treating it as a sides list, e.g. `dicey '(-1)'` (quotation is required due to shell processing).
+> 💡 If your die definition starts with a negative number, it can be bracketed, prefixed with "d", or put after "--" pseudo-argument to avoid processing as an option.
 
-Dicey is in principle able to handle any numeric dice and some abstract dice with well-defined summation (tested on complex numbers), though not every possibility is exposed through command-line interface: that is limited to floating-point values.
+Dicey is in principle able to handle any real numeric dice and some abstract dice with well-defined summation (tested on complex numbers), though not every possibility is exposed through command-line interface: that is limited to floating-point values.
 
-Currently, three algorithms are implemented, with different possibilities and trade-offs.
+Currently, three algorithms for calculating frequencies are implemented, with different possibilities and trade-offs.
 
 > [!NOTE]
 > 💡 Complexity is listed for `n` dice with at most `m` sides and has not been rigorously proven.
@@ -349,7 +375,7 @@ Currently, three algorithms are implemented, with different possibilities and tr
 An algorithm based on fast polynomial multiplication. This is the default algorithm, used for most reasonable dice.
 
 - Limitations: only **natural** dice are allowed, including **regular** dice.
-- Example: `dicey 5 3,4,1 '(0)'`
+- Example: `dicey 5 3,4,1 0,`
 - Complexity: `O(m⋅n)` where `m` is the highest value
 
 ### Multinomial coefficients

data/lib/dicey/abstract_die.rb

@@ -21,6 +21,8 @@ module Dicey
 
     # Yes, class variable is actually useful here.
     # TODO: Allow supplying a custom Random.
+
+    # Shared randomness source, accessed through {.rand} and {.srand}.
     @@random = Random.new
 
     # rubocop:enable Style/ClassVars
@@ -31,9 +33,8 @@ module Dicey
     # @return [String]
     def self.describe(dice)
       return dice.to_s if AbstractDie === dice
-      return dice.join(";") if Array === dice
 
-      dice.to_a.join(";")
+      dice.to_a.join("+")
     end
 
     # Create a bunch of different dice at once.
@@ -55,7 +56,15 @@ module Dicey
       Array.new(count) { new(definition) }
     end
 
-    attr_reader :sides_list, :sides_num
+    # Die's list of sides.
+    #
+    # @return [Array<Any>]
+    attr_reader :sides_list
+
+    # Number of sides of the die.
+    #
+    # @return [Integer]
+    attr_reader :sides_num
 
     # @param sides_list [Enumerable<Any>]
     # @raise [DiceyError] if +sides_list+ is empty
@@ -92,9 +101,13 @@ module Dicey
       current
     end
 
+    # Return a string representing the die.
+    #
+    # Default representation is a list of sides in round brackets.
+    #
     # @return [String]
     def to_s
-      "(#{@sides_list.join(",")})"
+      (@sides_list.size > 1) ? "(#{@sides_list.join(",")})" : "(#{@sides_list.first},)"
     end
 
     # Determine if this die and the other one have the same list of sides.

data/lib/dicey/cli/options.rb

@@ -54,8 +54,10 @@ module Dicey
       def add_banner_and_version
         @parser.banner = <<~TEXT
           Usage: #{@parser.program_name} [options] <die> [<die> ...]
+                 #{@parser.program_name} [options] -- <die> [<die> ...]
                  #{@parser.program_name} --test [full|quiet]
           All option names and arguments can be abbreviated if abbreviation is unambiguous.
+          A lone "--" separates options and die definitions, allowing definitions to start with "-".
         TEXT
       end
 

data/lib/dicey/die_foundry.rb

@@ -6,18 +6,20 @@ require_relative "regular_die"
 module Dicey
   # Helper class to define die definitions and automatically select the best one.
   class DieFoundry
-    # Regexp for matching a count.
-    COUNT = /(?:(?<count>[1-9]\d*+)?d)?+/i
+    # Regexp for matching a possible count.
+    PREFIX = /(?>(?<count>[1-9]\d*+)?d)?+/i
 
     # Possible molds for the dice. They are matched in the order as written.
     MOLDS = [
       # Positive integer goes into the RegularDie mold.
-      [/\A#{COUNT}(?<sides>[1-9]\d*+)\z/, :regular_mold],
+      [/\A#{PREFIX}(?<sides>[1-9]\d*+)\z/, :regular_mold].freeze,
+      # Integer range goes into the NumericDie mold.
+      [/\A#{PREFIX}\(?(?<begin>-?\d++)(?>[-–—…]|\.{2,3})(?<end>-?\d++)\)?\z/, :range_mold].freeze,
       # List of numbers goes into the NumericDie mold.
-      [/\A#{COUNT}\(?(?<sides>-?\d++(?>,(?>-?\d++)?)*)\)?\z/, :weirdly_shaped_mold],
+      [/\A#{PREFIX}\(?(?<sides>-?\d++(?>,(?>-?\d++)?)+|,)\)?\z/, :weirdly_shaped_mold].freeze,
       # Non-integers require arbitrary precision arithmetic, which is not enabled by default.
-      [/\A#{COUNT}\(?(?<sides>-?\d++(?>\.\d++)?(?>,(?>-?\d++(?>\.\d++)?)?)*)\)?\z/,
-       :weirdly_precise_mold],
+      [/\A#{PREFIX}\(?(?<sides>-?\d++(?>\.\d++)?(?>,(?>-?\d++(?>\.\d++)?)?)+|,)\)?\z/,
+       :weirdly_precise_mold].freeze,
       # Anything else is spilled on the floor.
     ].freeze
 
@@ -25,15 +27,16 @@ module Dicey
     #
     # Following definitions are recognized:
     # - positive integer (like "6" or "20"), which produces a {RegularDie};
+    # - integer range (like "3-6" or "(-5..5)"), which produces a {NumericDie};
     # - list of integers (like "3,4,5", "(-1,0,1)", or "2,"), which produces a {NumericDie};
-    # - list of decimal numbers (like "0.5,0.2,0.8" or "2.0"), which produces a {NumericDie},
+    # - list of decimal numbers (like "0.5,0.2,0.8" or "(2.0,)"), which produces a {NumericDie},
     #   but uses +BigDecimal+ for values to maintain precise results.
     #
     # Any die definition can be prefixed with a count, like "2D6" or "1d1,3,5" to create an array.
     # A plain "d" without an explicit count is ignored instead, creating a single die.
     #
     # @param definition [String] die shape
-    # @return [NumericDie, RegularDie, Array<NumericDie, RegularDie>]
+    # @return [NumericDie, RegularDie, Array<NumericDie>, Array<RegularDie>]
     # @raise [DiceyError] if no mold fits the definition
     def call(definition)
       matched, name =
@@ -54,6 +57,13 @@ module Dicey
       build_dice(RegularDie, definition[:count], definition[:sides].to_i)
     end
 
+    def range_mold(definition)
+      first = definition[:begin].to_i
+      last = definition[:end].to_i
+      first, last = last, first if first > last
+      build_dice(NumericDie, definition[:count], first..last)
+    end
+
     def weirdly_shaped_mold(definition)
       build_dice(NumericDie, definition[:count], definition[:sides].split(",").map(&:to_i))
     end

data/lib/dicey/output_formatters/hash_formatter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dicey
+  # Processors which turn data to text.
   module OutputFormatters
     # Base formatter for outputting in formats which can be converted from a Hash directly.
     # Can add an optional description into the result.

data/lib/dicey/regular_die.rb

@@ -5,9 +5,6 @@ require_relative "numeric_die"
 module Dicey
   # Regular die, which has N sides with numbers from 1 to N.
   class RegularDie < NumericDie
-    # Characters to use for small dice.
-    D6 = "⚀⚁⚂⚃⚄⚅"
-
     # @param max [Integer] maximum side / number of sides
     def initialize(max)
       unless Integer === max && max.positive?
@@ -17,12 +14,13 @@ module Dicey
       super((1..max))
     end
 
-    # Dice with 1–6 sides are displayed with a single character from {D6}.
-    # More than that, and we get into the square bracket territory.
+    # Return a string representing the die.
+    #
+    # Regular dice are represented with a "D" followed by the number of sides.
     #
     # @return [String]
     def to_s
-      (sides_num <= D6.size) ? D6[sides_num - 1] : "[#{sides_num}]"
+      "D#{sides_num}"
     end
   end
 end

data/lib/dicey/sum_frequency_calculators/base_calculator.rb

@@ -1,8 +1,17 @@
 # frozen_string_literal: true
 
 module Dicey
+  # Calculators for probability distributions of dice.
   module SumFrequencyCalculators
     # Base frequencies calculator.
+    #
+    # *Options:*
+    #
+    # Calculators may have calculator-specific options,
+    # passed as extra keyword arguments to {#call}.
+    # If present, they will be documented under *Options* heading
+    # on the class itself.
+    #
     # @abstract
     class BaseCalculator
       # Possible values for +result_type+ argument in {#call}.
@@ -10,11 +19,12 @@ module Dicey
 
       # @param dice [Enumerable<AbstractDie>]
       # @param result_type [Symbol] one of {RESULT_TYPES}
+      # @param options [Hash{Symbol => Any}] calculator-specific options
       # @return [Hash{Numeric => Numeric}] frequencies of each sum
       # @raise [DiceyError] if +result_type+ is invalid
       # @raise [DiceyError] if dice list is invalid for the calculator
       # @raise [DiceyError] if calculator returned obviously wrong results
-      def call(dice, result_type: :frequencies)
+      def call(dice, result_type: :frequencies, **options)
         unless RESULT_TYPES.include?(result_type)
           raise DiceyError, "#{result_type} is not a valid result type!"
         end
@@ -22,7 +32,7 @@ module Dicey
         return {} if dice.empty?
         raise DiceyError, "#{self.class} can not handle these dice!" unless valid_for?(dice)
 
-        frequencies = calculate(dice)
+        frequencies = calculate(dice, **options)
         verify_result(frequencies, dice)
         frequencies = sort_result(frequencies)
         transform_result(frequencies, result_type)
@@ -46,7 +56,7 @@ module Dicey
 
       # Peform frequencies calculation.
       # (see #call)
-      def calculate(dice)
+      def calculate(dice, **nil)
         # :nocov:
         raise NotImplementedError
         # :nocov:

data/lib/dicey/sum_frequency_calculators/brute_force.rb

@@ -12,7 +12,7 @@ module Dicey
         dice.all?(NumericDie)
       end
 
-      def calculate(dice)
+      def calculate(dice, **nil)
         combine_dice_enumerators(dice).map(&:sum).tally
       end
 

data/lib/dicey/sum_frequency_calculators/empirical.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "base_calculator"
+
+module Dicey
+  module SumFrequencyCalculators
+    # "Calculator" for a collection of {NumericDie} using empirically-obtained statistics.
+    #
+    # @note This calculator is mostly a joke. It can be useful for educational purposes,
+    #   or to verify results of {BruteForce} when in doubt. It is not used by default.
+    #
+    # Does a number of rolls and calculates approximate probabilities from that.
+    # Even if frequencies are requested, results are non-integer.
+    #
+    # *Options:*
+    # - *rolls* (Integer) (_defaults_ _to:_ _N_) — number of rolls to perform
+    class Empirical < BaseCalculator
+      # Default number of rolls to perform.
+      N = 10_000
+
+      private
+
+      def validate(dice)
+        dice.all?(NumericDie)
+      end
+
+      def calculate(dice, rolls: N)
+        statistics = rolls.times.with_object(Hash.new(0)) { |_, hash| hash[dice.sum(&:roll)] += 1 }
+        total_results = dice.map(&:sides_num).reduce(:*)
+        statistics.transform_values { (_1 * total_results).fdiv(rolls) }
+      end
+
+      def verify_result(*)
+        # Ignore verification, as this is inherently imprecise.
+        true
+      end
+    end
+  end
+end

data/lib/dicey/sum_frequency_calculators/kronecker_substitution.rb

@@ -10,7 +10,9 @@ module Dicey
     #
     # Based on Kronecker substitution method for polynomial multiplication.
     # @see https://en.wikipedia.org/wiki/Kronecker_substitution
-    # @see https://arxiv.org/pdf/0712.4046v1.pdf in particular section 3
+    # @see https://arxiv.org/pdf/0712.4046v1.pdf
+    #   David Harvey, Faster polynomial multiplication via multi-point Kronecker substitution
+    #   (in particular section 3)
     class KroneckerSubstitution < BaseCalculator
       private
 
@@ -18,7 +20,7 @@ module Dicey
         dice.all? { |die| die.sides_list.all? { _1.is_a?(Integer) && _1 >= 0 } }
       end
 
-      def calculate(dice)
+      def calculate(dice, **nil)
         polynomials = build_polynomials(dice)
         evaluation_point = find_evaluation_point(polynomials)
         values = evaluate_polynomials(polynomials, evaluation_point)

data/lib/dicey/sum_frequency_calculators/multinomial_coefficients.rb

@@ -9,7 +9,7 @@ module Dicey
     # Example dice: (1,2,3,4), (-2,-1,0,1,2), (0,0.2,0.4,0.6), (-1,-2,-3).
     #
     # Based on extension of Pascal's triangle for a higher number of coefficients.
-    # @see https://en.wikipedia.org/wiki/Pascal%27s_triangle
+    # @see https://en.wikipedia.org/wiki/Pascal's_triangle
     # @see https://en.wikipedia.org/wiki/Trinomial_triangle
     class MultinomialCoefficients < BaseCalculator
       private
@@ -33,9 +33,7 @@ module Dicey
         true
       end
 
-      # @param dice [Array<NumericDie>]
-      # @return [Hash{Numeric => Integer}]
-      def calculate(dice)
+      def calculate(dice, **nil)
         first_die = dice.first
         number_of_sides = first_die.sides_num
         number_of_dice = dice.size

data/lib/dicey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dicey
-  VERSION = "0.14.0"
+  VERSION = "0.15.0"
 end

data/lib/dicey.rb

@@ -5,7 +5,7 @@ module Dicey
   # General error for Dicey.
   class DiceyError < StandardError; end
 
-  Dir["#{__dir__}/dicey/*.rb"].each { require _1 }
-  Dir["#{__dir__}/dicey/output_formatters/*.rb"].each { require _1 }
-  Dir["#{__dir__}/dicey/sum_frequency_calculators/*.rb"].each { require _1 }
+  Dir["dicey/*.rb", base: __dir__].each { require_relative _1 }
+  Dir["dicey/output_formatters/*.rb", base: __dir__].each { require_relative _1 }
+  Dir["dicey/sum_frequency_calculators/*.rb", base: __dir__].each { require_relative _1 }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dicey
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Alexandr Bulancov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-11 00:00:00.000000000 Z
+date: 2025-09-22 00:00:00.000000000 Z
 dependencies: []
 description: |
   Dicey provides a CLI executable and a Ruby API for fast calculation of
@@ -46,6 +46,7 @@ files:
 - lib/dicey/roller.rb
 - lib/dicey/sum_frequency_calculators/base_calculator.rb
 - lib/dicey/sum_frequency_calculators/brute_force.rb
+- lib/dicey/sum_frequency_calculators/empirical.rb
 - lib/dicey/sum_frequency_calculators/kronecker_substitution.rb
 - lib/dicey/sum_frequency_calculators/multinomial_coefficients.rb
 - lib/dicey/sum_frequency_calculators/runner.rb
@@ -57,9 +58,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/trinistr/dicey
   bug_tracker_uri: https://github.com/trinistr/dicey/issues
-  documentation_uri: https://rubydoc.info/gems/dicey/0.14.0
-  source_code_uri: https://github.com/trinistr/dicey/tree/v0.14.0
-  changelog_uri: https://github.com/trinistr/dicey/blob/v0.14.0/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/dicey/0.15.0
+  source_code_uri: https://github.com/trinistr/dicey/tree/v0.15.0
+  changelog_uri: https://github.com/trinistr/dicey/blob/v0.15.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: