[WIP] Additional koans

CLAUDE_THOUGHTS_ON_KOANS.md

@@ -0,0 +1,113 @@
+# Claude's Analysis of Elixir Koans
+
+## Overall Assessment
+
+The Elixir koans provide a solid foundation for learning Elixir's core concepts through hands-on practice. The progression from basic data types to advanced concurrency concepts follows a logical learning path that builds knowledge incrementally.
+
+## Strengths
+
+### 1. **Excellent Progression and Coverage**
+- Well-structured from fundamentals (equalities, strings, numbers) to advanced topics (processes, GenServers, protocols)
+- Covers all essential Elixir data types and concepts systematically
+- Good balance between breadth and depth
+
+### 2. **Interactive Learning Approach**
+- The fill-in-the-blank (`___`) format encourages active engagement
+- Immediate feedback through test execution
+- Zen-like koan naming creates an engaging learning atmosphere
+
+### 3. **Strong Foundation Building**
+- **Basic Types**: Numbers, strings, atoms, booleans are well covered
+- **Data Structures**: Comprehensive coverage of lists, tuples, maps, keyword lists, MapSets, and structs
+- **Advanced Features**: Pattern matching, functions, enums, and comprehensions are thoughtfully presented
+
+### 4. **Concurrency Excellence**
+- Outstanding coverage of Elixir's actor model with processes, Tasks, Agents, and GenServers
+- Practical examples showing message passing, state management, and supervision
+- Good introduction to OTP concepts
+
+## Areas for Improvement
+
+### 1. **Missing Fundamental Concepts**
+- **Pipe Operator**: Only briefly mentioned in functions.ex:104-111, but deserves dedicated coverage as it's idiomatic Elixir
+- **with Statement**: Missing entirely - important for error handling and nested operations
+- **Case/Cond/If Statements**: Only case is briefly shown in pattern matching
+- **Guard Clauses**: Mentioned in functions but could use more comprehensive coverage
+- **Binary Pattern Matching**: Missing - important for working with binary data
+
+### 2. **Limited Error Handling**
+- Only basic error tuple patterns (`{:ok, value}`, `{:error, reason}`) are shown
+- Missing `try/catch/rescue/after` constructs
+- No coverage of custom exception types
+- Could benefit from more comprehensive error handling patterns
+
+### 3. **Module System Gaps**
+- Basic module definition shown but missing:
+  - Module attributes beyond `@moduledoc`
+  - Import/alias/require directives  
+  - Module compilation hooks
+  - Behaviors beyond GenServer
+
+### 4. **Syntax and Language Features**
+- **Documentation**: No coverage of `@doc` or doctests
+- **Typespecs**: Missing `@spec` and `@type` - important for larger codebases
+- **Macros**: Not covered (though perhaps too advanced for koans)
+- **Use/Import/Alias**: Mentioned but not explained
+
+### 5. **Practical Application**
+- Most examples are abstract - could benefit from more real-world scenarios
+- Missing file I/O operations
+- No coverage of common patterns like supervision trees
+- HTTP client/server basics could be valuable
+
+## Outdated or Problematic Areas
+
+### 1. **Syntax Updates Needed**
+- All syntax appears current for modern Elixir (1.14+)
+- No deprecated functions or patterns identified
+
+### 2. **Best Practices Alignment**
+- Code follows current Elixir style guidelines
+- Function definitions and module structures are idiomatic
+
+### 3. **Minor Issues**
+- Line 113 in Numbers.ex uses pattern matching syntax that's slightly advanced for its position
+- Some variable names could be more descriptive in complex examples
+
+## Recommended Additions
+
+### 1. **New Koans to Add**
+```
+21_control_flow.ex       # if/unless/cond/case comprehensive coverage
+22_error_handling.ex     # try/catch/rescue/after, error tuples
+23_pipe_operator.ex      # |>, then/2, comprehensive piping patterns  
+24_with_statement.ex     # with clauses, error handling patterns
+25_binary_matching.ex    # <<>>, binary patterns, string manipulation
+26_module_attributes.ex  # @doc, @spec, @type, compile-time attributes
+27_io_and_files.ex       # File operations, IO operations
+28_otp_behaviors.ex      # Custom behaviors, supervision basics
+```
+
+### 2. **Enhanced Existing Koans**
+- **Functions**: Add more pipe operator examples and capture syntax variations
+- **Pattern Matching**: Include more binary pattern matching examples
+- **GenServers**: Add supervision and error handling examples
+- **Enums**: Include Stream module basics for lazy evaluation
+
+### 3. **Pedagogical Improvements**
+- Add more real-world context to abstract examples
+- Include common pitfalls and "gotcha" moments
+- Add exercises that build on previous koans
+- Include performance considerations where relevant
+
+## Conclusion
+
+The Elixir koans are well-crafted and provide excellent coverage of Elixir's core concepts. They successfully teach the fundamentals and introduce advanced topics in a logical progression. The main gaps are in practical error handling, advanced control flow, and some modern Elixir idioms.
+
+**Recommendation**: These koans do a good job introducing Elixir basics. The most impactful improvements would be:
+1. Adding dedicated coverage for the pipe operator and `with` statement
+2. Expanding error handling beyond basic tuple patterns  
+3. Including more real-world, practical examples
+4. Adding binary pattern matching for string/data processing
+
+The current koans provide a solid foundation, but learners would benefit from supplementary material covering the missing concepts before moving to production Elixir development.

lib/koans/25_binary_matching.ex

@@ -0,0 +1,232 @@
+defmodule BinaryMatching do
+  @moduledoc false
+  use Koans
+
+  @intro "Binary Pattern Matching - Working with raw bytes and binary data"
+
+  koan "Binaries are sequences of bytes" do
+    binary = <<1, 2, 3>>
+    assert byte_size(binary) == ___
+  end
+
+  koan "Strings are UTF-8 encoded binaries" do
+    string = "hello"
+    assert is_binary(string) == ___
+    assert byte_size(string) == ___
+  end
+
+  koan "You can pattern match on binary prefixes" do
+    <<"Hello", rest::binary>> = "Hello, World!"
+    assert rest == ___
+  end
+
+  koan "Binary pattern matching can extract specific bytes" do
+    <<first, second, rest::binary>> = <<65, 66, 67, 68>>
+    assert first == ___
+    assert second == ___
+    assert rest == ___
+  end
+
+  koan "String pattern matching works with binary syntax" do
+    <<"HTTP/", version::binary-size(3), " ", status::binary-size(3), " ", message::binary>> =
+      "HTTP/1.1 200 OK"
+
+    assert version == ___
+    assert status == ___
+    assert message == ___
+  end
+
+  koan "You can match on specific bit patterns" do
+    <<flag::1, counter::7>> = <<200>>
+    assert flag == ___
+    assert counter == ___
+  end
+
+  koan "Endianness can be specified for multi-byte integers" do
+    <<number::16-little>> = <<1, 2>>
+    assert number == ___
+
+    <<number::16-big>> = <<1, 2>>
+    assert number == ___
+  end
+
+  koan "You can construct binaries with specific values" do
+    binary = <<255, 0, 128>>
+    <<high, low, middle>> = binary
+    assert high == ___
+    assert low == ___
+    assert middle == ___
+  end
+
+  koan "Float values can be packed into binaries" do
+    <<value::32-float>> = <<66, 246, 0, 0>>
+    assert Float.round(value, 1) == ___
+  end
+
+  # I think this is trying to cover https://hexdocs.pm/elixir/main/comprehensions.html#bitstring-generators
+  # but the syntax is apparently wrong...
+  # TODO: investigate
+  # koan "Binary comprehensions can create patterns" do
+  #  result = for <<byte <- <<1, 2, 3, 4>>, byte > 2>>, do: byte * 2
+  #  assert result == ___
+  # end
+
+  # TODO: investigate syntax here. It's erroring currently
+  # koan "You can parse CSV-like data with binary matching" do
+  #  parse_csv_line = fn line ->
+  #    String.split(String.trim(line), ",")
+  #    |> Enum.map(&String.trim/1)
+  #  end
+
+  #  # But with binary matching for more control:
+  #  parse_field = fn
+  #    <<"\"", field::binary-size(n), "\"", _::binary>> when byte_size(field) > 0 -> field
+  #    <<field::binary>> -> String.trim(field)
+  #  end
+
+  #  result = parse_csv_line.("Alice, 30, Engineer")
+  #  assert result == ___
+  # end
+
+  koan "IP address parsing with binary patterns" do
+    parse_ipv4 = fn ip_string ->
+      case String.split(ip_string, ".") do
+        [a, b, c, d] ->
+          <<String.to_integer(a), String.to_integer(b), String.to_integer(c),
+            String.to_integer(d)>>
+
+        _ ->
+          :error
+      end
+    end
+
+    <<a, b, c, d>> = parse_ipv4.("192.168.1.1")
+    assert a == ___
+    assert b == ___
+    assert c == ___
+    assert d == ___
+  end
+
+  koan "Binary matching can validate data formats" do
+    is_png? = fn
+      <<137, 80, 78, 71, 13, 10, 26, 10, _::binary>> -> true
+      _ -> false
+    end
+
+    png_header = <<137, 80, 78, 71, 13, 10, 26, 10, "fake data">>
+    jpeg_header = <<255, 216, 255, "fake data">>
+
+    assert is_png?.(png_header) == ___
+    assert is_png?.(jpeg_header) == ___
+  end
+
+  koan "You can extract length-prefixed strings" do
+    parse_length_string = fn
+      <<length::8, string::binary-size(length), rest::binary>> ->
+        {string, rest}
+
+      _ ->
+        :error
+    end
+
+    data = <<5, "Hello", "World">>
+    {extracted, remaining} = parse_length_string.(data)
+    assert extracted == ___
+    assert remaining == ___
+  end
+
+  koan "Binary matching works with hexadecimal literals" do
+    <<red::8, green::8, blue::8>> = <<0xFF, 0x80, 0x00>>
+    assert red == ___
+    assert green == ___
+    assert blue == ___
+  end
+
+  koan "You can match variable-length binary data" do
+    extract_until_delimiter = fn binary, delimiter ->
+      case :binary.split(binary, delimiter) do
+        [a, b] -> {a, b}
+        [_] -> {binary, ""}
+      end
+    end
+
+    {a, b} = extract_until_delimiter.("name=John&age=30", "&")
+    assert a == ___
+    assert b == ___
+  end
+
+  koan "Binary matching can parse simple protocols" do
+    parse_message = fn
+      <<1, length::16, payload::binary-size(length)>> ->
+        {:text, payload}
+
+      <<2, length::16, payload::binary-size(length)>> ->
+        {:binary, payload}
+
+      <<3>> ->
+        :ping
+
+      _ ->
+        :unknown
+    end
+
+    text_msg = <<1, 0, 5, "Hello">>
+    ping_msg = <<3>>
+
+    assert parse_message.(text_msg) == ___
+    assert parse_message.(ping_msg) == ___
+  end
+
+  koan "String interpolation creates binaries" do
+    name = "Alice"
+    age = 30
+    message = "Hello #{name}, you are #{age} years old"
+
+    <<"Hello ", rest::binary>> = message
+    assert rest == ___
+  end
+
+  koan "Binary pattern matching can validate checksums" do
+    validate_checksum = fn <<data::binary-size(4), checksum::8>> ->
+      calculated =
+        data
+        |> :binary.bin_to_list()
+        |> Enum.sum()
+        |> rem(256)
+
+      calculated == checksum
+    end
+
+    # Data: [1,2,3,4], sum = 10, checksum = 10
+    valid_packet = <<1, 2, 3, 4, 10>>
+    invalid_packet = <<1, 2, 3, 4, 20>>
+
+    assert validate_checksum.(valid_packet) == ___
+    assert validate_checksum.(invalid_packet) == ___
+  end
+
+  koan "You can work with null-terminated strings" do
+    parse_c_string = fn binary ->
+      case :binary.split(binary, <<0>>) do
+        [string, _rest] -> string
+        [string] -> string
+      end
+    end
+
+    c_string = <<"Hello World", 0, "ignored">>
+    result = parse_c_string.(c_string)
+    assert result == ___
+  end
+
+  koan "Binary construction and pattern matching are symmetric" do
+    # Construction
+    packet = <<42::16, "Hello", 0>>
+
+    # Deconstruction  
+    <<id::16, message::binary-size(5), terminator::8>> = packet
+
+    assert id == ___
+    assert message == ___
+    assert terminator == ___
+  end
+end