Implement comprehensive struct utility library with injection and transformation

[rjrodger]

Summary

This PR implements a complete, multi-language struct utility library with support for deep value injection, path-based access, type validation, and recursive tree transformation. The implementation achieves functional parity across TypeScript (canonical), JavaScript, Python, Go, PHP, Ruby, Lua, and partial implementations in Java and C++.

Key Changes

Core Library Implementation (Ruby)

• New utility functions: Added 40+ utility functions including getdef, size, slice, pad, getelem, flatten, filter, delprop, join, joinurl, jsonify, replace, and tree traversal helpers
• Injection system: Implemented complete Injection class and inject() function with support for backtick expression resolution, metadata injection, and custom handlers
• Path-based access: Enhanced getpath() to support complex path expressions with meta-path syntax, escape sequences, and injection definitions
• Tree walking: Redesigned walk() function with before/after callbacks, depth limiting, and proper node traversal
• Type system: Added typename() function with bitfield type constants (T_any, T_noval, T_boolean, T_decimal, T_integer, T_number, T_string, T_function, T_symbol, T_null, T_list, T_map, T_instance, T_scalar, T_node)
• Mode constants: Added M_KEYPRE, M_KEYPOST, M_VAL bitfield constants with MODENAME mapping for injection phases

Enhanced Existing Functions

• clone(): Now handles UNDEF sentinel properly
• isempty(): Extended to recognize UNDEF as empty
• items(): Added optional apply function parameter; list indices now converted to strings for consistency
• stringify(): Improved handling of UNDEF, added pretty-printing support, fixed maxlen logic
• pathify(): Enhanced with better UNDEF handling and fallback logic
• merge(): Complete rewrite with depth limiting and proper node merging semantics
• haskey(): Simplified signature to use UNDEF sentinel instead of variable args

Constants and Sentinels

• Added UNDEF = Object.new.freeze as unique undefined marker
• Added mode constants: M_KEYPRE = 1, M_KEYPOST = 2, M_VAL = 4
• Added MAXDEPTH = 32 for recursion limiting
• Added MODENAME and PLACEMENT hashes for mode introspection

Test Infrastructure

• Updated test suite with 75+ passing tests
• Enhanced deep_equal() helper for robust comparison
• Added support for new utility functions in test runner
• Improved test organization and assertion clarity

Cross-Language Consistency

• PHP: Updated getpath() signature to match canonical (removed current parameter)
• Python: Added MODENAME constant for consistency
• Documentation: Added comprehensive REPORT.md documenting API parity across all language implementations

Notable Implementation Details

1. Injection System: The Injection class maintains state during recursive tree traversal, supporting three phases (key:pre, value, key:post) for flexible transformation hooks.

2. Path Resolution: getpath() now supports:

   • Meta-path syntax: key$=value or key$~pattern
   • Escape sequences: $BT (backtick), $DS (dollar sign)
   • Special references: $KEY, $GET:path, $REF:path, $META:path
   • Relative paths with .. (empty string) for parent traversal

3. Backtick Injection: _injectstr() resolves backtick expressions in strings, supporting both full-string (\path`) and partial (prefix`path`suffix`) injection with fallback to empty string for missing keys.

4. Merge Semantics: merge() implements proper node merging where matching node types (map-to-map, list-to-list) merge recursively, while non-nodes override directly.

5. Type Bitfield: typify() returns a bitfield integer where each bit represents a

https://claude.ai/code/session_01QkN2u1cRavoxb7UebdMcDr