rkoans 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9da424188c5df8f91c61f90ea21e3322877af560c5c56e073267c863c43156a9
-  data.tar.gz: 15fde98c5158a6b49c9f9bd3cc606556e43380695cf4045c27b5ecf3b8dfbe98
+  metadata.gz: 20e5b0bf25e0df8e45b6e657a17ea17d11261ea4898a8c3324a76c6140fdf7ff
+  data.tar.gz: e957886a95dcf25e1d2bb4d4baf16423f0c63b9bdee5f67ca066ac427f95ff6f
 SHA512:
-  metadata.gz: c4a4d73b82063fcbd98cdafa982f19cb7787efc80f3f688f94068cfcf184c4b35341352a714ff159b012a04b533b20aa5240575c7fe62023421c06608c338664
-  data.tar.gz: 9f8d4751b8525ec5fa38b8ecf8b4f51c7d4f80dd7d22557138428e0a013044d9273fa4ddf6e7a2755e873ac4077eb31d99e6cd508333071f54efde0ca75bde6d
+  metadata.gz: a909d17fea94d5acba405c4b720df92719cd4eb923247d0e0b35346df3b0f31261a7dcf3e207139670a2b36bea8b55f3916964ea56eac77691f6943329057305
+  data.tar.gz: ac1f4eb219698c0aca30530d49c7c5b500c00a7158f53d0fe2df892ecdbbc48bdb031bf2e843b8194c9acc6d7d4e5e678d49e3e21ee31b6b2ad3cc5a89308fc9

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.1.0]
+
+- Expand the Ruby track to 59 lessons, including the MRI-compatible Ruby Koans
+  sequence, triangle, scoring, dice and proxy projects, and a Greed game capstone.
+- Document practice coverage for the published Ruby Gold version 3 topics and
+  the differences between the exam's Ruby 3.1 target and this gem's runtime.
+- Add hints, reference solutions and RBS signatures for the exercises.
+- Correct lesson commands and strengthen regexp ID type checks.
+
+Existing selections, saved edits and completion history are preserved. Use
+`rkoans list` and `rkoans start EXERCISE` to try lessons added earlier in the
+sequence. See [the curriculum guide](CURRICULUM.md) for scope and exclusions.
+
 ## [0.0.1] - 2026-10-13
 
 - Initial release

data/CURRICULUM.md

@@ -0,0 +1,86 @@
+# Ruby curriculum
+
+The Ruby track combines the MRI-compatible Ruby Koans chapters with implementation
+exercises covering the published Ruby Gold version 3 topic outline. Lessons build
+from predictions about Ruby expressions to small programming projects.
+
+## Ruby Koans scope
+
+The sequence includes all 33 MRI-compatible `about_*` chapters in the source
+curriculum, including the optional extra-credit project. Another 26 exercises,
+including the heredoc prediction lesson, bring the track to 59 lessons.
+`about-pattern-matching` is included even though the source runner restricts it
+to older runtime versions.
+
+The JRuby-only `about_java_interop` chapter is excluded: this gem targets MRI Ruby
+4.0.7 and does not provide a Java runtime. Obsolete Ruby 1.8 behavior is explained
+or replaced with current behavior, rather than presented as a current answer.
+For example, indexing a string returns a string, and `self` can receive a private
+method call in modern Ruby.
+
+The triangle projects are independent learner files, so part two supplies a
+classifier to extend. File examples use real temporary files rather than requiring
+a file in the caller's working directory. Dice checks replay a seeded random
+stream; they never assume that two random rolls must differ. The original
+free-form extra credit is adapted as a deterministic Greed engine repair, with
+an optional interface or automated player left for further practice.
+
+See [third-party notices](THIRD_PARTY_NOTICES.md) for Koans attribution and terms.
+
+## Gold topics
+
+Mapped against the Ruby Association's [official Gold version 3 outline](https://www.ruby.or.jp/en/certification/examination/)
+on October 14, 2026. The exam targets **Ruby 3.1.x**; Rkoans runs on **Ruby 4.0.7 or
+newer**. These are practice examples for every published topic category, not an
+exhaustive model of the exam or a guarantee of exam readiness. Runtime-specific
+behavior can differ, and the suite has not been validated on Ruby 3.1.
+
+Each link points to an independent Minitest check; the named method identifies a
+concrete behavior checked there. References are teaching examples, not the source
+of expected values inside those checks. Checks establish observable behavior;
+they do not require one particular implementation technique.
+
+| Topic | Exercise check | Behavior exercised |
+| --- | --- | --- |
+| `environment.predefined` | [runtime-context: `test_runtime_globals`](test/exercises/runtime_context_test.rb) | ARGV and ENV; runtime constants and empty/missing input checks |
+| `syntax.literals` | [literals-and-operators: `test_literals_and_precedence`](test/exercises/literals_and_operators_test.rb) | Literal values and numeric division |
+| `syntax.variables_constants` | [constant-scope: `test_scope_predictions`](test/exercises/constant_scope_test.rb) | Lexical constants, shared class state and local scope |
+| `syntax.operators` | [literals-and-operators: `test_short_circuit_default`](test/exercises/literals_and_operators_test.rb) | Precedence, truthiness and nil-only defaults |
+| `syntax.blocks` | [blocks-and-methods: `test_apply_block`](test/exercises/blocks_and_methods_test.rb) | Yielded arguments, result and invocation count |
+| `syntax.exceptions` | [exception-flow: `test_ensure_and_else`](test/exercises/exception_flow_test.rb) | Rescue, else, ensure and reraising |
+| `syntax.nonlocal_exit` | [nonlocal-exit: `test_catch_throw_and_next`](test/exercises/nonlocal_exit_test.rb) | Catch/throw, next, and escaped proc return |
+| `syntax.keywords` | [keyword-forwarding: `test_keyword_and_block`](test/exercises/keyword_forwarding_test.rb) | Keywords, defaults, positional hashes and blocks |
+| `syntax.numbered_parameters` | [numbered-parameters: `test_numbered_pair_input`](test/exercises/numbered_parameters_test.rb) | Numbered block arguments and syntax predictions |
+| `syntax.lambda` | [closure-capture: `test_lambda_contract`](test/exercises/closure_capture_test.rb) | Lambda identity, strict arity and independent captures |
+| `syntax.pattern_matching` | [pattern-matching: `test_pinned_kind`](test/exercises/pattern_matching_test.rb) | Pinned values, type patterns and guards |
+| `syntax.heredocs` | [heredoc-layout: `test_squiggly_indentation`](test/exercises/heredoc_layout_test.rb) | Indentation and interpolation |
+| `oop.methods` | [method-contracts: `test_parameter_metadata`](test/exercises/method_contracts_test.rb) | Parameter kinds, required keywords, defaults and blocks |
+| `oop.access` | [visibility: `test_protected_peer_calls`](test/exercises/visibility_test.rb) | Protected peer access and private normalization |
+| `oop.classes` | [class-state: `test_independent_class_instance_state`](test/exercises/class_state_test.rb) | Independent class-object instance state |
+| `oop.inheritance` | [class-state: `test_class_inheritance_and_singleton`](test/exercises/class_state_test.rb) | Superclass method calls and singleton ancestry |
+| `oop.modules` | [method-lookup: `test_ancestor_order`](test/exercises/method_lookup_test.rb) | Module lookup order and wrapping |
+| `oop.prepend` | [method-lookup: `test_prepend_wrapper`](test/exercises/method_lookup_test.rb) | Prepending a wrapper around the original method |
+| `oop.refinements` | [refinement-scope: `test_lexical_refinement`](test/exercises/refinement_scope_test.rb) | Lexical activation and behavior outside the scope |
+| `meta.eval` | [dynamic-methods: `test_eval_binding_and_reflection`](test/exercises/dynamic_methods_test.rb) | Evaluation with a captured local binding |
+| `meta.define_method` | [dynamic-methods: `test_defined_reader_closures`](test/exercises/dynamic_methods_test.rb) | Dynamically defined readers with separate captured names |
+| `meta.instance_variables` | [dynamic-methods: `test_eval_binding_and_reflection`](test/exercises/dynamic_methods_test.rb) | Reflective instance-variable access and class evaluation |
+| `builtin.object` | [core-protocols: `test_enumerable_protocol`](test/exercises/core_protocols_test.rb) | Object membership and capability introspection |
+| `builtin.module` | [method-lookup: `test_ancestor_order`](test/exercises/method_lookup_test.rb) | Module ancestry; dynamic methods also exercise Module APIs |
+| `builtin.kernel` | [dynamic-methods: `test_eval_binding_and_reflection`](test/exercises/dynamic_methods_test.rb) | Kernel eval and binding; enum_for in core protocols |
+| `builtin.enumerable` | [core-protocols: `test_enumerable_protocol`](test/exercises/core_protocols_test.rb) | Custom each powering map and enumeration |
+| `builtin.comparable` | [core-protocols: `test_comparable_and_conversion`](test/exercises/core_protocols_test.rb) | Comparison protocol, ordering and printable conversion |
+| `builtin.numeric` | [numeric-precision: `test_numeric_division`](test/exercises/numeric_precision_test.rb) | Integer, Float, Rational and Complex type/value contracts |
+| `builtin.regexp` | [regexp-captures: `test_whole_string_and_captures`](test/exercises/regexp_captures_test.rb) | Whole-string anchors, named captures and Integer conversion |
+| `builtin.proc` | [nonlocal-exit: `test_proc_nonlocal_return`](test/exercises/nonlocal_exit_test.rb) | Escaped proc return; closures and lambdas in closure-capture |
+| `builtin.enumerator` | [lazy-enumeration: `test_lazy_limit`](test/exercises/lazy_enumeration_test.rb) | Finite demand from an unbounded lazy enumerator |
+| `stdlib.time` | [time-and-date: `test_time_offset`](test/exercises/time_and_date_test.rb) | Parsing an explicit offset and converting to UTC |
+| `stdlib.date` | [time-and-date: `test_calendar_days`](test/exercises/time_and_date_test.rb) | Signed calendar-day distances across leap day |
+| `stdlib.singleton` | [singleton-pattern: `test_singleton_identity`](test/exercises/singleton_pattern_test.rb) | Stable identity and an inaccessible constructor |
+| `stdlib.forwardable` | [delegation: `test_live_receiver`](test/exercises/delegation_test.rb) | Delegation to a live receiver and return-value preservation |
+
+## Returning learners
+
+Your selected exercise, saved edits and completion history are preserved across
+updates. Newly added lessons earlier in the sequence are not visited automatically.
+Use `rkoans list` to find them and `rkoans start EXERCISE` to select one. Then use
+`rkoans check` to check the selected exercise once, or save while watching.

data/README.md

@@ -0,0 +1,77 @@
+# Rkoans
+
+Learn Ruby by editing code and watching Minitest checks respond to each save.
+
+## Get started
+
+Rkoans requires Ruby 4.0.7 or newer. From a source checkout, run:
+
+```sh
+bundle install
+bundle exec rkoans
+```
+
+Rkoans creates your study directory at `~/ruby-koans`, shows the exercise
+instructions, and prints the file to edit. The starter intentionally fails.
+Save your changes to rerun the checks automatically.
+
+Running `rkoans` again resumes your selected exercise and preserves your edits.
+Once the gem is installed, you can run it from any directory.
+`rkoans start` has the same behavior as `rkoans`.
+
+## Curriculum
+
+Practice Ruby through expression predictions and implementation projects, from
+basic syntax to blocks, object protocols, metaprogramming and standard libraries.
+See the [curriculum guide](CURRICULUM.md) for Ruby Koans scope, Gold topic coverage
+and runtime differences.
+
+Your current selection and saved work survive updates. To try a newly added
+lesson, use `rkoans list` and `rkoans start EXERCISE`.
+
+## Commands
+
+```sh
+rkoans list                       # List available exercises
+rkoans start blocks-and-methods   # Select an exercise
+rkoans check                      # Check the selected exercise once
+```
+
+Each exercise has a separate file in `~/ruby-koans/exercises`, such as
+`collection-basics/collection_basics.rb`. Switching exercises preserves your work.
+
+`rkoans check` exits with 0 for success, 1 for failed checks, or 2 for a setup or
+command error. Checks that run longer than 30 seconds are stopped.
+
+## Interactive session
+
+The terminal refreshes after each check. When an exercise passes, Rkoans shows
+`Exercise done ✓`, your progress, and a reference solution you can compare with
+your own code. The exercise stays open so you can experiment.
+
+- `?` shows keyboard help.
+- `h` shows a hint for the unfinished current exercise.
+- `l` lists exercises; `s` returns to the current exercise.
+- `n` followed by Enter advances to the next exercise.
+- `q` followed by Enter quits. Ctrl-C also exits.
+
+Help, hints, and view changes respond immediately. Available keys appear at the
+bottom of each screen. Saving while viewing the list keeps the list open.
+
+Rkoans remembers completed exercises, even if you later experiment with their
+code. Advancing checks your current code again and requires it to pass.
+
+## Licenses
+
+The CLI and original exercises use the MIT license. Adapted Ruby Koans lessons
+use CC BY-NC-SA 3.0; see [third-party notices](THIRD_PARTY_NOTICES.md) for their
+attribution, covered files, and license terms.
+
+## Development
+
+From the gem directory:
+
+```sh
+bundle exec rake
+gem build rkoans.gemspec
+```

data/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,30 @@
+# Third-party exercise content
+
+Rkoans' CLI and original exercises are covered by the MIT license in `LICENSE.txt`.
+Lessons named `about-*` are adapted from **Ruby Koans**, authored by
+Jim Weirich and Joe O'Brien. Their adapted content is distributed under
+**Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported
+(CC BY-NC-SA 3.0)**.
+
+This notice covers:
+
+- `exercises/about-*/` — starters, briefs, and hints
+- `test/exercises/about_*_test.rb` — exercise checks
+- `solutions/about-*/` — reference solutions
+- `sig/exercises/about_*.rbs` — signatures
+
+The `about-*` lesson names are reserved for Ruby Koans adaptations.
+
+Source: [Ruby Koans](https://github.com/edgecase/ruby_koans).
+Project: [Ruby Koans](https://www.rubykoans.com/).
+License: [CC BY-NC-SA 3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/).
+Full terms: [legal code](https://creativecommons.org/licenses/by-nc-sa/3.0/legalcode).
+
+Adaptations replace the Neo runner with Minitest, use Rkoans' learner-answer
+format, and add instructions, hints, references, and signatures.
+Individual files retain attribution and license notices.
+The original authors do not endorse these adaptations.
+
+The license permits sharing and adaptation with attribution, for noncommercial
+purposes, and requires adapted material to use the same license. The MIT license
+does not replace these terms for the covered files.

data/exercises/about-array-assignment/about_array_assignment.rb

@@ -0,0 +1,45 @@
+# 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 how array values are assigned to one or several variables.
+  class AboutArrayAssignment
+    # Replace each :fill_me_in with the assigned value shown in its example.
+    # @return [Hash<Symbol, String | Array<String> | nil>]
+    def self.koans
+      {
+        # names = ['John', 'Smith']; names
+        names: :fill_me_in,
+        # first_name, last_name = ['John', 'Smith']; first_name
+        first_name: :fill_me_in,
+        # first_name, last_name = ['John', 'Smith']; last_name
+        last_name: :fill_me_in,
+        # first_name, last_name = ['John', 'Smith', 'III']; first_name
+        extra_first: :fill_me_in,
+        # first_name, last_name = ['John', 'Smith', 'III']; last_name
+        extra_last: :fill_me_in,
+        # first_name, *last_name = ['John', 'Smith', 'III']; first_name
+        splat_first: :fill_me_in,
+        # first_name, *last_name = ['John', 'Smith', 'III']; last_name
+        splat_last: :fill_me_in,
+        # first_name, last_name = ['Cher']; first_name
+        short_first: :fill_me_in,
+        # first_name, last_name = ['Cher']; last_name
+        short_last: :fill_me_in,
+        # first_name, last_name = [['Willie', 'Rae'], 'Johnson']; first_name
+        nested_first: :fill_me_in,
+        # first_name, last_name = [['Willie', 'Rae'], 'Johnson']; last_name
+        nested_last: :fill_me_in,
+        # first_name, = ['John', 'Smith']; first_name
+        single_first: :fill_me_in,
+        # first_name = 'Roy'; last_name = 'Rob'; first_name, last_name = last_name, first_name; first_name
+        swapped_first: :fill_me_in,
+        # first_name = 'Roy'; last_name = 'Rob'; first_name, last_name = last_name, first_name; last_name
+        swapped_last: :fill_me_in
+      }
+    end
+  end
+end

data/exercises/about-array-assignment/brief.md

@@ -0,0 +1,11 @@
+# About Array Assignment
+
+Predict the values assigned by each example in `about_array_assignment.rb`.
+Replace each `:fill_me_in` with a string, array, or `nil` as appropriate.
+
+Explore assignment to one variable, parallel assignment, extra and missing
+values, splats, nested arrays, a trailing comma, and swapping two variables.
+Compare each variable's value after assignment with the original array.
+
+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-array-assignment/hint.md

@@ -0,0 +1,11 @@
+# Hint
+
+One variable normally receives the whole array. Several variables receive its
+values in order. A splat collects the remaining values in an array; without it,
+extra values are discarded. Missing values become `nil`.
+
+Compare `name = names` with `name, = names`. When swapping variables, Ruby
+evaluates the right-hand values before updating either left-hand variable.
+
+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-arrays/about_arrays.rb

@@ -0,0 +1,77 @@
+# 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 array construction, indexing, slicing, ranges, and destructive operations.
+  class AboutArrays
+    # Replace each :fill_me_in with the result of its example.
+    # Index and slice examples use [:peanut, :butter, :and, :jelly].
+    # @return [Hash<Symbol, Class | Integer | Symbol | Array | nil>]
+    # The answer table is data, not a sequence of operations.
+    def self.koans # rubocop:disable Metrics/MethodLength
+      {
+        # Array.new.class
+        empty_type: :fill_me_in,
+        # Array.new.size
+        empty_size: :fill_me_in,
+        # array = [1]; array[1] = 2; array[1]
+        second_literal: :fill_me_in,
+        # array = [1, 2]; array << 333; array
+        after_append: :fill_me_in,
+        # array[0]
+        first_index: :fill_me_in,
+        # array.first
+        first_method: :fill_me_in,
+        # array[3]
+        last_index: :fill_me_in,
+        # array.last
+        last_method: :fill_me_in,
+        # array[-1]
+        negative_last: :fill_me_in,
+        # array[-3]
+        negative_third: :fill_me_in,
+        # array[0, 1]
+        slice_one: :fill_me_in,
+        # array[0, 2]
+        slice_two: :fill_me_in,
+        # array[2, 2]
+        slice_tail: :fill_me_in,
+        # array[2, 20]
+        slice_long_tail: :fill_me_in,
+        # array[4, 0]
+        slice_at_end_zero: :fill_me_in,
+        # array[4, 100]
+        slice_at_end_long: :fill_me_in,
+        # array[5, 0]
+        slice_beyond_end: :fill_me_in,
+        # (1..5).class
+        range_type: :fill_me_in,
+        # (1..5).to_a
+        inclusive_range: :fill_me_in,
+        # (1...5).to_a
+        exclusive_range: :fill_me_in,
+        # array[0..2]
+        inclusive_slice: :fill_me_in,
+        # array[0...2]
+        exclusive_slice: :fill_me_in,
+        # array[2..-1]
+        negative_range_slice: :fill_me_in,
+        # array = [1, 2]; array.push(:last); array
+        after_push: :fill_me_in,
+        # array = [1, 2, :last]; array.pop
+        popped_value: :fill_me_in,
+        # array = [1, 2, :last]; array.pop; array
+        after_pop: :fill_me_in,
+        # array = [1, 2]; array.unshift(:first); array
+        after_unshift: :fill_me_in,
+        # array = [:first, 1, 2]; array.shift
+        shifted_value: :fill_me_in,
+        # array = [:first, 1, 2]; array.shift; array
+        after_shift: :fill_me_in
+      }
+    end
+  end
+end

data/exercises/about-arrays/brief.md

@@ -0,0 +1,16 @@
+# About Arrays
+
+Predict how Ruby arrays are constructed, indexed, sliced, and changed.
+
+Open `about_arrays.rb` and replace each `:fill_me_in` with the value produced by
+its example. For indexing and slicing, the examples use
+`[:peanut, :butter, :and, :jelly]`. Answers can be classes, integers, symbols,
+arrays, or `nil`.
+
+Explore positive and negative indexes, start-and-length slices, inclusive and
+exclusive ranges, and the difference between an operation's return value and
+the array it changes. Run the checks after each edit to see the next prediction
+to investigate.
+
+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-arrays/hint.md

@@ -0,0 +1,13 @@
+# Hint
+
+Array indexes start at zero. Negative indexes count backward from the end.
+
+With `array[start, length]`, `length` is a count of elements. Compare a start at
+`array.length` with a start beyond it: an empty array and `nil` are different.
+For ranges, `..` includes the endpoint and `...` excludes it.
+
+Try `push`, `pop`, `unshift`, and `shift` in IRB. Inspect the array after each
+operation as well as the value returned by the operation.
+
+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-asserts/about_asserts.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
+  # Supplies the expectations used by the five introductory assertion koans.
+  class AboutAsserts
+    # Replace the false and nil values with answers that make the checks pass.
+    # @return [Hash<Symbol, Boolean | Integer | nil>]
+    def self.koans
+      {
+        truth: false,
+        with_message: false,
+        expected_value: nil,
+        better_expected_value: nil,
+        filled_value: nil
+      }
+    end
+  end
+end

data/exercises/about-asserts/brief.md

@@ -0,0 +1,22 @@
+# Start with assertions
+
+An assertion checks whether something is true. A passing check stays quiet;
+a failing check tells you what to investigate.
+
+Open your `about_asserts.rb` file and replace the five answers in `koans`:
+
+- `truth`: make `assert truth` pass.
+- `with_message`: make `assert with_message, "This should be true -- Please fix this"` pass.
+- `expected_value`: supply the expected result for `1 + 1`, checked with `assert expected_value == actual_value`.
+- `better_expected_value`: supply that same result, checked with `assert_equal expected_value, actual_value`.
+- `filled_value`: fill the expectation in `assert_equal filled_value, 1 + 1`.
+
+Start with one answer and save. Compare the failures for `expected_value` and
+`better_expected_value`: `assert_equal` reports the expected and actual values,
+which makes the failure easier to understand.
+
+You only need to change the answers inside the braces. The surrounding Ruby code
+will become familiar in later exercises. Save to rerun the checks automatically.
+
+Adapted from **Ruby Koans: About Asserts** 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-asserts/hint.md

@@ -0,0 +1,10 @@
+# Hint: expectations and reality
+
+`assert` passes when its value is truthy. Try `true` for the first two answers.
+For the remaining answers, evaluate `1 + 1` and supply that result.
+
+`assert_equal expected, actual` compares both values and explains a mismatch.
+A message on `assert` gives you a clue about what went wrong.
+
+Adapted from **Ruby Koans: About Asserts** 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-blocks/about_blocks.rb

@@ -0,0 +1,76 @@
+# 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 blocks examples.
+  class AboutBlocks
+    # 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
+      {
+        # Methods can take blocks.
+        # yielded_result = method_with_block { 1 + 2 }
+        # assert_equal __, yielded_result
+        # Predict: yielded_result
+        methods_can_take_blocks_one: :fill_me_in,
+        # Blocks can be defined with do end too.
+        # yielded_result = method_with_block do 1 + 2 end
+        # assert_equal __, yielded_result
+        # Predict: yielded_result
+        blocks_can_be_defined_with_do_end_too_one: :fill_me_in,
+        # Blocks can take arguments.
+        # method_with_block_arguments do |argument|
+        # assert_equal __, argument
+        # end
+        # Predict: argument
+        blocks_can_take_arguments_one: :fill_me_in,
+        # Methods can call yield many times.
+        # result = []
+        # many_yields { |item| result << item }
+        # assert_equal __, result
+        # Predict: result
+        methods_can_call_yield_many_times_one: :fill_me_in,
+        # Methods can see if they have been called with a block.
+        # assert_equal __, yield_tester { :with_block }
+        # assert_equal __, yield_tester
+        # Predict: yield_tester { :with_block }
+        methods_can_see_if_they_have_been_called_with_a_block_one: :fill_me_in,
+        # Predict: yield_tester
+        methods_can_see_if_they_have_been_called_with_a_block_two: :fill_me_in,
+        # Block can affect variables in the code where they are created.
+        # value = :initial_value
+        # method_with_block { value = :modified_in_a_block }
+        # assert_equal __, value
+        # Predict: value
+        block_can_affect_variables_in_the_code_where_they_are_created_one: :fill_me_in,
+        # Blocks can be assigned to variables and called explicitly.
+        # add_one = lambda { |n| n + 1 }
+        # assert_equal __, add_one.call(10)
+        # Alternative calling syntax
+        # assert_equal __, add_one[10]
+        # Predict: add_one.call(10)
+        blocks_can_be_assigned_to_variables_and_called_explicitly_one: :fill_me_in,
+        # Predict: add_one[10]
+        blocks_can_be_assigned_to_variables_and_called_explicitly_two: :fill_me_in,
+        # Stand alone blocks can be passed to methods expecting blocks.
+        # make_upper = lambda { |n| n.upcase }
+        # result = method_with_block_arguments(&make_upper)
+        # assert_equal __, result
+        # Predict: result
+        stand_alone_blocks_can_be_passed_to_methods_expecting_blocks_one: :fill_me_in,
+        # Methods can take an explicit block argument.
+        # assert_equal __, method_with_explicit_block { |n| n * 2 }
+        # add_one = lambda { |n| n + 1 }
+        # assert_equal __, method_with_explicit_block(&add_one)
+        # Predict: method_with_explicit_block { |n| n * 2 }
+        methods_can_take_an_explicit_block_argument_one: :fill_me_in,
+        # Predict: method_with_explicit_block(&add_one)
+        methods_can_take_an_explicit_block_argument_two: :fill_me_in
+      }
+    end
+  end
+end

data/exercises/about-blocks/brief.md

@@ -0,0 +1,44 @@
+# About Blocks
+
+Replace each `:fill_me_in` in `about_blocks.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 `AboutBlocksTest`.
+
+```ruby
+def method_with_block
+    result = yield
+    result
+  end
+
+def method_with_block_arguments
+    yield("Jim")
+  end
+
+def many_yields
+    yield(:peanut)
+    yield(:butter)
+    yield(:and)
+    yield(:jelly)
+  end
+
+def yield_tester
+    if block_given?
+      yield
+    else
+      :no_block
+    end
+  end
+
+def method_with_explicit_block(&block)
+    block.call(10)
+  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-blocks/hint.md

@@ -0,0 +1,7 @@
+# Hint
+
+Follow each `yield`, including its arguments and return value. Blocks capture
+variables from their surrounding scope. `&` passes a callable as a block.
+
+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.