# 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.