diff options
Diffstat (limited to 'js/baba-yaga/docs/README.md')
| -rw-r--r-- | js/baba-yaga/docs/README.md | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/js/baba-yaga/docs/README.md b/js/baba-yaga/docs/README.md new file mode 100644 index 0000000..30f8700 --- /dev/null +++ b/js/baba-yaga/docs/README.md @@ -0,0 +1,82 @@ +# Baba Yaga Documentation + +This directory contains comprehensive documentation for the Baba Yaga functional programming language. + +## Documentation Structure + +### Core Documentation + +- **[00_crash-course.md](./00_crash-course.md)** - Complete language overview for quick reference (ideal for LLMs and quick onboarding) +- **[01_functional.md](./01_functional.md)** - Functional programming concepts, higher-order functions, and function combinators +- **[02_data-structures.md](./02_data-structures.md)** - Lists, tables, and array programming operations +- **[03_pattern-matching.md](./03_pattern-matching.md)** - Pattern matching syntax, guards, and advanced patterns +- **[04_types.md](./04_types.md)** - Optional type system, runtime validation, and type inference +- **[05_recursion-and-composition.md](./05_recursion-and-composition.md)** - Recursive functions, mutual recursion, and function composition +- **[06_error-handling.md](./06_error-handling.md)** - Result types, assertions, validation, and error handling patterns +- **[07_gotchyas.md](./07_gotchyas.md)** - Common syntax pitfalls and strict requirements +- **[08_array-programming.md](./08_array-programming.md)** - Comprehensive guide to array programming operations +- **[09_js-interop.md](./09_js-interop.md)** - JavaScript interoperability and safe JS integration + +## Topic Coverage + +### Language Fundamentals +- **Syntax**: Variables, functions, data types, operators (00, 07) +- **Data Types**: Numbers, strings, booleans, lists, tables (00, 02) +- **Functions**: Anonymous functions, currying, partial application (00, 01) +- **Control Flow**: `when` expressions, pattern matching (00, 03) + +### Advanced Features +- **Pattern Matching**: Literals, wildcards, types, guards, multiple discriminants (03) +- **Type System**: Optional types, runtime validation, function signatures (04) +- **Error Handling**: Result types, assertions, validation patterns (06) +- **Recursion**: Simple, tail, and mutual recursion (05) + +### Functional Programming +- **Higher-Order Functions**: `map`, `filter`, `reduce` (01) +- **Function Combinators**: `flip`, `apply`, `pipe`, `compose` (01) +- **Array Programming**: Indexing, scanning, broadcasting, reshaping (02, 08) +- **Monadic Operations**: `flatMap` and data transformation (01, 02, 08) + +### Standard Library +- **Array Operations**: `scan`, `cumsum`, `at`, `where`, `take`, `drop`, `broadcast`, `zipWith`, `reshape` (02, 08) +- **Math Functions**: Arithmetic, trigonometry, random numbers (00) +- **String Processing**: Manipulation, formatting, validation (00) +- **Utilities**: Sorting, grouping, debugging, validation (00, 06) +- **JavaScript Interop**: Safe JS function calls, property access, type conversion (09) + +## Documentation Principles + +1. **Non-Duplicative**: Each concept is documented in one primary location with cross-references +2. **Comprehensive**: All language features and standard library functions are covered +3. **Hierarchical**: Start with crash course, then dive into specific topics +4. **Practical**: Includes working examples and common patterns +5. **Error-Aware**: Documents error cases and safe usage patterns + +## Reading Path + +### For New Users +1. [Crash Course](./00_crash-course.md) - Complete overview +2. [Functional Programming](./01_functional.md) - Core concepts +3. [Data Structures](./02_data-structures.md) - Working with data +4. [Pattern Matching](./03_pattern-matching.md) - Control flow + +### For Specific Topics +- **Array Processing**: [Data Structures](./02_data-structures.md) → [Array Programming](./08_array-programming.md) +- **Advanced Functions**: [Functional Programming](./01_functional.md) → [Recursion & Composition](./05_recursion-and-composition.md) +- **Robust Code**: [Error Handling](./06_error-handling.md) → [Types](./04_types.md) +- **Troubleshooting**: [Gotchas](./07_gotchyas.md) +- **JavaScript Integration**: [JavaScript Interop](./09_js-interop.md) + +### For LLMs and Quick Reference +- [Crash Course](./00_crash-course.md) provides complete context in a single document + +## Cross-References + +Documentation includes appropriate cross-references to avoid duplication: +- Pattern guards are detailed in [Pattern Matching](./03_pattern-matching.md), referenced in [Functional Programming](./01_functional.md) +- Function combinators are detailed in [Functional Programming](./01_functional.md), referenced in [Recursion & Composition](./05_recursion-and-composition.md) +- Array programming is covered in both [Data Structures](./02_data-structures.md) (overview) and [Array Programming](./08_array-programming.md) (comprehensive) +- Error handling patterns for array operations are in [Error Handling](./06_error-handling.md) +- JavaScript interop strategies and gotchas are in [JavaScript Interop](./09_js-interop.md), with basic gotchas in [Gotchas](./07_gotchyas.md) + +This structure ensures comprehensive coverage while maintaining clarity and avoiding redundancy. |