dicey 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13602eca86dfef1610dd824ffcab19809d7416418f077ea7b51f8f2fc713ec17
-  data.tar.gz: 7a24922897bad67486e72592189a51358bc861e53c332a0780901ef7ddf66e2f
+  metadata.gz: b23d3fe347080f349190417819aba5f2778a6196569ab39e38d79049f7557f02
+  data.tar.gz: 5bd9295a6bb1a15fe33fe3b967fd1d2c0784a19e713977f57da7910589687ebe
 SHA512:
-  metadata.gz: 336cdbe4078db28e015ed393a65b358c9df13873b70da3f215cb75af95c84a67ae7ff6ec0939cd66c9f12b281e792d1acb9a0d00ec4e3f9c107b446e70cad703
-  data.tar.gz: 964b1502f92086c86b2861bd2eec432effec526b5aecbeb056f82a59cc2be83b1fe7fbe39482350d6764f994f432ebaef3f6e76b70f824adcc2cd630e9decaaf
+  metadata.gz: 778d6f36d896b5db19411bedf0bf272082310eb2c9a1403b57962932979ec0da863b6d408c9245b49bbfb914c99cc2bfa9e8443e0a02d732d2723f93f8b1f6bb
+  data.tar.gz: 694960b274505249fc705e0a61bb1452b6efed062d8b183c154734a9677cc9c28309cf859917443fd997a60de70e00c7f45abc9f9e36e96007949c1bdbee7e0f

data/README.md

@@ -1,16 +1,35 @@
 # Dicey
 
+[![Gem Version](https://badge.fury.io/rb/dicey.svg?icon=si%3Arubygems)](https://rubygems.org/gems/dicey)
+[![CI](https://github.com/trinistr/dicey/actions/workflows/CI.yaml/badge.svg)](https://github.com/trinistr/dicey/actions/workflows/CI.yaml)
+
 > [!TIP]
 > You may be viewing documentation for an older (or newer) version of the gem than intended. Look at [Changelog](https://github.com/trinistr/dicey/blob/main/CHANGELOG.md) to see all versions, including unreleased changes.
 
-<!-- Latest: [![Gem Version](https://badge.fury.io/rb/dicey.svg?icon=si%3Arubygems)](https://rubygems.org/gems/dicey) -->
-<!-- [![CI](https://github.com/trinistr/dicey/actions/workflows/CI.yaml/badge.svg)](https://github.com/trinistr/dicey/actions/workflows/CI.yaml) -->
-
 ***
 
 The premier solution in total paradigm shift for resolving dicey problems of tomorrow, today, used by industry-leading professionals around the world!
 
-In seriousness, this program produces total frequency (probability) distributions of all possible dice rolls for a given set of dice. Dice in such a set can be different or even have arbitrary numbers on the sides.
+In seriousness, this program is mainly useful for calculating total frequency (probability) distributions of all possible dice rolls for a given set of dice. Dice in such a set can be different or even have arbitrary numbers on the sides. It can also be used to roll any dice that it supports.
+
+## Table of contents
+
+- [No installation](#no-installation)
+- [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)
+  - [Dice](#dice)
+  - [Rolling](#rolling)
+  - [Calculators](#calculators)
+- [Diving deeper](#diving-deeper)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## No installation
 
@@ -22,7 +41,7 @@ Thanks to the efforts of Ruby developers, you can try **Dicey** online!
 
 ## Installation
 
-Install via `gem`:
+Install manually via `gem`:
 ```sh
 gem install dicey
 ```
@@ -36,20 +55,24 @@ gem "dicey", "~> 0.13"
 > Versions upto 0.12.1 were packaged as a single executable file. You can still download it from the [release](https://github.com/trinistr/dicey/releases/tag/v0.12.1).
 
 > [!NOTE]
-> `dicey` 0.0.1 was a completely separate project by [Adam Rogers](https://github.com/rodreegez). Big thanks for transfering the name!
+> `dicey` 0.0.1 was a completely separate [project](https://github.com/rodreegez/dicey) by [Adam Rogers](https://github.com/rodreegez). Big thanks for transfering the name!
 
 ### Requirements
 
-**Dicey** is developed on Ruby 3.2, but should work fine on 3.1 and later versions. There are no dependencies aside from standard library (`json`, `yaml`, `bigdecimal`) and common usage will not even load them.
+**Dicey** is tested to work on CRuby 3.0+, latest JRuby and TruffleRuby. Compatible implementations should work too.
+- JSON and YAML formatting require `json` and `yaml`.
+- Decimal dice require `bigdecimal`.
+
+Otherwise, there are no direct dependencies.
 
-## Usage
+## Usage / CLI (command line interface)
 
 Following examples assume that `dicey` (or `dicey-to-gnuplot`) is executable and is in `$PATH`. You can also run it with `ruby dicey` instead.
 
 > [!NOTE]
 > 💡 Run `dicey --help` to get a list of all possible options.
 
-### Example 1
+### 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
@@ -85,11 +108,12 @@ $ 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
+### 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
-$ dicey 8 4 4
+# Note the shorthand notation for two dice!
+$ dicey 8 2d4
 # [8];⚃;⚃
 3 => 1
 4 => 3
@@ -109,19 +133,48 @@ $ dicey 8 4 4
 
 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
+
 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 4 4 --format gnuplot | dicey-to-gnuplot
-# --format gnuplot can be abbreviated to -f g
+$ dicey 8 2d4 --format gnuplot | dicey-to-gnuplot
+# `--format gnuplot` can be abbreviated as `-f g`
 ```
 
 This will create a PNG image named `[8];⚃;⚃.png`:
 ![Graph of damage roll frequencies for Burning Sword]([8];⚃;⚃.png)
 
-> [!NOTE]
-> 💡 It is possible to output JSON or YAML with `--format json` and `--format yaml` respectively.
+#### 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.
 
-### Example 3
+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}}
+```
+
+YAML via `dicey 8 2d4 --format yaml`:
+```yaml
+---
+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
+```
+
+### 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.
 
@@ -141,15 +194,29 @@ $ 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 integer argument N practically is a shorthand for listing every side from 1 to N.
+> 💡 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)
+2 => 1
+3 => 2
+4 => 1
+5 => 2
+6 => 2
+8 => 1
+```
+
+Hah, now this is a properly cursed distribution!
 
-### Example 4
+### 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
+$ dicey 0.5,1.5,2.5 4 --mode roll # As always, can be abbreviated to -m r
 # (0.5e0,0.15e1,0.25e1);⚃
 roll => 0.35e1 # You probably will get a different value here.
 ```
@@ -157,6 +224,100 @@ roll => 0.35e1 # You probably will get a different value here.
 > [!NOTE]
 > 💡 Roll mode is compatible with `--format`, but not `--result`.
 
+## Usage / API
+
+> [!Note]
+> - Latest 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).
+
+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.
+
+> [!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:
+```rb
+Dicey::DieFoundry.new.call("100")
+  # same as Dicey::RegularDie.new(100)
+Dicey::DieFoundry.new.call("2d6")
+  # same as Dicey::RegularDie.from_count(2, 6)
+Dicey::DieFoundry.new.call("1d1,2,4")
+  # same as Dicey::NumericDie.from_list([1,2,4])
+```
+
+It only takes a single argument and may return both an array of dice and a single die. You will probably want to use `Enumerable#flat_map`:
+```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)]
+```
+
+### Rolling
+
+`Dicey::AbstractDie#roll` implements the rolling:
+```rb
+Dicey::AbstractDie.new([0, 1, 5, "10"]).roll
+  # almost same as [0, 1, 5, "10"].sample
+Dicey::RegularDie.new(6).roll
+  # almost same as rand(1..6)
+```
+
+Dice retain their roll state, with `#current` returning the last roll (or initial side if never rolled):
+```rb
+die = Dicey::RegularDie.new(6)
+die.current
+  # => 1
+die.roll
+  # => 3
+die.current
+  # => 3
+```
+
+Rolls can be reproducible if a specific seed is set:
+```rb
+Dicey::AbstractDie.srand(493_525)
+die = Dicey::RegularDie.new(6)
+die.roll
+  # => 4
+die.roll
+  # => 1
+# Repeat:
+Dicey::AbstractDie.srand(493_525)
+die = Dicey::RegularDie.new(6)
+die.roll
+  # => 4
+die.roll
+  # => 1
+```
+
+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:
+- `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.
+
+Calculators inherit from `Dicey::SumFrequencyCalculators::BaseCalculator` and provide the following public interface:
+- `#call(dice, result_type: {:frequencies | :probabilities}) : Hash`
+- `#valid_for?(dice) : Boolean`
+
+See [next section](#diving-deeper) for more details on limitations and complexity considerations.
+
 ## Diving deeper
 
 For a further discussion of calculations, it is important to understand which classes of dice exist.
@@ -209,7 +370,7 @@ As a last resort, there is a brute force algorithm which goes through every poss
 
 ## Development
 
-After checking out the repo, run `bundle` (or `bundle install`) to install dependencies. Then, run `rake spec` to run the tests, `rake rubocop` to lint code and check style compliance, `rake rbs` to validate signatures or just `rake` to do everything above. There is also `rake steep` to check typing, and `rake docs` to generate YARD documentation.
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests, `rake rubocop` to lint code and check style compliance, `rake rbs` to validate signatures or just `rake` to do everything above. There is also `rake steep` to check typing, and `rake docs` to generate YARD documentation.
 
 You can also run `bin/console` for an interactive prompt that will allow you to experiment, or `bin/benchmark` to run a benchmark script and generate a StackProf flamegraph.
 
@@ -223,13 +384,13 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/trinis
 
 ### Checklist for a new or updated feature
 
-- Running `rspec` reports 100% coverage (unless it's impossible to achieve in one run).
-- Running `rubocop` reports no offenses.
+- Running `rake spec` reports 100% coverage (unless it's impossible to achieve in one run).
+- Running `rake rubocop` reports no offenses.
 - Running `rake steep` reports no new warnings or errors.
-- Tests cover the behavior and its interactions. 100% coverage *is not enough*, as it does not guarantee that all code paths are covered.
+- Tests cover the behavior and its interactions. 100% coverage *is not enough*, as it does not guarantee that all code paths are tested.
 - Documentation is up-to-date: generate it with `rake docs` and read it.
-- `CHANGELOG.md` lists the change if it has impact on users.
-- `README.md` is updated if the feature should be visible there.
+- "*CHANGELOG.md*" lists the change if it has impact on users.
+- "*README.md*" is updated if the feature should be visible there, including the Kanban board.
 
 ## License
 

data/lib/dicey/abstract_die.rb

@@ -6,6 +6,7 @@ module Dicey
   class AbstractDie
     # rubocop:disable Style/ClassVars
 
+    # @api private
     # Get a random value using a private instance of Random.
     # @see Random#rand
     def self.rand(...)
@@ -26,66 +27,110 @@ module Dicey
 
     # Get a text representation of a list of dice.
     #
-    # @param dice [Enumerable<AbstractDie>]
+    # @param dice [Enumerable<AbstractDie>, AbstractDie]
     # @return [String]
     def self.describe(dice)
-      dice.join(";")
+      return dice.to_s if AbstractDie === dice
+      return dice.join(";") if Array === dice
+
+      dice.to_a.join(";")
+    end
+
+    # Create a bunch of different dice at once.
+    #
+    # @param definitions [Array<Enumerable<Any>>, Array<Any>]
+    #   list of definitions suitable for the dice class
+    # @return [Array<AbstractDie>]
+    def self.from_list(*definitions)
+      definitions.map { new(_1) }
+    end
+
+    # Create a number of equal dice.
+    #
+    # @param count [Integer] number of dice to create
+    # @param definition [Enumerable<Any>, Any]
+    #   definition suitable for the dice class
+    # @return [Array<AbstractDie>]
+    def self.from_count(count, definition)
+      Array.new(count) { new(definition) }
     end
 
     attr_reader :sides_list, :sides_num
 
-    # @param sides_list [Enumerable<Object>]
+    # @param sides_list [Enumerable<Any>]
     # @raise [DiceyError] if +sides_list+ is empty
     def initialize(sides_list)
-      @sides_list = sides_list.is_a?(Array) ? sides_list.dup.freeze : sides_list.to_a.freeze
+      @sides_list = (Array === sides_list) ? sides_list.dup.freeze : sides_list.to_a.freeze
       raise DiceyError, "dice must have at least one side!" if @sides_list.empty?
 
       @sides_num = @sides_list.size
-
-      sides_enum = @sides_list.to_enum
-      @enum =
-        Enumerator.produce do
-          sides_enum.next
-        rescue StopIteration
-          sides_enum.rewind
-          retry
-        end
+      @current_side_index = 0
     end
 
     # Get current side of the die.
-    # @return [Object] current side
+    #
+    # @return [Any] current side
     def current
-      @enum.peek
+      @sides_list[@current_side_index]
     end
 
-    # Get next side of the die, advancing internal enumerator state.
-    # Wraps from last to first side.
-    # @return [Object] next side
+    # Get next side of the die, advancing internal state.
+    # Starts from first side, wraps from last to first side.
+    #
+    # @return [Any] next side
     def next
-      @enum.next
+      ret = current
+      @current_side_index = (@current_side_index + 1) % @sides_num
+      ret
     end
 
-    # Advance internal enumerator state by a random number using {#next}.
-    # @return [Object] rolled side
+    # Move internal state to a random side.
+    #
+    # @return [Any] rolled side
     def roll
-      self.class.rand(0...sides_num).times { self.next }
+      @current_side_index = self.class.rand(0...@sides_num)
       current
     end
 
     # @return [String]
     def to_s
-      "(#{sides_list.join(",")})"
+      "(#{@sides_list.join(",")})"
     end
 
     # Determine if this die and the other one have the same list of sides.
     # Be aware that differently ordered sides are not considered equal.
     #
-    # @param other [AbstractDie, Object]
+    # @param other [AbstractDie, Any]
     # @return [Boolean]
     def ==(other)
-      return false unless other.is_a?(AbstractDie)
+      AbstractDie === other && same_sides?(other)
+    end
 
-      sides_list == other.sides_list
+    # Determine if this die and the other one are of the same class
+    # and have the same list of sides.
+    # Be aware that differently ordered sides are not considered equal.
+    #
+    # +die_1.eql?(die_2)+ implies +die_1.hash == die_2.hash+.
+    #
+    # @param other [AbstractDie, Any]
+    # @return [Boolean]
+    def eql?(other)
+      self.class === other && same_sides?(other)
+    end
+
+    # Generates an Integer hash value for this object.
+    #
+    # @return [Integer]
+    def hash
+      [self.class, @sides_list].hash
+    end
+
+    private
+
+    # @param other [AbstractDie]
+    # @return [Boolean]
+    def same_sides?(other)
+      @sides_list == other.sides_list
     end
   end
 end

data/lib/dicey/cli/options.rb

@@ -19,6 +19,9 @@ module Dicey
       def initialize(initial_options = DEFAULT_OPTIONS.dup)
         @options = initial_options
         @parser = ::OptionParser.new
+        @parser.program_name = "dicey"
+        @parser.version = Dicey::VERSION
+
         add_banner_and_version
         add_common_options
         add_test_options
@@ -54,7 +57,6 @@ module Dicey
                  #{@parser.program_name} --test [full|quiet]
           All option names and arguments can be abbreviated if abbreviation is unambiguous.
         TEXT
-        @parser.version = Dicey::VERSION
       end
 
       def add_common_options
@@ -86,13 +88,14 @@ module Dicey
         end
       end
 
-      def easy_option(short, long, values, description, &)
-        values = values.keys if values.respond_to?(:keys)
+      def easy_option(short, long, values, description, &block)
         option_name = long[/[a-z_]+/].to_sym
         argument_name = long[/[A-Z_]+/]
         listed_values = "#{argument_name} can be: #{values.map { "`#{_1}`" }.join(", ")}."
-        default_value = "`#{@options[option_name]}` is default." if @options[option_name]
-        @parser.on(*[short, long, values, description, listed_values, default_value].compact, &)
+        default_value = "`#{@options[option_name]}` is default."
+        @parser.on(
+          *[short, long, values, description, listed_values, default_value].compact, &block
+        )
       end
     end
   end

data/lib/dicey/die_foundry.rb

@@ -6,52 +6,71 @@ 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
+
     # Possible molds for the dice. They are matched in the order as written.
-    MOLDS = {
+    MOLDS = [
       # Positive integer goes into the RegularDie mold.
-      ->(d) { /\A[1-9]\d*\z/.match?(d) } => :regular_mold,
+      [/\A#{COUNT}(?<sides>[1-9]\d*+)\z/, :regular_mold],
       # List of numbers goes into the NumericDie mold.
-      ->(d) { /\A\(?-?\d++(?:,-?\d++)*\)?\z/.match?(d) } => :weirdly_shaped_mold,
-      # Real numbers require arbitrary precision arithmetic, which is not enabled by default.
-      ->(d) {
-        /\A\(?-?\d++(?:\.\d++)?(?:,-?\d++(?:\.\d++)?)*+\)?\z/.match?(d)
-      } => :weirdly_precise_mold,
+      [/\A#{COUNT}\(?(?<sides>-?\d++(?>,(?>-?\d++)?)*)\)?\z/, :weirdly_shaped_mold],
+      # Non-integers require arbitrary precision arithmetic, which is not enabled by default.
+      [/\A#{COUNT}\(?(?<sides>-?\d++(?>\.\d++)?(?>,(?>-?\d++(?>\.\d++)?)?)*)\)?\z/,
+       :weirdly_precise_mold],
       # Anything else is spilled on the floor.
-      ->(*) { true } => :broken_mold,
-    }.freeze
-
-    # Regexp for removing brackets from lists.
-    BRACKET_STRIPPER = /\A\(?(.+)\)?\z/
+    ].freeze
 
     # Cast a die definition into a mold to make a die.
     #
-    # @param definition [String] die shape, refer to {MOLDS} for possible variants
-    # @return [NumericDie, RegularDie]
+    # Following definitions are recognized:
+    # - positive integer (like "6" or "20"), which produces a {RegularDie};
+    # - 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},
+    #   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>]
     # @raise [DiceyError] if no mold fits the definition
-    def cast(definition)
-      _shape, mold = MOLDS.find { |shape, _mold| shape.call(definition) }
-      __send__(mold, definition)
+    def call(definition)
+      matched, name =
+        MOLDS.reduce(nil) do |_, (shape, mold)|
+          match = shape.match(definition)
+          break [match, mold] if match
+        end
+      raise DiceyError, "can not cast die from `#{definition}`!" unless name
+
+      __send__(name, matched)
     end
 
+    alias cast call
+
     private
 
     def regular_mold(definition)
-      RegularDie.new(definition.to_i)
+      build_dice(RegularDie, definition[:count], definition[:sides].to_i)
     end
 
     def weirdly_shaped_mold(definition)
-      definition = definition.match(BRACKET_STRIPPER)[1]
-      NumericDie.new(definition.split(",").map(&:to_i))
+      build_dice(NumericDie, definition[:count], definition[:sides].split(",").map(&:to_i))
     end
 
     def weirdly_precise_mold(definition)
-      require "bigdecimal"
-      definition = definition.match(BRACKET_STRIPPER)[1]
-      NumericDie.new(definition.split(",").map { BigDecimal(_1) })
+      require "bigdecimal" unless defined?(BigDecimal)
+
+      sides = definition[:sides].split(",").map { BigDecimal(_1) }
+      build_dice(NumericDie, definition[:count], sides)
     end
 
-    def broken_mold(definition)
-      raise DiceyError, "can not cast die from `#{definition}`!"
+    def build_dice(die_class, count, sides)
+      if count
+        die_class.from_count(count.to_i, sides)
+      else
+        die_class.new(sides)
+      end
     end
   end
 end

data/lib/dicey/numeric_die.rb

@@ -8,9 +8,16 @@ module Dicey
     # @param sides_list [Enumerable<Numeric>]
     # @raise [DiceyError] if +sides_list+ contains non-numerical values or is empty
     def initialize(sides_list)
-      sides_list.each do |value|
-        raise DiceyError, "`#{value}` is not a number!" unless value.is_a?(Numeric)
+      if Range === sides_list
+        unless Numeric === sides_list.begin && Numeric === sides_list.end
+          raise DiceyError, "`#{sides_list.inspect}` is not a numerical range!"
+        end
+      else
+        sides_list.each do |value|
+          raise DiceyError, "`#{value.inspect}` is not a number!" unless Numeric === value
+        end
       end
+
       super
     end
   end

data/lib/dicey/regular_die.rb

@@ -8,22 +8,18 @@ module Dicey
     # Characters to use for small dice.
     D6 = "⚀⚁⚂⚃⚄⚅"
 
-    # Create a list of regular dice with the same number of sides.
-    #
-    # @param dice [Integer]
-    # @param sides [Integer]
-    # @return [Array<RegularDie>]
-    def self.create_dice(dice, sides)
-      (1..dice).map { new(sides) }
-    end
+    # @param max [Integer] maximum side / number of sides
+    def initialize(max)
+      unless Integer === max && max.positive?
+        raise DiceyError, "regular dice can contain only positive integers, #{max.inspect} is not"
+      end
 
-    # @param sides [Integer]
-    def initialize(sides)
-      super((1..sides))
+      super((1..max))
     end
 
-    # Dice with 1–6 sides are displayed with a single character.
+    # 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 [String]
     def to_s
       (sides_num <= D6.size) ? D6[sides_num - 1] : "[#{sides_num}]"

data/lib/dicey/roller.rb

@@ -12,10 +12,9 @@ module Dicey
     def call(arguments, format:, **)
       raise DiceyError, "no dice!" if arguments.empty?
 
-      dice = arguments.map { |definition| die_foundry.cast(definition) }
-      dice.each(&:roll)
+      dice = arguments.flat_map { |definition| die_foundry.cast(definition) }
+      result = dice.sum(&:roll)
 
-      result = dice.sum(&:current)
       format.call({ "roll" => result }, AbstractDie.describe(dice))
     end
 

data/lib/dicey/sum_frequency_calculators/base_calculator.rb

@@ -18,6 +18,8 @@ module Dicey
         unless RESULT_TYPES.include?(result_type)
           raise DiceyError, "#{result_type} is not a valid result type!"
         end
+        # Short-circuit for a degenerate case.
+        return {} if dice.empty?
         raise DiceyError, "#{self.class} can not handle these dice!" unless valid_for?(dice)
 
         frequencies = calculate(dice)
@@ -31,7 +33,7 @@ module Dicey
       # @param dice [Enumerable<AbstractDie>]
       # @return [Boolean]
       def valid_for?(dice)
-        dice.is_a?(Enumerable) && dice.all? { _1.is_a?(AbstractDie) } && validate(dice)
+        dice.is_a?(Enumerable) && dice.all?(AbstractDie) && validate(dice)
       end
 
       private
@@ -45,7 +47,9 @@ module Dicey
       # Peform frequencies calculation.
       # (see #call)
       def calculate(dice)
+        # :nocov:
         raise NotImplementedError
+        # :nocov:
       end
 
       # Check that resulting frequencies actually add up to what they are supposed to be.
@@ -55,7 +59,7 @@ module Dicey
       # @return [void]
       # @raise [DiceyError] if result is wrong
       def verify_result(frequencies, dice)
-        valid = frequencies.values.sum == dice.map(&:sides_num).reduce(:*)
+        valid = frequencies.values.sum == (dice.map(&:sides_num).reduce(:*) || 0)
         raise DiceyError, "calculator #{self.class} returned invalid results!" unless valid
       end
 
@@ -74,14 +78,11 @@ module Dicey
       # @param result_type [Symbol] one of {RESULT_TYPES}
       # @return [Hash{Numeric => Numeric}]
       def transform_result(frequencies, result_type)
-        case result_type
-        when :frequencies
+        if result_type == :frequencies
           frequencies
-        when :probabilities
+        else
           total = frequencies.values.sum
           frequencies.transform_values { _1.fdiv(total) }
-        else
-          # Invalid, but was already checked in #call.
         end
       end
     end

data/lib/dicey/sum_frequency_calculators/brute_force.rb

@@ -8,51 +8,49 @@ module Dicey
     class BruteForce < BaseCalculator
       private
 
-      # def validate(dice)
-      #   dice.all? { |die| die.is_a?(NumericDie) }
-      # end
+      def validate(dice)
+        dice.all?(NumericDie)
+      end
 
       def calculate(dice)
-        # TODO: Replace `combine_dice_enumerators` with `Enumerator.product`.
         combine_dice_enumerators(dice).map(&:sum).tally
       end
 
-      # Get an enumerator which goes through all possible permutations of dice sides.
-      #
-      # @param dice [Enumerable<NumericDie>]
-      # @return [Enumerator<Array>]
-      def combine_dice_enumerators(dice)
-        sides_num_list = dice.map(&:sides_num)
-        total = sides_num_list.reduce(:*)
-        Enumerator.new(total) do |yielder|
-          current_values = dice.map(&:next)
-          remaining_iterations = sides_num_list
-          total.times do
-            yielder << current_values
-            iterate_dice(dice, remaining_iterations, current_values)
-          end
+      if defined?(Enumerator::Product)
+        # Get an enumerator which goes through all possible permutations of dice sides.
+        #
+        # @param dice [Enumerable<NumericDie>]
+        # @return [Enumerator<Array<Numeric>>]
+        def combine_dice_enumerators(dice)
+          Enumerator::Product.new(*dice.map(&:sides_list))
+        end
+      # :nocov:
+      else
+        # Get an enumerator which goes through all possible permutations of dice sides.
+        #
+        # @param dice [Enumerable<NumericDie>]
+        # @return [Enumerator<Array<Numeric>>]
+        def combine_dice_enumerators(dice)
+          product(dice.map(&:sides_list))
         end
-      end
 
-      # Iterate through dice, getting next side for first die,
-      # then getting next side for second die, resetting first die, and so on.
-      # This is analogous to incrementing by 1 in a positional system
-      # where each position is a die.
-      #
-      # @param dice [Enumerable<NumericDie>]
-      # @param remaining_iterations [Array<Integer>]
-      # @param current_values [Array<Numeric>]
-      # @return [void]
-      def iterate_dice(dice, remaining_iterations, current_values)
-        dice.each_with_index do |die, i|
-          value = die.next
-          current_values[i] = value
-          remaining_iterations[i] -= 1
-          break if remaining_iterations[i].nonzero?
+        # Simplified implementation of {Enumerator::Product}.
+        # Adapted from {https://bugs.ruby-lang.org/issues/18685#note-10}.
+        #
+        # @param enums [Enumerable<Enumerable<Numeric>>]
+        # @return [Enumerator<Array<Numeric>>]
+        def product(enums, &block)
+          return to_enum(__method__, enums) unless block_given?
 
-          remaining_iterations[i] = die.sides_num
+          enums
+            .reverse
+            .reduce(block) { |inner, enum|
+              ->(values) { enum.each_entry { inner.call([*values, _1]) } }
+            }
+            .call([])
         end
       end
+      # :nocov:
     end
   end
 end

data/lib/dicey/sum_frequency_calculators/multinomial_coefficients.rb

@@ -30,6 +30,7 @@ module Dicey
         return false if increment.zero?
 
         sides_list.each_cons(2) { return false if _1 + increment != _2 }
+        true
       end
 
       # @param dice [Array<NumericDie>]
@@ -48,27 +49,22 @@ module Dicey
       #
       # @param dice [Integer] number of dice, must be positive
       # @param sides [Integer] number of sides, must be positive
-      # @param throw_away_garbage [Boolean] whether to discard unused coefficients (debug option)
       # @return [Array<Integer>]
-      def multinomial_coefficients(dice, sides, throw_away_garbage: true)
-        # This builds a triangular matrix where each first element is a 1.
-        # Each element is a sum of +m+ elements in the previous row
-        # with indices less or equal to its, with out-of-bounds indices corresponding to 0s.
-        # Example for m=3:
+      def multinomial_coefficients(dice, sides)
+        # This builds a triangular matrix where first elements are always 1s
+        # and other elements are sums of +sides+ elements in the previous row
+        # with indices less or equal, with out-of-bounds indices corresponding to 0s.
+        # Example for sides=3:
         # 1
         # 1 1 1
         # 1 2 3 2 1
         # 1 3 6 7 6 3 1, etc.
-        coefficients = [[1]]
-        (1..dice).each do |row_index|
-          row = next_row_of_coefficients(row_index, sides - 1, coefficients.last)
-          if throw_away_garbage
-            coefficients[0] = row
-          else
-            coefficients << row
-          end
+        # We start directly from second row, which corresponds to 1 die.
+        coefficients = Array.new(sides, 1)
+        (2..dice).each do |row_index|
+          coefficients = next_row_of_coefficients(row_index, sides - 1, coefficients)
         end
-        coefficients.last
+        coefficients
       end
 
       # @param row_index [Integer]
@@ -79,7 +75,8 @@ module Dicey
         length = (row_index * window_size) + 1
         (0..length).map do |col_index|
           # Have to clamp to 0 to prevent accessing array from the end.
-          window_range = ((col_index - window_size).clamp(0..)..col_index)
+          # BUG: TruffleRuby can't handle endless range in #clamp (see https://github.com/oracle/truffleruby/issues/3945)
+          window_range = ((col_index - window_size).clamp(0..col_index)..col_index)
           window_range.sum { |i| previous_row.fetch(i, 0) }
         end
       end

data/lib/dicey/sum_frequency_calculators/runner.rb

@@ -21,7 +21,7 @@ module Dicey
       def call(arguments, roll_calculators:, format:, result:, **)
         raise DiceyError, "no dice!" if arguments.empty?
 
-        dice = arguments.map { |definition| die_foundry.cast(definition) }
+        dice = arguments.flat_map { |definition| die_foundry.cast(definition) }
         frequencies = roll_calculators.find { _1.valid_for?(dice) }&.call(dice, result_type: result)
         raise DiceyError, "no calculator could handle these dice!" unless frequencies
 

data/lib/dicey/version.rb

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

metadata

@@ -1,14 +1,25 @@
 --- !ruby/object:Gem::Specification
 name: dicey
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Alexandr Bulancov
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-09-11 00:00:00.000000000 Z
 dependencies: []
+description: |
+  Dicey provides a CLI executable and a Ruby API for fast calculation of
+  frequency/probability distributions of dice rolls,
+  with support for all kinds of numeric dice, even Complex ones!
+  Results can be exported as JSON, YAML or a gnuplot data file.
+
+  It can also be used to roll dice. While not the primary focus,
+  rolling is well supported, including ability to seed random source
+  for reproducible results.
+email:
 executables:
 - dicey
 - dicey-to-gnuplot
@@ -40,17 +51,17 @@ files:
 - lib/dicey/sum_frequency_calculators/runner.rb
 - lib/dicey/sum_frequency_calculators/test_runner.rb
 - lib/dicey/version.rb
-- sig/dicey.rbs
 homepage: https://github.com/trinistr/dicey
 licenses:
 - MIT
 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.13.1
-  source_code_uri: https://github.com/trinistr/dicey/tree/v0.13.1
-  changelog_uri: https://github.com/trinistr/dicey/blob/v0.13.1/CHANGELOG.md
+  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
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options:
 - "--main"
 - README.md
@@ -60,14 +71,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: Calculator of dice roll frequencies/probabilities. Also rolls dice.
+summary: Calculator for dice roll frequency/probability distributions. Also rolls
+  dice.
 test_files: []

data/sig/dicey.rbs

@@ -1,3 +0,0 @@
-module Dicey
-  VERSION: String
-end