dicey 0.16.2 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5926d48370da981038bcc841fda2d3b1ea995d033f02f2373a097be5a510020a
-  data.tar.gz: 1692a73044f83c7fa8889b86f2ad812cb40e1f9faf26feb94522457872544108
+  metadata.gz: 44c61b75bbf67e966293a7f0f77eb1aef19add3f28989f2a04143fe12fdabfc8
+  data.tar.gz: 5d9c59008e82a2140ed01432f8e4d1e2dbc0e47e184c0fdc715cf3a77a8f4696
 SHA512:
-  metadata.gz: 35e956615ff78b7007a7333172181f0c6666f06a5ab61cf2355c7744f1cff92e01fe9f1ad877c62b853bda9789de02d0a9a76ea13404e2e7a9b2711b7dc6c3df
-  data.tar.gz: '0858e35f03ddd80ef754fde0276f33999124040fd499193c5f7eb2fe0c933c1c24677a2ea25e8ceea0259055469dd9076c6def50cde665267eb88386de8d7659'
+  metadata.gz: 2e54b27bc49ddb8586684ea4e9a71e5b7ec81b4436ee026c6aa5ab1340c72d92025bbb783bb8d754357c396debfc921e74cf4361fe0d5193c10f5c19f128279f
+  data.tar.gz: 7ae20ecc547a2a151bad2111b22ca323f68b0d09882b0b808c934551e1d36476fae7c265a549488179fcfb2db64f45cf8924a4306396c44c0eb2f05847710c6b

data/README.md

@@ -10,7 +10,7 @@
 
 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 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.
+In seriousness, this program is mainly useful for calculating distributions of weights (or probabilities) of all possible dice rolls for a given set of dice. Dice in such a set can be different, have arbitrary numbers, or even be non-numeric altogether. It can also be used to roll any dice that it supports.
 
 ## Table of contents
 
@@ -49,11 +49,11 @@ It does not provide quite all features, but it's easy to use and quick to get st
 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.
+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.
+If familiar with Ruby, you can also use **RunRuby** to explore the API. Refer to [Usage: API](#usage-api) section for documentation.
 
 ## Installation
 
@@ -117,7 +117,7 @@ It should output the following:
 8 => 1
 ```
 
-First line is a comment telling you that calculation ran for two D4s. Every line after that has the form `roll sum => frequency`, where frequency is the number of different rolls which result in this sum. As can be seen, 5 is the most common result with 4 possible different rolls.
+First line is a comment telling you that calculation ran for two D4s. Every line after that has the form `outcome => weight`, where weight is the number of distinct rolls which result in this outcome. As can be seen, 5 is the most common result with 4 possible different rolls.
 
 If probability is preferred, there is an option for that:
 ```sh
@@ -168,7 +168,7 @@ $ dicey 8 2d4 -f g | dicey-to-gnuplot
 ```
 
 This will create a PNG image named "*D8+D4+D4.png*":
-![Graph of damage roll frequencies for Burning Sword](D8+D4+D4.png)
+![Graph of damage roll weights for Burning Sword](D8+D4+D4.png)
 
 #### Example 2.2: JSON and YAML
 
@@ -217,7 +217,7 @@ $ dicey 1,2,4 4
 8 => 1
 ```
 
-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.
+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 weights to slightly dip in the middle. Good to know.
 
 But what if you had TWO weird D4s?
 ```sh
@@ -273,7 +273,7 @@ There are four *main* ways to define dice:
   - Lists can end in a comma, allowing single-number lists.
 - *"1,1.5,Two", "(💚,🧡,💙,💜)" or "('1','(bracket)')"*: a list of strings and numbers separated by commas, possibly in round brackets, makes an arbitrary die.
   - Lists can end in a comma, allowing single-string lists.
-  - Single (') or double (") quotes can be used to use other quotes and round brackets in the string. Otherwise, they are prohibited. Commas are always prohibited.
+  - Single (') or double (") quotes can be used to include other quotes and round brackets in the string. Otherwise, they are prohibited. Commas are always prohibited.
   - Quotes can also be used to treat numbers as strings.
 
 *"D6", "d(-1,3)", "d2..4", or "d💚,🧡"*: 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 "-".
@@ -384,26 +384,31 @@ die.roll
 
 ### Distribution calculators
 
-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` and more. It is very fast, though sometimes slower than the next one.
-- `Dicey::SumFrequencyCalculators::MultinomialCoefficients` is specialized for repeated numeric dice, with performance on par with the previous one, depending on exact parameters. However, it is currently limited to dice with arithmetic sequences (this includes regular dice, however).
-- `Dicey::SumFrequencyCalculators::BruteForce` is the most generic and slowest one, but can work with *any* dice. It needs gem "**vector_number**" to be installed and available to work with non-numeric dice.
-- `Dicey::SumFrequencyCalculators::Empirical`... this is more of a tool than a calculator. It "calculates" probabilities by performing a large number of rolls and counting frequencies of outcomes. It can be interesting to play around with and see how practical results compare to theoretical ones. Due to its simplicity, it also works with *any* dice.
+Distribution calculators live in `Dicey::DistributionCalculators` module. There are three main calculators currently.
+- `Dicey::DistributionCalculators::PolynomialConvolution` is the recommended calculator, able to handle all `Dicey::RegularDie` and other integer dice.
+- `Dicey::DistributionCalculators::MultinomialCoefficients` is specialized for repeated numeric dice. However, it is currently limited to dice with arithmetic sequences (this includes regular dice, however).
+- `Dicey::DistributionCalculators::Iterative` is the most generic, able to work with *abstract* dice. It needs gem "**vector_number**" to be installed and available to work with non-numeric dice.
 
-Calculators inherit from `Dicey::SumFrequencyCalculators::BaseCalculator` and provide the following public interface:
-- `#call(dice, result_type: {:frequencies | :probabilities}, **options) : Hash`
+Additionally, there are three special calculators.
+- `Dicey::DistributionCalculators::Binomial` is a fast calculator for collections of equal two-sided dice, like coins, including *abstract* dice.
+- `Dicey::DistributionCalculators::Empirical` is more of a tool than a calculator. It "calculates" probabilities by performing a large number of rolls and counting frequency of outcomes. It can be interesting to play around with and see how practical results compare to theoretical ones. Due to its simplicity, it also works with *abstract* dice.
+- `Dicey::DistributionCalculators::Trivial` is an extra-fast calculator for some trivial cases. There isn't much point in using it manually.
+
+When in doubt which calculator to use (and if a given one *can* be used), use `Dicey::DistributionCalculators::AutoSelector`. Its `.call(dice)` method will return a valid calculator for the given dice or `nil` if none are acceptable.
+
+Calculators inherit from `Dicey::DistributionCalculators::BaseCalculator` and provide the following public interface:
+- `#call(dice, result_type: {:weights | :probabilities}, **options) : Hash`
 - `#valid_for?(dice) : Boolean`
+- `#heuristic_complexity(dice) : Integer`
 
 See [Diving deeper](#diving-deeper) for more details on limitations and complexity considerations of different algorithms.
 
-When in doubt which calculator to use (and if a given one *can* be used), use `Dicey::SumFrequencyCalculators::AutoSelector`. Its `#call(dice)` method will return a valid calculator for the given dice or `nil` if none are acceptable.
-
 ### 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` provides this functionality:
 ```rb
 Dicey::DistributionPropertiesCalculator.new.call(
-  Dicey::SumFrequencyCalculators::KroneckerSubstitution.new.call(
+  Dicey::DistributionCalculators::PolynomialConvolution.new.call(
     Dicey::RegularDie.from_count(2, 3)
   )
 )
@@ -427,7 +432,7 @@ Dicey::DistributionPropertiesCalculator.new.call(
 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::DistributionCalculators::PolynomialConvolution.new.call(
     [Dicey::RegularDie.new(4), Dicey::NumericDie.new([1,3,4])]
   )
 )
@@ -460,7 +465,7 @@ You can see that 11 and 12 are the most likely outcomes, coming from a larger pe
 
 ## Diving deeper
 
-For a further discussion of calculations, it is important to understand which classes of dice exist.
+For a further discussion of calculations, it is important to understand which classes of dice are distinguished in **Dicey**.
 - **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]
@@ -474,45 +479,56 @@ For a further discussion of calculations, it is important to understand which cl
 > [!NOTE]
 > 💡 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 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 for calculating frequencies are implemented, with different possibilities and trade-offs.
+Currently, three algorithms for calculating distributions are implemented, with different possibilities and trade-offs.
 
 > [!NOTE]
 > 💡 Complexity is listed for **n** dice with at most **m** sides and is only an approximation.
 
-### Kronecker substitution
+### Polynomial convolution
 
-An algorithm based on fast polynomial multiplication. This is the default algorithm, used for most reasonable dice.
+An algorithm based on fast polynomial multiplication. This is the algorithm which probably will be used by auto-selector for most reasonable dice.
 
 - Limitations: only **integer** dice are allowed, including **regular** dice.
 - Example: `dicey 5 3,4,1 0,`
 - Complexity: **O(n<sup>3</sup>⋅m<sup>2</sup>)**
 - Running time examples:
   - 6d1000 — 0.5 seconds
-  - 1000d6 — 18 seconds
+  - 1000d6 — 20 seconds
 
 ### Multinomial coefficients
 
-This algorithm is based on raising a univariate polynomial to a power and using the coefficients of the result, though certain restrictions are lifted as they don't actually matter for the calculation. It is usually faster than Kronecker substitution for many dice with few sides.
+This algorithm is based on raising a univariate polynomial to a power and using the coefficients of the result, though certain restrictions are lifted as they don't actually matter for the calculation. It is usually faster than polynomial convolution for many dice with few sides.
 
 - Limitations: only *equal* **arithmetic** dice are allowed.
 - Example: `dicey 1.5,3,4.5,6 1.5,3,4.5,6 1.5,3,4.5,6`
 - Complexity: **O(n<sup>2</sup>⋅m<sup>2</sup>)**
 - Running time examples:
-  - 6d1000 — 1.65 seconds
-  - 1000d6 — 10.5 seconds
+  - 6d1000 — 1.5 seconds
+  - 1000d6 — 10 seconds
 
-### Brute force
+### Binomial
 
-As a last resort, there is a brute force algorithm which goes through every possible dice roll and adds results together. While quickly growing terrible in performace (and memory usage), it has the largest input space, allowing to work with completely nonsensical dice, including complex numbers and altogether non-numeric values.
+This is a specialized alogorithm for coin-like dice of any kind. It is significantly faster than general algorithms.
+
+- Limitations: only *equal* two-sided dice are allowed, **vector_number** allows non-numeric values.
+- Example: `dicey 500d2`
+- Complexity: **O(n<sup>2</sup>)**
+- Running time examples:
+  - 1000d2 — 0.125 seconds
+  - 10000d2 — 3.5 seconds
+
+### Iterative
+
+At last, there is an iterative algorithm which goes through every possible dice roll and adds results together. Whil being inefficient, it has the largest input space, allowing to work with completely nonsensical dice, including complex numbers and altogether non-numeric values.
 
 - Limitations: without **vector_number** all values must be numbers, otherwise almost any values are viable.
 - Example: `dicey 5 1,0.1,2 A,B,C`
-- Complexity: **O(m<sup>n</sup>)**
+- Complexity: **O(n<sup>2</sup>⋅m<sup>2</sup>)**
 - Running time examples:
-  - 6d10 — 0.25 seconds
-  - 10d6 — 9.5 seconds
+  - 6d1000 — 2.5 seconds
+  - 1000d6 — 20 seconds
+  - 10d(a,b,c,d,e,f) — 0.5 seconds
+  - 10d(a,b,c,d,e,f,g,h,i,j) — 15 seconds
 
 ## Development
 
@@ -540,4 +556,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/trinis
 
 ## License
 
-This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT), see [LICENSE.txt](https://github.com/trinistr/dicey/blob/main/LICENSE.txt).
+This gem is available as open source under the terms of the MIT License, see [LICENSE.txt](https://github.com/trinistr/dicey/blob/main/LICENSE.txt).

data/exe/dicey

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "dicey/cli/blender"
+require "dicey/cli"
 
-exit Dicey::CLI::Blender.new.call
+exit Dicey::CLI.call

data/lib/dicey/abstract_die.rb

@@ -3,11 +3,29 @@
 module Dicey
   # Asbtract die which may have an arbitrary list of sides,
   # not even neccessarily numbers but strings or other objects.
+  #
+  # As the base class for all dice, defines their API.
+  #
+  # Dice can be created through several methods:
+  # - basic +.new+ ({#initialize}), creating one die from an appropriate definition;
+  # - {.from_list}, creating an array of dice from a list of definitions;
+  # - {.from_count}, creating a number of equal dice from one definition.
+  #
+  # Rolling a die is done through {#roll}. {#current} returns the current side of the die.
+  #
+  # {.srand} can be used to (re)set the internal randomizer's state for all dice,
+  # allowing to reproduce the same sequence of rolls (if it was done with a known state).
   class AbstractDie
+    # Yes, class variable is actually useful here.
+    # TODO: Allow supplying a custom Random.
     # rubocop:disable Style/ClassVars
 
     # @api private
     # Get a random value using a private instance of Random.
+    #
+    # Do not use this method directly.
+    # Reproducible rolls depend on it being called only internally.
+    #
     # @see Random#rand
     def self.rand(...)
       @@random.rand(...)
@@ -19,9 +37,6 @@ module Dicey
       @@random = Random.new(...)
     end
 
-    # Yes, class variable is actually useful here.
-    # TODO: Allow supplying a custom Random.
-
     # Shared randomness source, accessed through {.rand} and {.srand}.
     @@random = Random.new
 
@@ -37,7 +52,7 @@ module Dicey
       dice.to_a.join("+")
     end
 
-    # Create a bunch of different dice at once.
+    # Create a bunch of different dice at once from a list of definitions.
     #
     # @param definitions [Array<Enumerable<Any>>, Array<Any>]
     #   list of definitions suitable for the dice class
@@ -46,7 +61,7 @@ module Dicey
       definitions.map { new(_1) }
     end
 
-    # Create a number of equal dice.
+    # Create a number of equal dice from one definition.
     #
     # @param count [Integer] number of dice to create
     # @param definition [Enumerable<Any>, Any]
@@ -115,6 +130,8 @@ module Dicey
     # Determine if this die and the other one have the same list of sides.
     # Be aware that differently ordered sides are not considered equal.
     #
+    # @see #eql?
+    #
     # @param other [AbstractDie, Any]
     # @return [Boolean]
     def ==(other)
@@ -127,6 +144,8 @@ module Dicey
     #
     # +die_1.eql?(die_2)+ implies +die_1.hash == die_2.hash+.
     #
+    # @see #hash
+    #
     # @param other [AbstractDie, Any]
     # @return [Boolean]
     def eql?(other)

data/lib/dicey/cli/blender.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "../../dicey"
+
+require_relative "options"
+
+require_relative "calculator_runner"
+require_relative "calculator_test_runner"
+require_relative "roller"
+
+Dir["formatters/*.rb", base: __dir__].each { require_relative _1 }
+
 module Dicey
-  # Classes pertaining to CLI.
-  # NOT loaded by default, use +require "dicey/cli/blender"+ as needed.
   module CLI
-    require_relative "../../dicey"
-    require_relative "options"
-
     # Slice and dice everything in the Dicey module to produce a useful result.
     # This is the entry point for the CLI.
     class Blender
@@ -16,11 +21,11 @@ module Dicey
         mode: lambda(&:to_sym),
         result: lambda(&:to_sym),
         format: {
-          "list" => OutputFormatters::ListFormatter.new,
-          "gnuplot" => OutputFormatters::GnuplotFormatter.new,
-          "yaml" => OutputFormatters::YAMLFormatter.new,
-          "json" => OutputFormatters::JSONFormatter.new,
-          "null" => OutputFormatters::NullFormatter.new,
+          "list" => Formatters::ListFormatter.new,
+          "gnuplot" => Formatters::GnuplotFormatter.new,
+          "yaml" => Formatters::YAMLFormatter.new,
+          "json" => Formatters::JSONFormatter.new,
+          "null" => Formatters::NullFormatter.new,
         }.freeze,
       }.freeze
 
@@ -29,8 +34,8 @@ module Dicey
       # and return +true+, +false+ or a String.
       RUNNERS = {
         roll: Roller.new,
-        frequencies: SumFrequencyCalculators::Runner.new,
-        test: SumFrequencyCalculators::TestRunner.new,
+        distribution: CLI::CalculatorRunner.new,
+        test: CLI::CalculatorTestRunner.new,
       }.freeze
 
       # Run the program, blending everything together.
@@ -61,9 +66,9 @@ module Dicey
       # Require libraries only when needed, to cut on run time.
       def require_optional_libraries(options)
         case options[:format]
-        when OutputFormatters::YAMLFormatter
+        when Formatters::YAMLFormatter
           require "yaml"
-        when OutputFormatters::JSONFormatter
+        when Formatters::JSONFormatter
           require "json"
         else
           # No additional libraries needed

data/lib/dicey/{sum_frequency_calculators/runner.rb → cli/calculator_runner.rb}

@@ -2,31 +2,29 @@
 
 require_relative "../die_foundry"
 
-require_relative "brute_force"
-require_relative "kronecker_substitution"
-require_relative "multinomial_coefficients"
+Dir["../distribution_calculators/*.rb", base: __dir__].each { require_relative _1 }
 
 module Dicey
-  module SumFrequencyCalculators
-    # The defaultest runner which calculates roll frequencies from command-line dice.
-    class Runner
-      # Transform die definitions to roll frequencies.
+  module CLI
+    # The defaultest runner which calculates roll distribution from command-line dice.
+    class CalculatorRunner
+      # Transform die definitions to roll distribution.
       #
       # @param arguments [Array<String>] die definitions
       # @param format [#call] formatter for output
       # @param result [Symbol] result type selector
-      # @return [nil]
+      # @return [String]
       # @raise [DiceyError]
       def call(arguments, format:, result:, **)
         raise DiceyError, "no dice!" if arguments.empty?
 
         dice = arguments.flat_map { |definition| die_foundry.cast(definition) }
-        calculator = calculator_selector.call(dice)
+        calculator = DistributionCalculators::AutoSelector.call(dice)
         raise DiceyError, "no calculator could handle these dice!" unless calculator
 
-        frequencies = calculator.call(dice, result_type: result)
+        distribution = calculator.call(dice, result_type: result)
 
-        format.call(frequencies, AbstractDie.describe(dice))
+        format.call(distribution, AbstractDie.describe(dice))
       end
 
       private
@@ -34,10 +32,6 @@ module Dicey
       def die_foundry
         @die_foundry ||= DieFoundry.new
       end
-
-      def calculator_selector
-        @calculator_selector ||= AutoSelector.new
-      end
     end
   end
 end

data/lib/dicey/{sum_frequency_calculators/test_runner.rb → cli/calculator_test_runner.rb}

@@ -1,17 +1,14 @@
 # frozen_string_literal: true
 
-require_relative "auto_selector"
-require_relative "brute_force"
-require_relative "kronecker_substitution"
-require_relative "multinomial_coefficients"
+Dir["../distribution_calculators/*.rb", base: __dir__].each { require_relative _1 }
 
 module Dicey
-  module SumFrequencyCalculators
-    # A simple testing facility for roll frequency calculators.
-    class TestRunner
-      AVAILABLE_CALCULATORS = AutoSelector::AVAILABLE_CALCULATORS
+  module CLI
+    # A simple testing facility for roll distribution calculators.
+    class CalculatorTestRunner
+      AVAILABLE_CALCULATORS = DistributionCalculators::AutoSelector::AVAILABLE_CALCULATORS
 
-      # These are manually calculated frequencies,
+      # These are manually calculated weights,
       # with test cases for pretty much all variations of what this program can handle.
       TEST_DATA = [
         [[1], { 1 => 1 }],
@@ -78,7 +75,7 @@ module Dicey
       # @return [Boolean] whether there are no failing tests
       def call(*, report_style:, **)
         results = TEST_DATA.to_h { |test| run_test(test) }
-        full_report(results) if report_style == :full
+        output_report(results, report_style)
         results.values.none? do |test_result|
           test_result.values.any? { FAILURE_RESULTS.include?(_1) }
         end
@@ -88,7 +85,7 @@ module Dicey
 
       # @param test [Array(Array<Integer, Array<Numeric>>, Hash{Numeric => Integer})]
       #   pair of a dice list definition and expected results
-      # @return [Array(Array<NumericDie>, Hash{BaseCalculator => Symbol})]
+      # @return [Array(Array<AbstractDie>, Hash{BaseCalculator => Symbol})]
       #   result of running the test in a format suitable for +#to_h+
       def run_test(test)
         dice = build_dice(test.first)
@@ -99,10 +96,10 @@ module Dicey
         [dice, test_result]
       end
 
-      # Build a list of {NumericDie} objects from a plain definition.
+      # Build a list of dice from a plain definition.
       #
       # @param definition [Array<Integer, Array<Integer>>]
-      # @return [Array<NumericDie>]
+      # @return [Array<AbstractDie>]
       def build_dice(definition)
         definition.map do |die_def|
           if die_def.is_a?(Integer)
@@ -124,6 +121,15 @@ module Dicey
         :crash
       end
 
+      # Output report based on the results.
+      def output_report(results, report_style)
+        if report_style == :full
+          full_report(results)
+        elsif report_style == :short
+          short_report(results)
+        end
+      end
+
       # Print results of running all tests.
       def full_report(results)
         results.each do |dice, test_result|
@@ -134,6 +140,24 @@ module Dicey
           end
         end
       end
+
+      # Print only failing results of running tests.
+      def short_report(results)
+        results.each do |dice, test_result|
+          print "#{AbstractDie.describe(dice)}:"
+          if test_result.values.any? { FAILURE_RESULTS.include?(_1) }
+            puts
+            test_result.each do |calculator, result|
+              next unless FAILURE_RESULTS.include?(result)
+
+              print "  #{calculator.class}: "
+              puts RESULT_TEXT[result]
+            end
+          else
+            print " ", RESULT_TEXT[:pass], "\n"
+          end
+        end
+      end
     end
   end
 end

data/lib/dicey/cli/formatters/base_list_formatter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../../mixins/rational_to_integer"
+
+module Dicey
+  module CLI
+    module Formatters
+      # Base formatter for outputting lists of key-value pairs separated by newlines.
+      # Can add an optional description into the result.
+      # @abstract
+      class BaseListFormatter
+        include Mixins::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 << 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
+end

data/lib/dicey/cli/formatters/base_map_formatter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Dicey
+  module CLI
+    # Processors which turn data to text.
+    module Formatters
+      # Base formatter for outputting in formats which are map- (or object-) like.
+      # Can add an optional description into the result.
+      # @abstract
+      class BaseMapFormatter
+        # @param hash [Hash{Object => Object}]
+        # @param description [String] text to add to result as an extra key
+        # @return [String]
+        def call(hash, description = nil)
+          hash = hash.transform_keys { to_primitive(_1) }
+          hash.transform_values! { to_primitive(_1) }
+          output = {}
+          output["description"] = description if description
+          output["results"] = hash
+          output.public_send(self.class::METHOD)
+        end
+
+        private
+
+        def to_primitive(value)
+          return value if primitive?(value)
+          return value.to_f if Numeric === value
+
+          value.to_s
+        end
+
+        def primitive?(value)
+          value.is_a?(Integer) || value.is_a?(Float) || value.is_a?(String)
+        end
+      end
+    end
+  end
+end

data/lib/dicey/cli/formatters/gnuplot_formatter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base_list_formatter"
+
+module Dicey
+  module CLI
+    module Formatters
+      # Formats a hash as a text file suitable for consumption by Gnuplot.
+      #
+      # Will transform Rational probabilities to Floats.
+      # Non-numeric dice inherently won't work in gnuplot,
+      # even though the formatter will process them.
+      class GnuplotFormatter < BaseListFormatter
+        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
+end

data/lib/dicey/cli/formatters/json_formatter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base_map_formatter"
+
+module Dicey
+  module CLI
+    module Formatters
+      # Formats a hash as a JSON document under +results+ key, with optional +description+ key.
+      class JSONFormatter < BaseMapFormatter
+        METHOD = :to_json
+      end
+    end
+  end
+end

data/lib/dicey/cli/formatters/list_formatter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base_list_formatter"
+
+module Dicey
+  module CLI
+    module Formatters
+      # Formats a hash as list of key => value pairs, similar to a Ruby Hash.
+      class ListFormatter < BaseListFormatter
+        SEPARATOR = " => "
+      end
+    end
+  end
+end

data/lib/dicey/cli/formatters/null_formatter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dicey
+  module CLI
+    module Formatters
+      # Formatter that doesn't format anything and always returns an empty string.
+      class NullFormatter
+        # @param hash [Hash{Object => Object}]
+        # @param description [String] text to add as a comment.
+        # @return [String] always an empty string
+        def call(hash, description = nil) # rubocop:disable Lint/UnusedMethodArgument
+          ""
+        end
+      end
+    end
+  end
+end