rkoans 0.0.1 → 0.1.0

data/exercises/about-dice-project/about_dice_project.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: CC-BY-NC-SA-3.0
+# Adapted from Ruby Koans by Jim Weirich and Joe O'Brien.
+# See THIRD_PARTY_NOTICES.md for attribution and license terms.
+
+module Exercises
+  # A set of dice with stable values until the next roll.
+  class AboutDiceProject
+    # Stores the latest roll from an injectable random source.
+    class DiceSet
+      attr_reader :values
+
+      # @param random [Random] source of uniform six-sided die values
+      def initialize(random: Random.new)
+        @random = random
+        @values = []
+      end
+
+      # @param count [Integer] number of dice to roll
+      # @return [Array<Integer>] freshly rolled values
+      def roll(_count)
+        @values = []
+      end
+    end
+  end
+end

data/exercises/about-dice-project/brief.md

@@ -0,0 +1,12 @@
+# Dice Project
+
+Complete `Exercises::AboutDiceProject::DiceSet#roll(count)` in `about_dice_project.rb`.
+Replace `values` with exactly `count` integers from 1 through 6. Values must stay
+stable when read and only change when rolled. Zero dice produces an empty array.
+Use the random source supplied to the constructor and call `rand(1..6)` once
+per die. Normal use defaults to `Random.new`; checks supply a seeded source.
+
+Two genuinely random rolls can be equal. The checks therefore replay a known
+random stream instead of requiring successive rolls to differ.
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md`.

data/exercises/about-dice-project/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Build a fresh array on each roll and draw separately for each die. Do not draw when reading values.
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md`.

data/exercises/about-exceptions/about_exceptions.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: CC-BY-NC-SA-3.0
+# Adapted from Ruby Koans by Jim Weirich and Joe O'Brien.
+# See THIRD_PARTY_NOTICES.md for attribution and license terms.
+
+module Exercises
+  # Predictions for exceptions examples.
+  class AboutExceptions
+    # Replace each :fill_me_in with the result of the described expression.
+    # @return [Hash<Symbol, Object>]
+    # This method is an answer table, not a sequence of operations.
+    def self.koans
+      {
+        # Exceptions inherit from exception.
+        # assert_equal __, MySpecialError.ancestors[1]
+        # assert_equal __, MySpecialError.ancestors[2]
+        # assert_equal __, MySpecialError.ancestors[3]
+        # assert_equal __, MySpecialError.ancestors[4]
+        # Predict: MySpecialError.ancestors[1]
+        exceptions_inherit_from_Exception_one: :fill_me_in,
+        # Predict: MySpecialError.ancestors[2]
+        exceptions_inherit_from_Exception_two: :fill_me_in,
+        # Predict: MySpecialError.ancestors[3]
+        exceptions_inherit_from_Exception_three: :fill_me_in,
+        # Predict: MySpecialError.ancestors[4]
+        exceptions_inherit_from_Exception_four: :fill_me_in,
+        # Rescue clause.
+        # result = nil
+        # begin
+        # fail "Oops"
+        # rescue StandardError => ex
+        # result = :exception_handled
+        # end
+        # assert_equal __, result
+        # assert_equal __, ex.is_a?(StandardError), "Should be a Standard Error"
+        # assert_equal __, ex.is_a?(RuntimeError),  "Should be a Runtime Error"
+        # assert RuntimeError.ancestors.include?(StandardError),
+        # "RuntimeError is a subclass of StandardError"
+        # assert_equal __, ex.message
+        # Predict: result
+        rescue_clause_one: :fill_me_in,
+        # Predict: ex.is_a?(StandardError)
+        rescue_clause_two: :fill_me_in,
+        # Predict: ex.is_a?(RuntimeError)
+        rescue_clause_three: :fill_me_in,
+        # Predict: ex.message
+        rescue_clause_four: :fill_me_in,
+        # Raising a particular error.
+        # result = nil
+        # begin
+        # 'raise' and 'fail' are synonyms
+        # raise MySpecialError, "My Message"
+        # rescue MySpecialError => ex
+        # result = :exception_handled
+        # end
+        # assert_equal __, result
+        # assert_equal __, ex.message
+        # Predict: result
+        raising_a_particular_error_one: :fill_me_in,
+        # Predict: ex.message
+        raising_a_particular_error_two: :fill_me_in,
+        # Ensure clause.
+        # result = nil
+        # begin
+        # fail "Oops"
+        # rescue StandardError
+        # no code here
+        # ensure
+        # result = :always_run
+        # end
+        # assert_equal __, result
+        # Predict: result
+        ensure_clause_one: :fill_me_in,
+        # Asserting an error is raised.
+        # assert_raise(___) do
+        # raise MySpecialError.new("New instances can be raised directly.")
+        # end
+        # Predict: exception class from: raise MySpecialError.new("New instances can be raised directly.")
+        asserting_an_error_is_raised_one: :fill_me_in
+      }
+    end
+  end
+end

data/exercises/about-exceptions/brief.md

@@ -0,0 +1,19 @@
+# About Exceptions
+
+Replace each `:fill_me_in` in `about_exceptions.rb` with the predicted result.
+Each field identifies its example. Run the checks after edits to investigate the
+next prediction. Answers include the Ruby values and exception classes shown by
+the examples. Read the setup comments before evaluating an expression.
+
+## Example definitions
+
+These definitions supply the objects and methods used by the prediction examples.
+They run in the check class `AboutExceptionsTest`.
+
+```ruby
+class MySpecialError < RuntimeError
+  end
+```
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under
+CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md` for attribution and license terms.

data/exercises/about-exceptions/hint.md

@@ -0,0 +1,8 @@
+# Hint
+
+Follow the raised exception through rescue and ensure. Inspect its class,
+ancestors, and message. A rescue chooses compatible exception classes; ensure
+runs even after an exception is handled.
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under
+CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md` for attribution and license terms.

data/exercises/about-extra-credit/about_extra_credit.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: CC-BY-NC-SA-3.0
+# Adapted from Ruby Koans by Jim Weirich and Joe O'Brien.
+# See THIRD_PARTY_NOTICES.md for attribution and license terms.
+
+module Exercises
+  # A deterministic Greed game engine; callers supply rolls and decide when to bank.
+  class AboutExtraCredit
+    # Tracks one player and the entry threshold.
+    class Player
+      attr_reader :name, :score
+
+      # @param name [String] player name
+      def initialize(name)
+        @name = name
+        @score = 0
+      end
+
+      # Bank a turn once the player has entered with at least 300 points.
+      # @return [Integer] total score
+      # TODO: require 300 points to enter the game.
+      def bank(points)
+        @score += points
+        @score
+      end
+    end
+
+    # Coordinates turn order, banking, busts and the final round.
+    class Game
+      attr_reader :players, :current
+
+      # @param names [Array<String>] at least two players, in turn order
+      def initialize(names)
+        raise ArgumentError, 'at least two players required' if names.size < 2
+
+        @players = names.map { |name| Player.new(name) }
+        @current = 0
+        @remaining = nil
+      end
+
+      # Play the current player's complete turn; ending the rolls banks the points.
+      # @param rolls [Array<Array<Integer>>] ordered rolls, with legal remaining-dice counts
+      # @return [Integer] that player's total score after this turn
+      def play_turn(rolls)
+        raise 'game finished' if finished?
+
+        total = players[current].bank(turn_points(rolls))
+        advance(total)
+        total
+      end
+
+      # @return [Boolean] all other players have taken their final turn
+      def finished?
+        @remaining&.zero? || false
+      end
+
+      # @return [Player, nil] highest-scoring player after the final round; first in a tie
+      def winner
+        players.max_by(&:score) if finished?
+      end
+
+      private
+
+      # @return [Integer] accumulated turn points, or zero after a bust
+      def turn_points(rolls)
+        raise ArgumentError, 'a turn needs at least one roll' if rolls.empty?
+
+        points = 0
+        count = 5
+        rolls.each_with_index do |roll, index|
+          validate_roll(roll, count)
+          scored, unused = score_roll(roll)
+          if scored.zero?
+            raise ArgumentError, 'turn ends on a bust' unless index == rolls.size - 1
+
+            # TODO: a bust loses all points from this turn.
+            return points
+          end
+          points += scored
+          count = unused.zero? ? 5 : unused
+        end
+        points
+      end
+
+      # @return [void] reject malformed rolls before changing game state
+      def validate_roll(roll, count)
+        valid = roll.size == count && roll.all? { |face| face.is_a?(Integer) && (1..6).cover?(face) }
+        raise ArgumentError, 'invalid dice count or face' unless valid
+      end
+
+      # @return [Array<Integer>] points and the number of non-scoring dice
+      def score_roll(roll)
+        points = 0
+        unused = 0
+        roll.tally.each do |face, amount|
+          triples, singles = amount.divmod(3)
+          points += triples * (face == 1 ? 1000 : face * 100)
+          points += singles * { 1 => 100, 5 => 50 }.fetch(face, 0)
+          unused += singles unless [1, 5].include?(face)
+        end
+        [points, unused]
+      end
+
+      # Start the final round once, then give each remaining player exactly one turn.
+      def advance(total)
+        if @remaining
+          @remaining -= 1
+        elsif total >= 3000
+          # TODO: the other players still get a final turn.
+          @remaining = 0
+        end
+        @current = (current + 1) % players.size
+      end
+    end
+  end
+end

data/exercises/about-extra-credit/brief.md

@@ -0,0 +1,28 @@
+# Extra Credit
+
+The original extra-credit chapter proposes a free-form Greed game. This adaptation
+provides a deterministic engine to repair in `about_extra_credit.rb`; a terminal
+interface or computer player remains an optional extension.
+
+Fix the three incomplete rules in `Player#bank`, `Game#turn_points`, and
+`Game#advance`. Supplied scoring follows the scoring project: triples of ones
+are 1000, other triples are 100 times the face, remaining ones are 100 and
+fives are 50. Dice count once per roll.
+
+`Game.new(names)` requires at least two players. `play_turn(rolls)` accepts all
+rolls for the current player and returns their total score. The first roll uses
+five dice; later rolls use only non-scoring dice, or five again when all scored.
+Ending the supplied rolls means banking. A zero-point roll ends the turn and
+loses its accumulated points, preserving earlier banked totals. A player must
+first bank at least 300 in one turn; smaller turns count after entry.
+
+Reaching 3000 starts the final round: every other player gets exactly one more
+turn, even if someone overtakes the leader. `finished?` then becomes true and
+`winner` returns the highest-scoring Player (first in turn order on a tie).
+Reject further turns. Malformed rolls raise `ArgumentError` without advancing
+the game. Example: `[[1, 5, 2, 3, 4], [2, 2, 2]]` banks 350 points.
+
+Rolls are inputs so the game can be checked reproducibly. You can connect it to
+your DiceSet and a human or automated decision-maker as an optional extension.
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md`.

data/exercises/about-extra-credit/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Keep turn points separate from banked scores. Start a final-turn countdown only once; do not restart it when another player reaches 3000.
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md`.

data/exercises/about-hashes/about_hashes.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: CC-BY-NC-SA-3.0
+# Adapted from Ruby Koans by Jim Weirich and Joe O'Brien.
+# See THIRD_PARTY_NOTICES.md for attribution and license terms.
+
+module Exercises
+  # Predictions for hashes examples.
+  class AboutHashes
+    # Replace each :fill_me_in with the result of the described expression.
+    # @return [Hash<Symbol, Object>]
+    # This method is an answer table, not a sequence of operations.
+    def self.koans # rubocop:disable Metrics/MethodLength
+      {
+        # Creating hashes.
+        # empty_hash = Hash.new
+        # assert_equal __, empty_hash.class
+        # assert_equal(__, empty_hash)
+        # assert_equal __, empty_hash.size
+        # Predict: empty_hash.class
+        creating_hashes_one: :fill_me_in,
+        # Predict: empty_hash
+        creating_hashes_two: :fill_me_in,
+        # Predict: empty_hash.size
+        creating_hashes_three: :fill_me_in,
+        # Hash literals.
+        # hash = { :one => "uno", :two => "dos" }
+        # assert_equal __, hash.size
+        # Predict: hash.size
+        hash_literals_one: :fill_me_in,
+        # Accessing hashes.
+        # hash = { :one => "uno", :two => "dos" }
+        # assert_equal __, hash[:one]
+        # assert_equal __, hash[:two]
+        # assert_equal __, hash[:doesnt_exist]
+        # Predict: hash[:one]
+        accessing_hashes_one: :fill_me_in,
+        # Predict: hash[:two]
+        accessing_hashes_two: :fill_me_in,
+        # Predict: hash[:doesnt_exist]
+        accessing_hashes_three: :fill_me_in,
+        # Accessing hashes with fetch.
+        # hash = { :one => "uno" }
+        # assert_equal __, hash.fetch(:one)
+        # assert_raise(___) do
+        # hash.fetch(:doesnt_exist)
+        # end
+        # Predict: hash.fetch(:one)
+        accessing_hashes_with_fetch_one: :fill_me_in,
+        # Predict: exception class from: hash.fetch(:doesnt_exist)
+        accessing_hashes_with_fetch_two: :fill_me_in,
+        # Changing hashes.
+        # hash = { :one => "uno", :two => "dos" }
+        # hash[:one] = "eins"
+        # assert_equal __, hash
+        # Predict: hash
+        changing_hashes_one: :fill_me_in,
+        # Hash is unordered.
+        # hash1 = { :one => "uno", :two => "dos" }
+        # hash2 = { :two => "dos", :one => "uno" }
+        # assert_equal __, hash1 == hash2
+        # Predict: hash1 == hash2
+        hash_is_unordered_one: :fill_me_in,
+        # Hash keys.
+        # hash = { :one => "uno", :two => "dos" }
+        # assert_equal __, hash.keys.size
+        # assert_equal __, hash.keys.include?(:one)
+        # assert_equal __, hash.keys.include?(:two)
+        # assert_equal __, hash.keys.class
+        # Predict: hash.keys.size
+        hash_keys_one: :fill_me_in,
+        # Predict: hash.keys.include?(:one)
+        hash_keys_two: :fill_me_in,
+        # Predict: hash.keys.include?(:two)
+        hash_keys_three: :fill_me_in,
+        # Predict: hash.keys.class
+        hash_keys_four: :fill_me_in,
+        # Hash values.
+        # hash = { :one => "uno", :two => "dos" }
+        # assert_equal __, hash.values.size
+        # assert_equal __, hash.values.include?("uno")
+        # assert_equal __, hash.values.include?("dos")
+        # assert_equal __, hash.values.class
+        # Predict: hash.values.size
+        hash_values_one: :fill_me_in,
+        # Predict: hash.values.include?("uno")
+        hash_values_two: :fill_me_in,
+        # Predict: hash.values.include?("dos")
+        hash_values_three: :fill_me_in,
+        # Predict: hash.values.class
+        hash_values_four: :fill_me_in,
+        # Combining hashes.
+        # hash = { "jim" => 53, "amy" => 20, "dan" => 23 }
+        # new_hash = hash.merge({ "jim" => 54, "jenny" => 26 })
+        # assert_equal __, hash != new_hash
+        # expected = { "jim" => 54, "amy" => 20, "dan" => 23, "jenny" => 26 }
+        # assert_equal __, expected == new_hash
+        # Predict: hash != new_hash
+        combining_hashes_one: :fill_me_in,
+        # Predict: expected == new_hash
+        combining_hashes_two: :fill_me_in,
+        # Default value.
+        # hash1 = Hash.new
+        # hash1[:one] = 1
+        # assert_equal __, hash1[:one]
+        # assert_equal __, hash1[:two]
+        # hash2 = Hash.new("dos")
+        # hash2[:one] = 1
+        # assert_equal __, hash2[:one]
+        # assert_equal __, hash2[:two]
+        # Predict: hash1[:one]
+        default_value_one: :fill_me_in,
+        # Predict: hash1[:two]
+        default_value_two: :fill_me_in,
+        # Predict: hash2[:one]
+        default_value_three: :fill_me_in,
+        # Predict: hash2[:two]
+        default_value_four: :fill_me_in,
+        # Default value is the same object.
+        # hash = Hash.new([])
+        # hash[:one] << "uno"
+        # hash[:two] << "dos"
+        # assert_equal __, hash[:one]
+        # assert_equal __, hash[:two]
+        # assert_equal __, hash[:three]
+        # assert_equal __, hash[:one].equal?(hash[:two])
+        # Predict: hash[:one]
+        default_value_is_the_same_object_one: :fill_me_in,
+        # Predict: hash[:two]
+        default_value_is_the_same_object_two: :fill_me_in,
+        # Predict: hash[:three]
+        default_value_is_the_same_object_three: :fill_me_in,
+        # Predict: hash[:one].equal?(hash[:two])
+        default_value_is_the_same_object_four: :fill_me_in,
+        # Default value with block.
+        # hash = Hash.new {|hash, key| hash[key] = [] }
+        # hash[:one] << "uno"
+        # hash[:two] << "dos"
+        # assert_equal __, hash[:one]
+        # assert_equal __, hash[:two]
+        # assert_equal __, hash[:three]
+        # Predict: hash[:one]
+        default_value_with_block_one: :fill_me_in,
+        # Predict: hash[:two]
+        default_value_with_block_two: :fill_me_in,
+        # Predict: hash[:three]
+        default_value_with_block_three: :fill_me_in,
+        # Default value attribute.
+        # hash = Hash.new
+        # assert_equal __, hash[:some_key]
+        # hash.default = 'peanut'
+        # assert_equal __, hash[:some_key]
+        # Predict: hash[:some_key]
+        default_value_attribute_one: :fill_me_in,
+        # Predict: hash[:some_key]
+        default_value_attribute_two: :fill_me_in
+      }
+    end
+  end
+end

data/exercises/about-hashes/brief.md

@@ -0,0 +1,9 @@
+# About Hashes
+
+Replace each `:fill_me_in` in `about_hashes.rb` with the predicted result.
+Each field identifies its example. Run the checks after edits to investigate the
+next prediction. Answers include the Ruby values and exception classes shown by
+the examples. Read the setup comments before evaluating an expression.
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under
+CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md` for attribution and license terms.

data/exercises/about-hashes/hint.md

@@ -0,0 +1,8 @@
+# Hint
+
+Compare `hash[key]` with `hash.fetch(key)` for an absent key.
+A shared default object is reused; a default block can create and store a fresh
+value for each key. Merging returns a new hash; inspect both hashes afterward.
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under
+CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md` for attribution and license terms.

data/exercises/about-inheritance/about_inheritance.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: CC-BY-NC-SA-3.0
+# Adapted from Ruby Koans by Jim Weirich and Joe O'Brien.
+# See THIRD_PARTY_NOTICES.md for attribution and license terms.
+
+module Exercises
+  # Predictions for inheritance examples.
+  class AboutInheritance
+    # Replace each :fill_me_in with the result of the described expression.
+    # @return [Hash<Symbol, Object>]
+    # This method is an answer table, not a sequence of operations.
+    def self.koans
+      {
+        # Subclasses have the parent as an ancestor.
+        # assert_equal __, Chihuahua.ancestors.include?(Dog)
+        # Predict: Chihuahua.ancestors.include?(Dog)
+        subclasses_have_the_parent_as_an_ancestor_one: :fill_me_in,
+        # All classes ultimately inherit from object.
+        # assert_equal __, Chihuahua.ancestors.include?(Object)
+        # Predict: Chihuahua.ancestors.include?(Object)
+        all_classes_ultimately_inherit_from_object_one: :fill_me_in,
+        # Subclasses inherit behavior from parent class.
+        # chico = Chihuahua.new("Chico")
+        # assert_equal __, chico.name
+        # Predict: chico.name
+        subclasses_inherit_behavior_from_parent_class_one: :fill_me_in,
+        # Subclasses add new behavior.
+        # chico = Chihuahua.new("Chico")
+        # assert_equal __, chico.wag
+        # assert_raise(___) do
+        # fido = Dog.new("Fido")
+        # fido.wag
+        # end
+        # Predict: chico.wag
+        subclasses_add_new_behavior_one: :fill_me_in,
+        # Predict: exception class from: fido = Dog.new("Fido");       fido.wag
+        subclasses_add_new_behavior_two: :fill_me_in,
+        # Subclasses can modify existing behavior.
+        # chico = Chihuahua.new("Chico")
+        # assert_equal __, chico.bark
+        # fido = Dog.new("Fido")
+        # assert_equal __, fido.bark
+        # Predict: chico.bark
+        subclasses_can_modify_existing_behavior_one: :fill_me_in,
+        # Predict: fido.bark
+        subclasses_can_modify_existing_behavior_two: :fill_me_in,
+        # Subclasses can invoke parent behavior via super.
+        # ralph = BullDog.new("Ralph")
+        # assert_equal __, ralph.bark
+        # Predict: ralph.bark
+        subclasses_can_invoke_parent_behavior_via_super_one: :fill_me_in,
+        # Super does not work cross method.
+        # george = GreatDane.new("George")
+        # assert_raise(___) do
+        # george.growl
+        # end
+        # Predict: exception class from: george.growl
+        super_does_not_work_cross_method_one: :fill_me_in
+      }
+    end
+  end
+end

data/exercises/about-inheritance/brief.md

@@ -0,0 +1,50 @@
+# About Inheritance
+
+Replace each `:fill_me_in` in `about_inheritance.rb` with the predicted result.
+Each field identifies its example. Run the checks after edits to investigate the
+next prediction. Answers include the Ruby values and exception classes shown by
+the examples. Read the setup comments before evaluating an expression.
+
+## Example definitions
+
+These definitions supply the objects and methods used by the prediction examples.
+They run in the check class `AboutInheritanceTest`.
+
+```ruby
+class Dog
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+    end
+
+    def bark
+      "WOOF"
+    end
+  end
+
+class Chihuahua < Dog
+    def wag
+      :happy
+    end
+
+    def bark
+      "yip"
+    end
+  end
+
+class BullDog < Dog
+    def bark
+      super + ", GROWL"
+    end
+  end
+
+class GreatDane < Dog
+    def growl
+      super.bark + ", GROWL"
+    end
+  end
+```
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under
+CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md` for attribution and license terms.

data/exercises/about-inheritance/hint.md

@@ -0,0 +1,8 @@
+# Hint
+
+Look at the receiver class and its ancestors. `super` invokes the same method
+name further up the lookup chain; it does not search for a differently named
+method on the parent.
+
+Adapted from Ruby Koans by Jim Weirich and Joe O'Brien, licensed under
+CC BY-NC-SA 3.0. See `THIRD_PARTY_NOTICES.md` for attribution and license terms.