dicey 0.14.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b23d3fe347080f349190417819aba5f2778a6196569ab39e38d79049f7557f02
-  data.tar.gz: 5bd9295a6bb1a15fe33fe3b967fd1d2c0784a19e713977f57da7910589687ebe
+  metadata.gz: 315d35b504558fad6ce08ebd3e648903e9f85e97dd5388c20afbcff896c40825
+  data.tar.gz: f4138742272906c291d44533391e3b63216c45f8bd99337f8c570e252bd0ce3b
 SHA512:
-  metadata.gz: 778d6f36d896b5db19411bedf0bf272082310eb2c9a1403b57962932979ec0da863b6d408c9245b49bbfb914c99cc2bfa9e8443e0a02d732d2723f93f8b1f6bb
-  data.tar.gz: 694960b274505249fc705e0a61bb1452b6efed062d8b183c154734a9677cc9c28309cf859917443fd997a60de70e00c7f45abc9f9e36e96007949c1bdbee7e0f
+  metadata.gz: 201115ad574e086ab99bf62d0129ae2dd3457cf2c06639d2e18f95c16699fa42f0ec72852aa13bdea408001a27fc366c1150d7cef2874f227957f5cd0e80bc40
+  data.tar.gz: abfec7efee1b05e607432650a6e5de444e2cf75d9c462e9b6a0211cb48888234ccf4e95ddb50d431017ddc01d5969d6ca4b6a130faefd31b7f852dc3c41a9200

data/README.md

@@ -14,30 +14,45 @@ 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)
+  - [Distribution calculators](#distribution-calculators)
+  - [Distribution properties](#distribution-properties)
 - [Diving deeper](#diving-deeper)
 - [Development](#development)
 - [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 +63,7 @@ gem install dicey
 
 Or, if using Bundler, add it to your `Gemfile`:
 ```rb
-gem "dicey", "~> 0.13"
+gem "dicey", "~> 0.14"
 ```
 
 > [!TIP]
@@ -61,18 +76,17 @@ gem "dicey", "~> 0.13"
 
 **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 / 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,25 +110,25 @@ 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
-# ⚃;⚃
-2 => 0.0625
-3 => 0.125
-4 => 0.1875
-5 => 0.25
-6 => 0.1875
-7 => 0.125
-8 => 0.0625
+# D4+D4
+2 => 1/16
+3 => 1/8
+4 => 3/16
+5 => 1/4
+6 => 3/16
+7 => 1/8
+8 => 1/16
 ```
 
 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);⚃
-roll => 0.35e1 # You probably will get a different value here.
+$ dicey 0.5,1.0,1.5,2.0,2.5 4 --mode roll # As always, can be abbreviated to -m r
+# (1/2,1,3/2,2,5/2)+D4
+roll => 7/2 # 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,28 +330,77 @@ 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
+### Distribution 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.
+Distribution 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 a 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.
+See [Diving deeper](#diving-deeper) for more details on limitations and complexity considerations.
+
+### Distribution properties
+
+While distribution itself is already enough in most cases (we are talking just dice here, after all). it may be of interest to calculate properties of it: mode, mean, expected value, standard deviation, etc. `Dicey::DistributionPropertiesCalculator` already provides this functionality:
+```rb
+Dicey::DistributionPropertiesCalculator.new.call(
+  Dicey::SumFrequencyCalculators::KroneckerSubstitution.new.call(
+    Dicey::RegularDie.from_count(2, 3)
+  )
+)
+  # => 
+  # {:mode=>[4],
+  # :min=>2,
+  # :max=>6,
+  # :total_range=>4,
+  # :mid_range=>4,
+  # :median=>4,
+  # :arithmetic_mean=>4,
+  # :expected_value=>4,
+  # :variance=>(4/3),
+  # :standard_deviation=>1.1547005383792515,
+  # :skewness=>0.0,
+  # :kurtosis=>(9/4),
+  # :excess_kurtosis=>(-3/4)}
+```
+
+Of course, for regular dice most properties are quite simple and predicatable due to symmetricity of distribution. It becomes more interesting with unfair, lopsided dice. Remember [Example 3](#example-3-custom-dice)?
+```rb
+Dicey::DistributionPropertiesCalculator.new.call(
+  Dicey::SumFrequencyCalculators::KroneckerSubstitution.new.call(
+    [Dicey::RegularDie.new(4), Dicey::NumericDie.new([1,3,4])]
+  )
+)
+  # => 
+  # {:mode=>[5],
+  # :min=>2,
+  # :max=>8,
+  # :total_range=>6,
+  # :mid_range=>5,
+  # :median=>5,
+  # :arithmetic_mean=>5,
+  # :expected_value=>(31/6),
+  # :variance=>(101/36),
+  # :standard_deviation=>1.674979270186815,
+  # :skewness=>-0.15762965389465178,
+  # :kurtosis=>(23145/10201),
+  # :excess_kurtosis=>(-7458/10201)}
+```
+
+This disitrubution is obviosuly skewed (as can be immediately seen from non-zero skewness), with expected value no longer equal to mean. This is a mild example. It is easily possible to create a distribution with multiple local maxima and high skewness.
 
 ## 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 +411,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 +425,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
@@ -390,7 +466,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/trinis
 - 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, including the Kanban board.
+- "*README.md*" is updated if the feature should be visible there.
 
 ## License
 

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

@@ -3,21 +3,27 @@
 require_relative "numeric_die"
 require_relative "regular_die"
 
+require_relative "rational_to_integer"
+
 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
+    include RationalToInteger
+
+    # 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],
-      # 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++)?)+|,)\)?\z/, :weirdly_shaped_mold].freeze,
+      # Non-integers require special handling for precision.
+      [/\A#{PREFIX}\(?(?<sides>-?\d++(?>\.\d++)?(?>,(?>-?\d++(?>\.\d++)?)?)+|,)\)?\z/,
+       :weirdly_precise_mold].freeze,
       # Anything else is spilled on the floor.
     ].freeze
 
@@ -25,15 +31,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},
-    #   but uses +BigDecimal+ for values to maintain precise results.
+    # - list of decimal numbers (like "0.5,0.2,0.8" or "(2.0,)"), which produces a {NumericDie},
+    #   but uses +Rational+ 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,14 +61,19 @@ 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
 
     def weirdly_precise_mold(definition)
-      require "bigdecimal" unless defined?(BigDecimal)
-
-      sides = definition[:sides].split(",").map { BigDecimal(_1) }
+      sides = definition[:sides].split(",").map { rational_to_integer(Rational(_1)) }
       build_dice(NumericDie, definition[:count], sides)
     end
 

data/lib/dicey/distribution_properties_calculator.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "rational_to_integer"
+
+module Dicey
+  # Calculates distribution properties,
+  # also known as descriptive statistics when applied to a population sample.
+  #
+  # These are well-known properties such as:
+  # - min, max, mid-range;
+  # - mode, median, arithmetic mean;
+  # - important moments (expected value, variance, skewness, kurtosis).
+  #
+  # It is notable that most dice create symmetric distributions,
+  # which means that skewness is 0, while properties denoting center in some way
+  # (median, mean, ...) are all equal.
+  # Mode is often not unique, but includes this center.
+  class DistributionPropertiesCalculator
+    include RationalToInteger
+
+    # Calculate properties for a given distribution.
+    #
+    # Depending on values in the distribution, some properties may be undefined.
+    # In such cases, only mode is guaranteed to be present.
+    #
+    # @param distribution [Hash{Numeric => Numeric}
+    #   numeric distribution with pre-sorted keys
+    # @return [Hash{Symbol => Numeric, Array<Numeric>}]
+    def call(distribution)
+      return {} if distribution.empty?
+
+      calculate_properties(distribution)
+    end
+
+    private
+
+    def calculate_properties(distribution)
+      outcomes = distribution.keys
+      weights = distribution.values
+
+      {
+        mode: mode(outcomes, weights),
+        **range_characteristics(outcomes),
+        **median(outcomes),
+        **means(outcomes, weights),
+        **moments(distribution),
+      }
+    end
+
+    def mode(outcomes, weights)
+      max_weight = weights.max
+      outcomes.select.with_index { |_, index| weights[index] == max_weight }
+    end
+
+    def range_characteristics(outcomes)
+      min = outcomes.min
+      max = outcomes.max
+      {
+        min: min,
+        max: max,
+        total_range: max - min,
+        mid_range: rational_to_integer(Rational(min + max, 2)),
+      }
+    rescue ArgumentError, TypeError, NoMethodError
+      # Outcomes are not comparable with each other, so a range can not be determined.
+      {}
+    end
+
+    def means(outcomes, _weights)
+      {
+        arithmetic_mean: rational_to_integer(Rational(outcomes.sum, outcomes.size)),
+      }
+    rescue ArgumentError, TypeError
+      # Outcomes are not summable with each other, means are meaningless.
+      {}
+    end
+
+    def median(outcomes)
+      outcomes = outcomes.sort
+      value =
+        if outcomes.size.odd?
+          outcomes[outcomes.size / 2]
+        else
+          Rational(outcomes[(outcomes.size / 2) - 1] + outcomes[outcomes.size / 2], 2)
+        end
+      { median: value }
+    rescue ArgumentError, TypeError, NoMethodError
+      # Outcomes are not compatible with each other, so a median can not be determined.
+      {}
+    end
+
+    def moments(distribution)
+      total_weight = distribution.values.sum
+      expected_value = rational_to_integer(moment(distribution, total_weight, 1))
+      variance = rational_to_integer(moment(distribution, total_weight, 2) - (expected_value**2))
+      skewness =
+        rational_to_integer(moment(distribution, total_weight, 3, expected_value, variance))
+      kurtosis =
+        rational_to_integer(moment(distribution, total_weight, 4, expected_value, variance))
+
+      {
+        expected_value: expected_value,
+        variance: variance,
+        standard_deviation: Math.sqrt(variance),
+        skewness: skewness,
+        kurtosis: kurtosis,
+        excess_kurtosis: kurtosis ? kurtosis - 3 : nil,
+      }
+    rescue ArgumentError, TypeError, NoMethodError
+      # Outcomes are not compatible with each other, moments are fleeing.
+      {}
+    end
+
+    def moment(distribution, total_weight, degree, center = 0, variance = nil)
+      # With 0 variance, normalized moments are undefined.
+      return nil if variance == 0 # rubocop:disable Style/NumericPredicate
+
+      unnormalized = distribution.sum { |r, w| ((r - center)**degree) * Rational(w, total_weight) }
+      variance ? (unnormalized / (variance**(degree/2r))) : unnormalized
+    end
+  end
+end

data/lib/dicey/numeric_die.rb

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

data/lib/dicey/output_formatters/gnuplot_formatter.rb

@@ -5,8 +5,20 @@ require_relative "key_value_formatter"
 module Dicey
   module OutputFormatters
     # Formats a hash as a text file suitable for consumption by Gnuplot.
+    #
+    # Will transform Rational probabilities to Floats.
     class GnuplotFormatter < KeyValueFormatter
       SEPARATOR = " "
+
+      private
+
+      def transform(key, value)
+        [derationalize(key), derationalize(value)]
+      end
+
+      def derationalize(value)
+        value.is_a?(Rational) ? value.to_f : value
+      end
     end
   end
 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.
@@ -21,7 +22,10 @@ module Dicey
       private
 
       def to_primitive(value)
-        primitive?(value) ? value : value.to_s
+        return value if primitive?(value)
+        return value.to_f if Numeric === value
+
+        value.to_s
       end
 
       def primitive?(value)

data/lib/dicey/output_formatters/key_value_formatter.rb

@@ -1,20 +1,34 @@
 # frozen_string_literal: true
 
+require_relative "../rational_to_integer"
+
 module Dicey
   module OutputFormatters
     # Base formatter for outputting lists of key-value pairs separated by newlines.
     # Can add an optional description into the result.
     # @abstract
     class KeyValueFormatter
+      include RationalToInteger
+
       # @param hash [Hash{Object => Object}]
       # @param description [String] text to add as a comment.
       # @return [String]
       def call(hash, description = nil)
         initial_string = description ? "# #{description}\n" : +""
         hash.each_with_object(initial_string) do |(key, value), output|
-          output << "#{key}#{self.class::SEPARATOR}#{value}\n"
+          output << line(transform(key, value)) << "\n"
         end
       end
+
+      private
+
+      def transform(key, value)
+        [rational_to_integer(key), rational_to_integer(value)]
+      end
+
+      def line((key, value))
+        "#{key}#{self.class::SEPARATOR}#{value}"
+      end
     end
   end
 end

data/lib/dicey/rational_to_integer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Dicey
+  # Mix-in for converting rationals with denominator of 1 to integers.
+  module RationalToInteger
+    # Convert +value+ to +Integer+ if it's a +Rational+ with denominator of 1.
+    # Otherwise, return +value+ as-is.
+    #
+    # @value [Numeric, Any]
+    # @return [Numeric, Integer, Any]
+    def rational_to_integer(value)
+      (Rational === value && value.denominator == 1) ? value.numerator : value
+    end
+  end
+end

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/roller.rb

@@ -2,9 +2,13 @@
 
 require_relative "die_foundry"
 
+require_relative "rational_to_integer"
+
 module Dicey
   # Let the dice roll!
   class Roller
+    include RationalToInteger
+
     # @param arguments [Array<String>] die definitions
     # @param format [#call] formatter for output
     # @return [nil]
@@ -15,7 +19,7 @@ module Dicey
       dice = arguments.flat_map { |definition| die_foundry.cast(definition) }
       result = dice.sum(&:roll)
 
-      format.call({ "roll" => result }, AbstractDie.describe(dice))
+      format.call({ "roll" => rational_to_integer(result) }, AbstractDie.describe(dice))
     end
 
     private

data/lib/dicey/sum_frequency_calculators/base_calculator.rb

@@ -1,8 +1,25 @@
 # frozen_string_literal: true
 
 module Dicey
+  # Calculators for probability distributions of dice.
   module SumFrequencyCalculators
     # Base frequencies calculator.
+    #
+    # *Result types:*
+    # - +:frequencies+ (default)
+    # - +:probabilities+
+    #
+    # By default, returns frequencies as they are easier to calculate and
+    # can be represented with integers.
+    # Probabilities are calculated using +Rational+ numbers to return exact results.
+    #
+    # *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 +27,12 @@ module Dicey
 
       # @param dice [Enumerable<AbstractDie>]
       # @param result_type [Symbol] one of {RESULT_TYPES}
-      # @return [Hash{Numeric => Numeric}] frequencies of each sum
+      # @param options [Hash{Symbol => Any}] calculator-specific options
+      # @return [Hash{Numeric => Numeric}] frequencies or probabilities for each outcome
       # @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 +40,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 +64,7 @@ module Dicey
 
       # Peform frequencies calculation.
       # (see #call)
-      def calculate(dice)
+      def calculate(dice, **nil)
         # :nocov:
         raise NotImplementedError
         # :nocov:
@@ -82,7 +100,7 @@ module Dicey
           frequencies
         else
           total = frequencies.values.sum
-          frequencies.transform_values { _1.fdiv(total) }
+          frequencies.transform_values { Rational(_1, total) }
         end
       end
     end

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 { Rational(_1 * total_results, 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.1"
 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.1
 platform: ruby
 authors:
 - Alexandr Bulancov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-11 00:00:00.000000000 Z
+date: 2025-10-07 00:00:00.000000000 Z
 dependencies: []
 description: |
   Dicey provides a CLI executable and a Ruby API for fast calculation of
@@ -35,6 +35,7 @@ files:
 - lib/dicey/cli/blender.rb
 - lib/dicey/cli/options.rb
 - lib/dicey/die_foundry.rb
+- lib/dicey/distribution_properties_calculator.rb
 - lib/dicey/numeric_die.rb
 - lib/dicey/output_formatters/gnuplot_formatter.rb
 - lib/dicey/output_formatters/hash_formatter.rb
@@ -42,10 +43,12 @@ files:
 - lib/dicey/output_formatters/key_value_formatter.rb
 - lib/dicey/output_formatters/list_formatter.rb
 - lib/dicey/output_formatters/yaml_formatter.rb
+- lib/dicey/rational_to_integer.rb
 - lib/dicey/regular_die.rb
 - 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 +60,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.1
+  source_code_uri: https://github.com/trinistr/dicey/tree/v0.15.1
+  changelog_uri: https://github.com/trinistr/dicey/blob/v0.15.1/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: