dicey 0.0.1 → 0.13.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13602eca86dfef1610dd824ffcab19809d7416418f077ea7b51f8f2fc713ec17
+  data.tar.gz: 7a24922897bad67486e72592189a51358bc861e53c332a0780901ef7ddf66e2f
+SHA512:
+  metadata.gz: 336cdbe4078db28e015ed393a65b358c9df13873b70da3f215cb75af95c84a67ae7ff6ec0939cd66c9f12b281e792d1acb9a0d00ec4e3f9c107b446e70cad703
+  data.tar.gz: 964b1502f92086c86b2861bd2eec432effec526b5aecbeb056f82a59cc2be83b1fe7fbe39482350d6764f994f432ebaef3f6e76b70f824adcc2cd630e9decaaf

data/README.md

@@ -0,0 +1,236 @@
+# Dicey
+
+> [!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.
+
+## 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.
+4. Click "**Run code**" button below the editor.
+
+## Installation
+
+Install via `gem`:
+```sh
+gem install dicey
+```
+
+Or, if using Bundler, add it to your `Gemfile`:
+```rb
+gem "dicey", "~> 0.13"
+```
+
+> [!TIP]
+> 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!
+
+### 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.
+
+## Usage
+
+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
+
+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
+$ dicey 4 4
+```
+
+It should output the following:
+```sh
+# ⚃;⚃
+2 => 1
+3 => 2
+4 => 3
+5 => 4
+6 => 3
+7 => 2
+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.
+
+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
+```
+
+This shows that 5 will probably be rolled a quarter of the time.
+
+### Example 2
+
+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
+# [8];⚃;⚃
+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
+```
+
+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?
+
+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
+```
+
+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 3
+
+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);⚃
+2 => 1
+3 => 2
+4 => 2
+5 => 3
+6 => 2
+7 => 1
+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.
+
+> [!TIP]
+> 💡 A single integer argument N practically is a shorthand for listing every side from 1 to N.
+
+### Example 4
+
+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.
+```
+
+> [!NOTE]
+> 💡 Roll mode is compatible with `--format`, but not `--result`.
+
+## 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.
+
+> [!TIP]
+> 💡 If you only need to roll **regular** dice, this section will not contain anything important.
+
+- **Natural** die has sides with only positive integers or 0. For example, (1,2,3,4,5,6), (5,1,6,5), (1,10000), (1,1,1,1,1,1,1,0).
+- **Arithmetic** die's sides form an arithmetic sequence. For example, (1,2,3,4,5,6), (1,0,-1), (2.6,2.1,1.6,1.1).
+- **Numeric** die is limited by having sides confined to ℝ (or ℂ if you are feeling particularly adventurous).
+- **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).
+
+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.
+
+Currently, three algorithms 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.
+
+### Kronecker substitution
+
+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)'`
+- Complexity: `O(m⋅n)` where `m` is the highest value
+
+### 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.
+
+- 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(m⋅n²)`
+
+### Brute force
+
+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, it has the largest input space, allowing to work with completely nonsensical dice, including aforementioned dice with complex numbers.
+
+- Limitations: objects on dice sides must be numbers.
+- Example: `dicey 5 1,0.1,2 1,-1,1,-1,0`
+- Complexity: `O(mⁿ)`
+
+## 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.
+
+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.
+
+To install this gem onto your local machine, run `rake install`.
+
+To release a new version, run `rake version:{major|minor|patch}`, and then run `rake release`, which will build the package and push the `.gem` file to [rubygems.org](https://rubygems.org). After that, push the release commit and tags to the repository with `git push --follow-tags`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/trinistr/dicey.
+
+### 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 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.
+- 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.
+
+## 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).

data/exe/dicey

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

data/exe/dicey-to-gnuplot

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Generate an image from dicey results.
+# Requires gnuplot to be installed and in PATH.
+# Usage: dicey 6 6 6 -f gnuplot | gnuplot-for-dicey
+
+require "tempfile"
+
+data = ARGF.read
+description = data[/(?<=\A# ).+$/] || "dice"
+Tempfile.create do |file|
+  file << data
+  file.flush
+  Process.wait(
+    Process.spawn(
+      "gnuplot",
+      "-e", "set term pngcairo size 1000,600",
+      "-e", %(set output "#{description}.png"),
+      "-e", "set boxwidth 0.9 relative",
+      "-e", "set style fill solid 0.5",
+      "-e", "plot [][0:] \"#{file.path}\" " \
+            "using 1:2:xticlabels(1) with boxes title \"#{description}\", " \
+            "'' using 1:2:2 with labels notitle"
+    )
+  )
+end

data/lib/dicey/abstract_die.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Dicey
+  # Asbtract die which may have an arbitrary list of sides,
+  # not even neccessarily numbers (but preferably so).
+  class AbstractDie
+    # rubocop:disable Style/ClassVars
+
+    # Get a random value using a private instance of Random.
+    # @see Random#rand
+    def self.rand(...)
+      @@random.rand(...)
+    end
+
+    # Reset internal randomizer using a new seed.
+    # @see Random.new
+    def self.srand(...)
+      @@random = Random.new(...)
+    end
+
+    # Yes, class variable is actually useful here.
+    # TODO: Allow supplying a custom Random.
+    @@random = Random.new
+
+    # rubocop:enable Style/ClassVars
+
+    # Get a text representation of a list of dice.
+    #
+    # @param dice [Enumerable<AbstractDie>]
+    # @return [String]
+    def self.describe(dice)
+      dice.join(";")
+    end
+
+    attr_reader :sides_list, :sides_num
+
+    # @param sides_list [Enumerable<Object>]
+    # @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
+      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
+    end
+
+    # Get current side of the die.
+    # @return [Object] current side
+    def current
+      @enum.peek
+    end
+
+    # Get next side of the die, advancing internal enumerator state.
+    # Wraps from last to first side.
+    # @return [Object] next side
+    def next
+      @enum.next
+    end
+
+    # Advance internal enumerator state by a random number using {#next}.
+    # @return [Object] rolled side
+    def roll
+      self.class.rand(0...sides_num).times { self.next }
+      current
+    end
+
+    # @return [String]
+    def to_s
+      "(#{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]
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(AbstractDie)
+
+      sides_list == other.sides_list
+    end
+  end
+end

data/lib/dicey/cli/blender.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+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
+      # List of calculators to use, ordered by efficiency.
+      ROLL_FREQUENCY_CALCULATORS = [
+        SumFrequencyCalculators::KroneckerSubstitution.new,
+        SumFrequencyCalculators::MultinomialCoefficients.new,
+        SumFrequencyCalculators::BruteForce.new,
+      ].freeze
+
+      # How to transform option values from command-line arguments
+      # to internally significant objects.
+      OPTION_TRANSFORMATIONS = {
+        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,
+        }.freeze,
+      }.freeze
+
+      # What to run for every mode.
+      # Every runner must respond to `call(arguments, **options)`
+      # and return +true+, +false+ or a String.
+      RUNNERS = {
+        roll: Roller.new,
+        frequencies: SumFrequencyCalculators::Runner.new,
+        test: SumFrequencyCalculators::TestRunner.new,
+      }.freeze
+
+      # Run the program, blending everything together.
+      #
+      # @param argv [Array<String>] arguments for the program
+      # @return [Boolean]
+      # @raise [DiceyError] anything can happen
+      def call(argv = ARGV)
+        options, arguments = get_options_and_arguments(argv)
+        require_optional_libraries(options)
+        options[:roll_calculators] = ROLL_FREQUENCY_CALCULATORS
+        return_value = RUNNERS[options.delete(:mode)].call(arguments, **options)
+        print return_value if return_value.is_a?(String)
+        !!return_value
+      end
+
+      private
+
+      def get_options_and_arguments(argv)
+        options = Options.new
+        arguments = options.read(argv)
+        options = options.to_h
+        options.each_pair do |k, v|
+          options[k] = OPTION_TRANSFORMATIONS[k][v] || v if OPTION_TRANSFORMATIONS[k]
+        end
+        [options, arguments]
+      end
+
+      # Require libraries only when needed, to cut on run time.
+      def require_optional_libraries(options)
+        case options[:format]
+        when OutputFormatters::YAMLFormatter
+          require "yaml"
+        when OutputFormatters::JSONFormatter
+          require "json"
+        else
+          # No additional libraries needed
+        end
+      end
+    end
+  end
+end

data/lib/dicey/cli/options.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Dicey
+  module CLI
+    # Helper class for parsing command-line options and generating help.
+    class Options
+      # Allowed modes (--mode) (only directly selectable).
+      MODES = %w[frequencies roll].freeze
+      # Allowed result types (--result).
+      RESULT_TYPES = %w[frequencies probabilities].freeze
+      # Allowed output formats (--format).
+      FORMATS = %w[list gnuplot json yaml].freeze
+
+      # Default values for initial values of the options.
+      DEFAULT_OPTIONS = { mode: "frequencies", format: "list", result: "frequencies" }.freeze
+
+      def initialize(initial_options = DEFAULT_OPTIONS.dup)
+        @options = initial_options
+        @parser = ::OptionParser.new
+        add_banner_and_version
+        add_common_options
+        add_test_options
+        add_other_options
+      end
+
+      # Parse command-line arguments as options and return non-option arguments.
+      #
+      # @param argv [Array<String>]
+      # @return [Array<String>] non-option arguments
+      def read(argv)
+        @parser.parse!(argv, into: @options)
+      end
+
+      # Get an option value by key.
+      #
+      # @param key [Symbol]
+      # @return [Object]
+      def [](key)
+        @options[key]
+      end
+
+      # @return [Hash{Symbol => Object}]
+      def to_h
+        @options.dup
+      end
+
+      private
+
+      def add_banner_and_version
+        @parser.banner = <<~TEXT
+          Usage: #{@parser.program_name} [options] <die> [<die> ...]
+                 #{@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
+        easy_option("-m", "--mode MODE", MODES, "What kind of action or calculation to perform.")
+        easy_option("-r", "--result RESULT_TYPE", RESULT_TYPES,
+                    "Select type of result to calculate (only for frequencies).")
+        easy_option("-f", "--format FORMAT", FORMATS, "Select output format for results.")
+      end
+
+      def add_test_options
+        @parser.on_tail(
+          "--test [REPORT_STYLE]", %w[full quiet],
+          "Check predefined calculation cases and exit.",
+          "REPORT_STYLE can be: `full`, `quiet`.", "`full` is default."
+        ) do |report_style|
+          @options[:mode] = :test
+          @options[:report_style] = report_style&.to_sym || :full
+        end
+      end
+
+      def add_other_options
+        @parser.on_tail("-h", "--help", "Show this help and exit.") do
+          puts @parser.help
+          exit
+        end
+        @parser.on_tail("-v", "--version", "Show program version and exit.") do
+          puts @parser.ver
+          exit
+        end
+      end
+
+      def easy_option(short, long, values, description, &)
+        values = values.keys if values.respond_to?(:keys)
+        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, &)
+      end
+    end
+  end
+end

data/lib/dicey/die_foundry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "numeric_die"
+require_relative "regular_die"
+
+module Dicey
+  # Helper class to define die definitions and automatically select the best one.
+  class DieFoundry
+    # Possible molds for the dice. They are matched in the order as written.
+    MOLDS = {
+      # Positive integer goes into the RegularDie mold.
+      ->(d) { /\A[1-9]\d*\z/.match?(d) } => :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,
+      # Anything else is spilled on the floor.
+      ->(*) { true } => :broken_mold,
+    }.freeze
+
+    # Regexp for removing brackets from lists.
+    BRACKET_STRIPPER = /\A\(?(.+)\)?\z/
+
+    # 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]
+    # @raise [DiceyError] if no mold fits the definition
+    def cast(definition)
+      _shape, mold = MOLDS.find { |shape, _mold| shape.call(definition) }
+      __send__(mold, definition)
+    end
+
+    private
+
+    def regular_mold(definition)
+      RegularDie.new(definition.to_i)
+    end
+
+    def weirdly_shaped_mold(definition)
+      definition = definition.match(BRACKET_STRIPPER)[1]
+      NumericDie.new(definition.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) })
+    end
+
+    def broken_mold(definition)
+      raise DiceyError, "can not cast die from `#{definition}`!"
+    end
+  end
+end

data/lib/dicey/numeric_die.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "abstract_die"
+
+module Dicey
+  # A die which only has numeric sides, with no shenanigans.
+  class NumericDie < AbstractDie
+    # @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)
+      end
+      super
+    end
+  end
+end

data/lib/dicey/output_formatters/gnuplot_formatter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "key_value_formatter"
+
+module Dicey
+  module OutputFormatters
+    # Formats a hash as a text file suitable for consumption by Gnuplot.
+    class GnuplotFormatter < KeyValueFormatter
+      SEPARATOR = " "
+    end
+  end
+end

data/lib/dicey/output_formatters/hash_formatter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Dicey
+  module OutputFormatters
+    # Base formatter for outputting in formats which can be converted from a Hash directly.
+    # Can add an optional description into the result.
+    # @abstract
+    class HashFormatter
+      # @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)
+        primitive?(value) ? value : value.to_s
+      end
+
+      def primitive?(value)
+        value.is_a?(Integer) || value.is_a?(Float) || value.is_a?(String)
+      end
+    end
+  end
+end

data/lib/dicey/output_formatters/json_formatter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "hash_formatter"
+
+module Dicey
+  module OutputFormatters
+    # Formats a hash as a JSON document under +results+ key, with optional +description+ key.
+    class JSONFormatter < HashFormatter
+      METHOD = :to_json
+    end
+  end
+end