rkoans 0.0.1 → 0.1.0

data/exercises/about-symbols/brief.md

@@ -0,0 +1,21 @@
+# Symbols: names, values, and identity
+
+Replace each `:fill_me_in` prediction with the result of its commented example.
+Use `true` or `false` for comparisons, symbols or strings for converted values,
+and an exception class for the unsupported concatenation example.
+
+Compare the value and identity of two symbols with the same name. Convert a
+string to a symbol, try quoted names containing spaces, and observe interpolation.
+A symbol is a different type from a string, even when they have the same spelling.
+
+The checks define a constant named `RUBY_CONSTANT` and a method named
+`test_method_names_become_symbols`. Predict whether their names occur in
+`Symbol.all_symbols`. Compare strings when searching: creating a new symbol for
+the expected name would change the table being observed.
+
+For `concatenation_error`, predict the class of the exception raised by
+`:cats + :dogs`, rather than an exception instance. Save a group of predictions
+at a time and compare Expected (your prediction) with Actual (Ruby's result).
+
+Adapted from **Ruby Koans: About Symbols** by Jim Weirich and Joe O'Brien.
+Licensed under [CC BY-NC-SA 3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/).

data/exercises/about-symbols/hint.md

@@ -0,0 +1,12 @@
+# Hint: a symbol is a name, not a string
+
+Identical symbol names refer to the same symbol object. `to_sym` converts a
+string into a symbol, while interpolation uses `to_s` to insert text.
+
+Use `respond_to?` to explore a proposed string operation. If an operation is
+unsupported, Ruby's failure names the exception class; compare that class with
+your prediction. Constant and method names already declared by the checks are
+present in the symbol table.
+
+Adapted from **Ruby Koans: About Symbols** by Jim Weirich and Joe O'Brien.
+Licensed under [CC BY-NC-SA 3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/).

data/exercises/about-to-str/about_to_str.rb

@@ -0,0 +1,49 @@
+# 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 to str examples.
+  class AboutToStr
+    # 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
+      {
+        # To s returns a string representation.
+        # not_like_a_string = CanNotBeTreatedAsString.new
+        # assert_equal __, not_like_a_string.to_s
+        # Predict: not_like_a_string.to_s
+        to_s_returns_a_string_representation_one: :fill_me_in,
+        # Normally objects cannot be used where strings are expected.
+        # assert_raise(___) do
+        # File.exist?(CanNotBeTreatedAsString.new)
+        # end
+        # Predict: exception class from: File.exist?(CanNotBeTreatedAsString.new)
+        normally_objects_cannot_be_used_where_strings_are_expected_one: :fill_me_in,
+        # To str also returns a string representation.
+        # like_a_string = CanBeTreatedAsString.new
+        # assert_equal __, like_a_string.to_str
+        # Predict: like_a_string.to_str
+        to_str_also_returns_a_string_representation_one: :fill_me_in,
+        # To str allows objects to be treated as strings.
+        # Dir.mktmpdir do |directory|
+        # Dir.chdir(directory) do
+        # assert_equal __, File.exist?(CanBeTreatedAsString.new)
+        # end
+        # end
+        # Predict: File.exist?(CanBeTreatedAsString.new)
+        to_str_allows_objects_to_be_treated_as_strings_one: :fill_me_in,
+        # User defined code can check for to str.
+        # assert_equal __, acts_like_a_string?(CanNotBeTreatedAsString.new)
+        # assert_equal __,  acts_like_a_string?(CanBeTreatedAsString.new)
+        # Predict: acts_like_a_string?(CanNotBeTreatedAsString.new)
+        user_defined_code_can_check_for_to_str_one: :fill_me_in,
+        # Predict: acts_like_a_string?(CanBeTreatedAsString.new)
+        user_defined_code_can_check_for_to_str_two: :fill_me_in
+      }
+    end
+  end
+end

data/exercises/about-to-str/brief.md

@@ -0,0 +1,37 @@
+# About To Str
+
+Replace each `:fill_me_in` in `about_to_str.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 `AboutToStrTest`.
+
+```ruby
+class CanNotBeTreatedAsString
+    def to_s
+      "non-string-like"
+    end
+  end
+
+class CanBeTreatedAsString
+    def to_s
+      "string-like"
+    end
+
+    def to_str
+      to_s
+    end
+  end
+
+def acts_like_a_string?(string)
+    string = string.to_str if string.respond_to?(:to_str)
+    string.is_a?(String)
+  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-to-str/hint.md

@@ -0,0 +1,7 @@
+# Hint
+
+`to_s` gives an explicit representation. `to_str` opts an object into
+implicit string conversion. An object may implement one without the other.
+
+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-triangle-project/about_triangle_project.rb

@@ -0,0 +1,15 @@
+# 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
+  # Classifies triangles by the number of equal sides.
+  class AboutTriangleProject
+    # @return [Symbol] :equilateral, :isosceles, or :scalene for valid side lengths
+    def self.triangle(_side_a, _side_b, _side_c)
+      :fill_me_in
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# Triangle Project
+
+Implement `Exercises::AboutTriangleProject.triangle(a, b, c)` in `about_triangle_project.rb`.
+Return `:equilateral` for three equal sides, `:isosceles` for exactly two equal
+sides, and `:scalene` otherwise. This first project accepts valid triangles;
+handling invalid lengths comes after the exceptions lesson.
+
+Run `rkoans check` after editing. Each project is self-contained; it does not
+read or overwrite another exercise's learner file.
+
+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-triangle-project/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Compare the number of distinct side lengths. Check every position of an equal pair.
+
+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-triangle-project-two/about_triangle_project_two.rb

@@ -0,0 +1,22 @@
+# 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
+  # Adds exception handling to triangle classification.
+  class AboutTriangleProjectTwo
+    class TriangleError < StandardError; end
+
+    # @raise [TriangleError] nonpositive or degenerate side lengths
+    # @return [Symbol] triangle classification
+    def self.triangle(side_a, side_b, side_c)
+      case [side_a, side_b, side_c].uniq.size
+      when 1 then :equilateral
+      when 2 then :isosceles
+      else :scalene
+      end
+    end
+  end
+end

data/exercises/about-triangle-project-two/brief.md

@@ -0,0 +1,10 @@
+# Triangle Project Two
+
+Add validation to `Exercises::AboutTriangleProjectTwo.triangle` in
+`about_triangle_project_two.rb`. Raise its nested `TriangleError` if any side
+is zero or negative, or if two sides together are no longer than the third.
+Retain the three valid classifications from part one. Numeric side lengths
+may include fractions. A starting classifier is supplied here so this lesson
+works independently of your saved part-one solution.
+
+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-triangle-project-two/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Sort the sides before comparing the longest with the sum of the other two. Equality is invalid too.
+
+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-true-and-false/about_true_and_false.rb

@@ -0,0 +1,26 @@
+# 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
+  # Predicts the branch taken by Ruby's conditionals for common values.
+  class AboutTrueAndFalse
+    # Replace each nil with :true_stuff or :false_stuff.
+    # @return [Hash<Symbol, Symbol | nil>] expected branch labels for each input
+    def self.koans
+      {
+        true_value: nil,
+        false_value: nil,
+        nil_value: nil,
+        one: nil,
+        zero: nil,
+        empty_array: nil,
+        empty_hash: nil,
+        string: nil,
+        empty_string: nil
+      }
+    end
+  end
+end

data/exercises/about-true-and-false/brief.md

@@ -0,0 +1,22 @@
+# True, false, and everything else
+
+An `if` statement chooses a branch based on its condition:
+
+```ruby
+if condition
+  :true_stuff
+else
+  :false_stuff
+end
+```
+
+Fill each answer in `koans` with `:true_stuff` or `:false_stuff`, predicting the
+branch for `true`, `false`, `nil`, `1`, `0`, `[]`, `{}`, `"Strings"`, and `""`.
+The answer names match these inputs in order. The colon creates a symbol, which
+we use here as a branch label.
+
+Pay particular attention to zero and empty collections. Do they behave like
+false? Save one prediction at a time and read the failing check's message.
+
+Adapted from **Ruby Koans: About True and False** by Jim Weirich and Joe O'Brien.
+Licensed under [CC BY-NC-SA 3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/).

data/exercises/about-true-and-false/hint.md

@@ -0,0 +1,7 @@
+# Hint: only two falsey values
+
+Ruby treats only `false` and `nil` as falsey. Zero, empty strings, empty arrays,
+and empty hashes are truthy. Choose the branch label for each input.
+
+Adapted from **Ruby Koans: About True and False** by Jim Weirich and Joe O'Brien.
+Licensed under [CC BY-NC-SA 3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/).

data/exercises/blocks-and-methods/blocks_and_methods.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Fill the expectation and implement the block invocation below.
+  class BlocksAndMethods
+    def self.koans
+      { sequence: nil }
+    end
+
+    def self.apply(value)
+      value
+    end
+  end
+end

data/exercises/blocks-and-methods/brief.md

@@ -0,0 +1,8 @@
+# Who calls the block?
+
+The expression `3.times.map { |i| i + 1 }` returns three values.
+Fill `koans[:sequence]`. Implement `apply(value)` to call the supplied block
+once and return its result. For `apply(5) { |n| n * 3 }`, return 15.
+Calling without a block should raise `LocalJumpError`.
+
+Save your file to rerun the checks automatically.

data/exercises/blocks-and-methods/hint.md

@@ -0,0 +1,6 @@
+# Hint: calling a block
+
+A block is behavior supplied by the caller, not an ordinary positional argument.
+Ruby's `yield` invokes the block and returns its result.
+
+For the expectation blank, work through the three values of `i` in `3.times`.

data/exercises/catalog.json

@@ -0,0 +1,61 @@
+[
+  "about-asserts",
+  "about-true-and-false",
+  "about-strings",
+  "heredoc-layout",
+  "about-symbols",
+  "about-arrays",
+  "about-array-assignment",
+  "shared-rows",
+  "about-objects",
+  "about-nil",
+  "about-hashes",
+  "literals-and-operators",
+  "about-methods",
+  "numeric-precision",
+  "about-keyword-arguments",
+  "about-constants",
+  "about-regular-expressions",
+  "regexp-captures",
+  "about-control-statements",
+  "about-pattern-matching",
+  "pattern-matching",
+  "about-triangle-project",
+  "about-exceptions",
+  "exception-flow",
+  "about-triangle-project-two",
+  "about-iteration",
+  "about-blocks",
+  "collection-basics",
+  "blocks-and-methods",
+  "numbered-parameters",
+  "lazy-enumeration",
+  "closure-capture",
+  "nonlocal-exit",
+  "method-contracts",
+  "keyword-forwarding",
+  "about-sandwich-code",
+  "about-scoring-project",
+  "about-classes",
+  "visibility",
+  "about-open-classes",
+  "about-dice-project",
+  "about-inheritance",
+  "class-state",
+  "about-modules",
+  "core-protocols",
+  "about-scope",
+  "constant-scope",
+  "about-class-methods",
+  "singleton-pattern",
+  "method-lookup",
+  "about-message-passing",
+  "delegation",
+  "about-proxy-object-project",
+  "dynamic-methods",
+  "about-to-str",
+  "refinement-scope",
+  "time-and-date",
+  "runtime-context",
+  "about-extra-credit"
+]

data/exercises/class-state/brief.md

@@ -0,0 +1,8 @@
+# An inherited counter
+
+Keep independent counts for Parent and Child. Both start at zero; incrementing one must not alter the other. Child.label must compose its label with Parent.label through super, producing "parent-child". Implement `singleton_owner` to identify the singleton class that owns Parent.label.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `class_state.rb` in this exercise's folder. Checks call
+`Exercises::ClassState` and its example classes.

data/exercises/class-state/class_state.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Shared class variables are the deliberate starting bug.
+# rubocop:disable Style/ClassVars
+
+module Exercises
+  # Keep independent counts for Parent and Child.
+  class ClassState
+    # Example Parent for class state.
+    class Parent
+      @@count = 0
+      # Resets state belonging to this class object.
+      # @return [Integer]
+      def self.reset = @@count = 0
+      # Returns this class object's counter, defaulting to zero.
+      # @return [Integer]
+      def self.count = @@count
+      # Increments this class object's counter.
+      # @return [Integer]
+      def self.increment = @@count += 1
+      # Returns the label supplied by this class's inheritance chain.
+      # @return [String]
+      def self.label = 'parent'
+    end
+
+    # Example Child for class state.
+    class Child < Parent
+      # Returns the label supplied by this class's inheritance chain.
+      # @return [String]
+      def self.label = 'child'
+    end
+
+    # Returns the singleton class owning the label class method.
+    # @return [Class]
+    def self.singleton_owner = Parent
+  end
+end
+
+# rubocop:enable Style/ClassVars

data/exercises/class-state/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Class variables can share one slot through an inheritance hierarchy.
+
+Class instance variables belong to each class object; initialize or default them per receiver.

data/exercises/closure-capture/brief.md

@@ -0,0 +1,8 @@
+# Three multipliers, one captured name
+
+Implement `multipliers(numbers)` returning one lambda per number. Each lambda multiplies its single argument by its own captured number and rejects extra arguments. The starting for loop shares its loop variable, and Proc has different argument handling from lambda.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `closure_capture.rb` in this exercise's folder. Checks call
+`Exercises::ClosureCapture` and its example classes.

data/exercises/closure-capture/closure_capture.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# The example deliberately uses for rather than a block iterator.
+# rubocop:disable Style/For
+
+module Exercises
+  # Implement multipliers(numbers) returning one lambda per number.
+  class ClosureCapture
+    # Creates an independently captured lambda for each factor.
+    # @return [Array<Proc>]
+    def self.multipliers(numbers)
+      functions = []
+      for factor in numbers
+        functions << proc { |value| value * factor }
+      end
+      functions
+    end
+  end
+end
+
+# rubocop:enable Style/For

data/exercises/closure-capture/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+A closure retains a variable, not just a snapshot of its current value.
+
+A for loop shares its variable; an each block gives a useful scope for creating each closure.

data/exercises/collection-basics/brief.md

@@ -0,0 +1,8 @@
+# A collection of clues
+
+Read `[1, 2, 3].map { |n| n * 2 }` and `[1, 2, 3].select(&:odd?)`.
+Fill the two expectation blanks in `koans`, then implement `double_odds`
+so it doubles only odd input numbers. For `[1, 2, 3]`, return `[2, 6]`.
+Preserve the input array.
+
+Save your file to rerun the checks automatically.

data/exercises/collection-basics/collection_basics.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Fill the expectations and implement the collection operation below.
+  class CollectionBasics
+    def self.koans
+      { mapped: nil, selected: nil }
+    end
+
+    # @param [Object] numbers
+    # @return [Object]
+    def self.double_odds(numbers)
+      numbers.map { |number| number * 2 }
+    end
+  end
+end

data/exercises/collection-basics/hint.md

@@ -0,0 +1,6 @@
+# Hint: choosing and transforming values
+
+map returns one result for every input item; select keeps only matching items.
+Separate choosing odd values from doubling those values.
+
+For the expectation blanks, work through each input number and write the resulting arrays.

data/exercises/constant-scope/brief.md

@@ -0,0 +1,8 @@
+# Which scope owns this name?
+
+Study this setup, then fill `predictions`: a module Catalog has LABEL="outer"; Catalog::Item has LABEL="item" and Catalog::Item::Nested reads LABEL. A class Base sets @@count=0; Child inherits Base and increments @@count. A local `value` assigned only inside a block does not become available outside that block unless it was already declared. Return lexical_label, shared_class_count, new_block_local_visible. Implement `counter` as a closure over a local integer; two separately created counters must not share state.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `constant_scope.rb` in this exercise's folder. Checks call
+`Exercises::ConstantScope` and its example classes.

data/exercises/constant-scope/constant_scope.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Study this setup, then fill predictions: a module Catalog has LABEL="outer"; Catalog::Item has
+  # LABEL="item" and Catalog::Item::Nested reads LABEL.
+  class ConstantScope
+    # Returns predictions for the expressions described in the brief.
+    # @return [Hash<Symbol, Object>]
+    def self.predictions = { lexical_label: 'outer', shared_class_count: 0, new_block_local_visible: true }
+
+    # Creates a new counter closure with independent local state.
+    # @return [Proc]
+    def self.counter
+      @count = 0
+      -> { @count += 1 }
+    end
+  end
+end

data/exercises/constant-scope/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Constant lookup follows lexical nesting; inherited class variables can be shared.
+
+An instance variable on the Exercises::ConstantScope class is shared by all closures using that module as self.

data/exercises/core-protocols/brief.md

@@ -0,0 +1,8 @@
+# A useful custom collection
+
+Packet wraps numbers. Implement each to yield all values and return an Enumerator without a block; include Enumerable. Order Packet objects by the sum of their values through Comparable and <=>. to_s should return "Packet(total)". `protocol` returns whether a Packet responds to each and is an Object. Do not change the caller’s array.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `core_protocols.rb` in this exercise's folder. Checks call
+`Exercises::CoreProtocols` and its example classes.

data/exercises/core-protocols/core_protocols.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# The example deliberately contrasts received arguments with values actually used.
+# rubocop:disable Lint/UnusedMethodArgument
+
+module Exercises
+  # Packet wraps numbers.
+  class CoreProtocols
+    # Example Packet for core protocols.
+    class Packet
+      include Enumerable
+      include Comparable
+
+      # Stores the initial values used by this example.
+      # @return [void]
+      def initialize(values) = @values = values.dup
+
+      # Yields all stored numbers, or returns an Enumerator when no block is given.
+      # @return [Enumerator, Object]
+      def each
+        return enum_for(:each) unless block_given?
+
+        yield @values.first unless @values.empty?
+      end
+
+      # Returns the sum of the packet's stored numbers.
+      # @return [Integer]
+      def total = @values.sum
+      # Compares packet totals in ascending order.
+      # @return [Integer]
+      def <=>(other) = other.total <=> total
+      # Returns the packet's total in its printable representation.
+      # @return [String]
+      def to_s = 'Packet'
+    end
+
+    # Reports each support and ordinary object membership.
+    # @return [Array<Boolean>]
+    def self.protocol(packet) = [false, false]
+  end
+end
+
+# rubocop:enable Lint/UnusedMethodArgument

data/exercises/core-protocols/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Enumerable needs an each implementation; Comparable needs <=>.
+
+A no-block each can return enum_for(:each), which uses Kernel’s enumeration support.

data/exercises/delegation/brief.md

@@ -0,0 +1,8 @@
+# Send it to the right receiver
+
+Mailbox wraps a supplied array. Use Forwardable so push and size delegate to that supplied array, including later changes made directly to it. Do not copy it or delegate to the archive. Return Array#push’s normal result.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `delegation.rb` in this exercise's folder. Checks call
+`Exercises::Delegation` and its example classes.

data/exercises/delegation/delegation.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+module Exercises
+  # Mailbox wraps a supplied array.
+  class Delegation
+    # Example Mailbox for delegation.
+    class Mailbox
+      extend Forwardable
+
+      # Stores the initial values used by this example.
+      # @return [void]
+      def initialize(items)
+        @items = items
+        @archive = []
+      end
+      def_delegators :@archive, :push, :size
+    end
+  end
+end

data/exercises/delegation/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+A delegated method forwards to a particular receiver; the choice of receiver is part of the API.
+
+Forwardable generates focused forwarding methods without writing every wrapper.

data/exercises/dynamic-methods/brief.md

@@ -0,0 +1,8 @@
+# Build readers without losing names
+
+Implement `readers(names)` to return a new class with one instance reader per name, using define_method and instance_variable_get. Each method must retain its own name. Implement `evaluate(factor)` to evaluate "factor * 2" in its local binding. `instance_value(object,name)` should return that object’s @name through reflection. `class_value` should evaluate a class-level expression in the generated class context.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `dynamic_methods.rb` in this exercise's folder. Checks call
+`Exercises::DynamicMethods` and its example classes.