rkoans 0.0.1 → 0.1.0

data/solutions/class-state/class_state.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Keep independent counts for Parent and Child.
+  class ClassState
+    # Example Parent for class state.
+    class Parent
+      # 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 || 0
+      # Increments this class object's counter.
+      # @return [Integer]
+      def self.increment = @count = 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 = "#{super}-child"
+    end
+
+    # Returns the singleton class owning the label class method.
+    # @return [Class]
+    def self.singleton_owner = Parent.method(:label).owner
+  end
+end

data/solutions/closure-capture/closure_capture.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+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)
+      numbers.map { |factor| ->(value) { value * factor } }
+    end
+  end
+end

data/solutions/collection-basics/collection_basics.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Exercises
+  # A reference implementation for comparison after completing the exercise.
+  class CollectionBasics
+    def self.koans
+      { mapped: [2, 4, 6], selected: [1, 3] }
+    end
+
+    def self.double_odds(numbers)
+      numbers.select(&:odd?).map { |number| number * 2 }
+    end
+  end
+end

data/solutions/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: 'item', shared_class_count: 1, new_block_local_visible: false }
+
+    # Creates a new counter closure with independent local state.
+    # @return [Proc]
+    def self.counter
+      count = 0
+      -> { count += 1 }
+    end
+  end
+end

data/solutions/core-protocols/core_protocols.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# These examples demonstrate yield rather than explicit block forwarding.
+# rubocop:disable Style/ExplicitBlockArgument
+
+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?
+
+        @values.each { |value| yield value }
+        self
+      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) = total <=> other.total
+      # Returns the packet's total in its printable representation.
+      # @return [String]
+      def to_s = "Packet(#{total})"
+    end
+
+    # Reports each support and ordinary object membership.
+    # @return [Array<Boolean>]
+    def self.protocol(packet) = [packet.respond_to?(:each), packet.is_a?(Object)]
+  end
+end
+
+# rubocop:enable Style/ExplicitBlockArgument

data/solutions/delegation/delegation.rb

@@ -0,0 +1,17 @@
+# 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
+      def_delegators :@items, :push, :size
+    end
+  end
+end

data/solutions/dynamic-methods/dynamic_methods.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# The fixed literal expression is an isolated binding or syntax experiment.
+# rubocop:disable Style/EvalWithLocation
+
+module Exercises
+  # Implement readers(names) to return a new class with one instance reader per name, using
+  # define_method and instance_variable_get.
+  class DynamicMethods
+    # Builds a class whose readers capture their own instance-variable names.
+    # @return [Class]
+    def self.readers(names)
+      Class.new do
+        names.each do |name|
+          define_method(name) { instance_variable_get("@#{name}") }
+        end
+      end
+    end
+
+    # Evaluates a fixed literal expression with access to the local binding.
+    # @return [Integer]
+    def self.evaluate(factor) = eval('factor * 2', binding)
+    # Reads the named instance variable from the supplied object.
+    # @return [Object]
+    def self.instance_value(object, name) = object.instance_variable_get("@#{name}")
+    # Returns the class object seen as self inside class_eval.
+    # @return [Class]
+    def self.class_value(klass) = klass.class_eval { self }
+  end
+end
+
+# rubocop:enable Style/EvalWithLocation

data/solutions/exception-flow/exception_flow.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# The example deliberately rescues and reraises to observe preserved exception state.
+# rubocop:disable Lint/UselessRescue
+
+module Exercises
+  # Implement trace(fail:): append "work"; if fail, raise and rescue a StandardError and append
+  # "rescue"; otherwise append "else".
+  class ExceptionFlow
+    # Implements trace.
+    def self.trace(fail:)
+      trail = ['work']
+      begin
+        raise StandardError, 'failure' if fail
+      rescue StandardError
+        trail << 'rescue'
+      else
+        trail << 'else'
+      ensure
+        trail << 'ensure'
+      end
+      trail
+    end
+
+    # Implements reraises.
+    def self.reraises
+      raise ArgumentError, 'original'
+    rescue ArgumentError
+      raise
+    end
+  end
+end
+
+# rubocop:enable Lint/UselessRescue

data/solutions/heredoc-layout/heredoc_layout.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Exercises
+  # A reference implementation for comparison after completing the exercise.
+  class HeredocLayout
+    # Strips common source indentation and interpolates the supplied name.
+    # @param name [String]
+    # @return [String]
+    def self.render(name)
+      <<~TEXT
+        Hello #{name}
+          Ruby
+      TEXT
+    end
+
+    # Returns literal interpolation syntax followed by a newline.
+    # @return [String]
+    def self.literal
+      <<~'TEXT'
+        Hello #{name}
+      TEXT
+    end
+  end
+end

data/solutions/keyword-forwarding/keyword_forwarding.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# The block name is observable through parameter metadata or the explicit forwarding example.
+# The exercise makes positional, keyword, and block forwarding visible.
+# rubocop:disable Naming/BlockForwarding, Style/ArgumentsForwarding
+
+module Exercises
+  # Fix forward to preserve positional arguments, keyword arguments, and the block when calling
+  # target.
+  class KeywordForwarding
+    # Renders one positional payload with an optional block and suffix.
+    # @return [String]
+    def self.target(payload, suffix: '?')
+      rendered = block_given? ? yield(payload) : payload.to_s
+      rendered + suffix
+    end
+
+    # Forwards positional arguments, keywords, and the block to target.
+    # @return [String]
+    def self.forward(*args, **keywords, &block)
+      target(*args, **keywords, &block)
+    end
+  end
+end
+
+# rubocop:enable Naming/BlockForwarding, Style/ArgumentsForwarding

data/solutions/lazy-enumeration/lazy_enumeration.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Implement first_multiples(limit) to return the first limit positive multiples of seven, starting
+  # at seven, using the endless range (1..).
+  class LazyEnumeration
+    # Takes the requested number of multiples from a lazy infinite sequence.
+    # @return [Array<Integer>]
+    def self.first_multiples(limit) = (1..).lazy.select { |n| (n % 7).zero? }.first(limit)
+  end
+end

data/solutions/literals-and-operators/literals_and_operators.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Fill predictions for these expressions: !!0, 5 / 2, 5 / 2.0, 1 + 2 * 3, !nil, %w[ruby rails], and (1..3).to_a.
+  class LiteralsAndOperators
+    # Implements predictions.
+    def self.predictions
+      {
+        zero_truthy: true,
+        integer_division: 2,
+        float_division: 2.5,
+        precedence: 7,
+        not_nil: true,
+        words: %w[ruby rails],
+        range: [1, 2, 3]
+      }
+    end
+
+    # Implements default for nil.
+    def self.default_for_nil(value) = value.nil? ? 'missing' : value
+  end
+end

data/solutions/method-contracts/method_contracts.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Fix format_order(name, quantity=1, *extras, unit:, **options, &block) to return
+  # "name:quantity:unit:extra_count:priority" where priority defaults to "normal".
+  class MethodContracts
+    # Formats positional, rest, and keyword options, then applies an optional block.
+    # @return [String]
+    def self.format_order(name, quantity = 1, *extras, unit:, **options, &block)
+      text = "#{name}:#{quantity}:#{unit}:#{extras.size}:#{options.fetch(:priority, 'normal')}"
+      block ? block.call(text) : text
+    end
+
+    # Reports the parameter kinds and names of format_order.
+    # @return [Array<Array<Symbol>>]
+    def self.parameters = method(:format_order).parameters
+  end
+end

data/solutions/method-lookup/method_lookup.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Presenter#call returns "base".
+  class MethodLookup
+    # Example Wrapper for method lookup.
+    module Wrapper
+      # Returns the value from this scope's example receiver.
+      # @return [String]
+      def call = "[#{super}]"
+    end
+
+    # Example Presenter for method lookup.
+    class Presenter
+      prepend Wrapper
+
+      # Returns the value from this scope's example receiver.
+      # @return [String]
+      def call = 'base'
+    end
+
+    # Lists the first two ancestor names in method lookup order.
+    # @return [Array<String>]
+    def self.lookup = Presenter.ancestors.first(2).map(&:name)
+  end
+end

data/solutions/nonlocal-exit/nonlocal_exit.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Explicit return is the subject of this example.
+# rubocop:disable Style/RedundantReturn
+
+module Exercises
+  # Implement lambda_trace so return inside the lambda ends only that lambda, and the method still
+  # appends "after".
+  class NonlocalExit
+    # Collects the lambda result and continues the surrounding method.
+    # @return [Array<String>]
+    def self.lambda_trace
+      action = -> { return 'inside' }
+      [action.call, 'after']
+    end
+
+    # Returns a proc whose later return targets this already completed method.
+    # @return [Proc]
+    def self.escaped_proc = proc { return :gone }
+
+    # Uses catch and throw to find the first even number across nested groups.
+    # @return [Integer, nil]
+    def self.find_even(groups)
+      catch(:found) do
+        groups.each do |group|
+          group.each { |value| throw :found, value if value.even? }
+        end
+        nil
+      end
+    end
+
+    # Skips odd values while collecting the even numbers.
+    # @return [Array<Integer>]
+    def self.skip_odds(values)
+      collected = []
+      values.each do |value|
+        next if value.odd?
+
+        collected << value
+      end
+      collected
+    end
+  end
+end
+
+# rubocop:enable Style/RedundantReturn

data/solutions/numbered-parameters/numbered_parameters.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Two numbered parameters deliberately demonstrate pair destructuring.
+# rubocop:disable Style/NumberedParametersLimit
+
+module Exercises
+  # Implement pair_sums using the block’s input pairs; for [[2,3],[4,5]], return [5,9].
+  class NumberedParameters
+    # Adds both components of each pair using numbered parameters.
+    # @return [Array<Integer>]
+    def self.pair_sums(pairs) = pairs.map { _1 + _2 }
+    # Returns predictions for the expressions described in the brief.
+    # @return [Hash<Symbol, Object>]
+    def self.predictions = { explicit_and_numbered: false, numbered_pair: true }
+  end
+end
+
+# rubocop:enable Style/NumberedParametersLimit

data/solutions/numeric-precision/numeric_precision.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# The original descriptive check identifiers and example strings remain intact.
+# Short parameter names match the small arithmetic or assignment examples.
+# rubocop:disable Layout/LineLength, Naming/MethodParameterName
+
+module Exercises
+  # Implement ratios(a,b) returning integer division, floating division, and exact Rational division under keys integer, floating, rational.
+  class NumericPrecision
+    # Implements ratios.
+    def self.ratios(a, b) = { integer: a / b, floating: a.fdiv(b), rational: Rational(a, b) }
+    # Implements imaginary product.
+    def self.imaginary_product(a, b) = Complex(0, a) * Complex(0, b)
+  end
+end
+
+# rubocop:enable Layout/LineLength, Naming/MethodParameterName

data/solutions/pattern-matching/pattern_matching.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Implement amount(payload, kind) to return a positive Integer amount only when a hash has type
+  # equal to the supplied kind and amount is an Integer greater than zero.
+  class PatternMatching
+    # Implements amount.
+    def self.amount(payload, kind)
+      case payload
+      in { type: ^kind, amount: Integer => number } if number.positive?
+        number
+      else
+        nil
+      end
+    end
+  end
+end

data/solutions/refinement-scope/refinement_scope.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Speaker#say normally returns "plain".
+  class RefinementScope
+    # Example Speaker for refinement scope.
+    class Speaker
+      # Returns the voice selected by the lexical refinement scope.
+      # @return [String]
+      def say = 'plain'
+    end
+
+    # Example Voice for refinement scope.
+    module Voice
+      refine Speaker do
+        # Returns the voice selected by the lexical refinement scope.
+        # @return [String]
+        def say = 'local'
+      end
+    end
+
+    # Example Local for refinement scope.
+    module Local
+      using Voice
+      # Returns the value from this scope's example receiver.
+      # @return [String]
+      def self.call = Speaker.new.say
+    end
+
+    # Returns the unrefined voice outside the local scope.
+    # @return [String]
+    def self.outside = Speaker.new.say
+  end
+end

data/solutions/regexp-captures/regexp_captures.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# The example explicitly observes the regexp capture variable.
+# rubocop:disable Style/SpecialGlobalVars
+
+module Exercises
+  # Implement parse(text) for an entire string of lowercase name, colon, and decimal digits.
+  class RegexpCaptures
+    # Implements parse.
+    def self.parse(text)
+      match = /\A(?<name>[a-z]+):(?<id>\d+)\z/.match(text)
+      match && { name: match[:name], id: match[:id].to_i }
+    end
+
+    # Implements probe.
+    def self.probe(text)
+      /old/.match('old')
+      matched = /ruby/.match?(text)
+      [$~&.to_s, matched]
+    end
+  end
+end
+
+# rubocop:enable Style/SpecialGlobalVars

data/solutions/runtime-context/runtime_context.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Exercises
+  # A reference implementation for comparison after completing the exercise.
+  class RuntimeContext
+    # Returns process inputs and runtime metadata with an independent argument array.
+    # The greeting is nil when RKOANS_GREETING is absent; file fields are basenames.
+    def self.context
+      {
+        arguments: ARGV.dup,
+        greeting: ENV.fetch('RKOANS_GREETING', nil),
+        program: File.basename($PROGRAM_NAME),
+        file: File.basename(__FILE__),
+        encoding: __ENCODING__.name,
+        ruby: RUBY_VERSION
+      }
+    end
+  end
+end

data/solutions/shared-rows/shared_rows.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Builds rows whose mutable contents are independent.
+  class SharedRows
+    # Returns count empty rows, each with its own mutable array.
+    # @param count [Integer] nonnegative number of rows
+    # @return [Array<Array<Object>>]
+    def self.rows(count)
+      Array.new(count) { [] }
+    end
+  end
+end

data/solutions/singleton-pattern/singleton_pattern.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'singleton'
+module Exercises
+  # Use the standard-library Singleton module so Configuration.instance returns the same instance
+  # and Configuration.new is not a public constructor.
+  class SingletonPattern
+    # Example Configuration for singleton pattern.
+    class Configuration
+      include Singleton
+
+      attr_accessor :mode
+
+      # Stores the initial values used by this example.
+      # @return [void]
+      def initialize = @mode = 'learning'
+    end
+  end
+end

data/solutions/time-and-date/time_and_date.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+module Exercises
+  # Implement utc(text) to parse an ISO8601 timestamp with an explicit offset and return the same
+  # instant formatted in UTC.
+  class TimeAndDate
+    # Normalizes an offset ISO8601 timestamp to its UTC representation.
+    # @return [String]
+    def self.utc(text) = Time.iso8601(text).utc.iso8601
+    # Returns the signed integer calendar-day difference between ISO dates.
+    # @return [Integer]
+    def self.days_between(first, last) = (Date.iso8601(last) - Date.iso8601(first)).to_i
+  end
+end

data/solutions/visibility/visibility.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# The explicit receiver is part of the method-call experiment.
+# Explicit getter definitions are compared with attr_reader and attr_accessor.
+# rubocop:disable Style/RedundantSelf, Style/TrivialAccessors
+
+module Exercises
+  # Wallet has an internal balance reader used when comparing wallets, and a normalizer used within
+  # deposit.
+  class Visibility
+    # Example Wallet for visibility.
+    class Wallet
+      # Stores the initial values used by this example.
+      # @return [void]
+      def initialize(balance) = @balance = balance
+      # Returns the protected balance used for peer comparisons.
+      # @return [Integer]
+      def balance = @balance
+      # Converts a deposit amount to its nonnegative value.
+      # @return [Integer]
+      def normalize(value) = value.abs
+      # Adds the normalized amount to the balance.
+      # @return [Integer]
+      def deposit(value) = @balance += self.normalize(value)
+      # Compares this balance with another wallet's balance.
+      # @return [Integer]
+      def compare(other) = balance <=> other.balance
+      protected :balance
+      private :normalize
+    end
+  end
+end
+
+# rubocop:enable Style/RedundantSelf, Style/TrivialAccessors