# Baba Yaga Tutorials

Welcome to the Baba Yaga tutorials! These tutorials will guide you through learning this functional programming language step by step.

## Getting Started

Start with the **Introduction** tutorial to learn the basics, then follow the numbered sequence for a complete learning path.

## Tutorial Sequence

### 🚀 **Beginner Level**

1. **[00_Introduction.md](00_Introduction.md)** - Basic concepts, functions, and pattern matching
2. **[01_Function_Calls.md](01_Function_Calls.md)** - Function calls without parentheses (juxtaposition)
3. **[02_Function_Composition.md](02_Function_Composition.md)** - Function composition with `via`, `compose`, and `pipe`
4. **[03_Table_Operations.md](03_Table_Operations.md)** - Working with tables and element-wise operations
5. **[04_Currying.md](04_Currying.md)** - Partial function application by default
6. **[05_Pattern_Matching.md](05_Pattern_Matching.md)** - Pattern matching with `when` expressions
7. **[06_Immutable_Tables.md](06_Immutable_Tables.md)** - Immutable table operations and functional programming
8. **[07_Function_References.md](07_Function_References.md)** - Function references with `@` symbol

### 🔧 **Intermediate Level**

9. **[08_Combinators.md](08_Combinators.md)** - Understanding the combinator-based architecture
10. **[09_Expression_Based.md](09_Expression_Based.md)** - Expression-based programming without explicit returns
11. **[10_Tables_Deep_Dive.md](10_Tables_Deep_Dive.md)** - Advanced table usage and data structures
12. **[11_Standard_Library.md](11_Standard_Library.md)** - Overview of available functions and combinators
13. **[12_IO_Operations.md](12_IO_Operations.md)** - Input/output operations and assertions
14. **[13_Error_Handling.md](13_Error_Handling.md)** - Error handling patterns and validation

### 🎯 **Advanced Level**

15. **[14_Advanced_Combinators.md](14_Advanced_Combinators.md)** - Advanced combinator patterns and optimization
16. **[15_Integration_Patterns.md](15_Integration_Patterns.md)** - External system integration and APIs
17. **[16_Best_Practices.md](16_Best_Practices.md)** - Best practices and coding guidelines

## Key Concepts Covered

- **Functional Programming**: Pure functions, immutability, composition
- **Pattern Matching**: `when` expressions for conditional logic
- **Tables**: Immutable data structures with functional operations
- **Combinators**: Higher-order functions for data transformation
- **IO Operations**: Input/output, assertions, and event handling
- **Error Handling**: Functional error patterns and validation
- **Integration**: External system integration patterns
- **Best Practices**: Operator spacing, syntax guidelines, and code organization

## REPL Integration Documentation

For comprehensive integration patterns and harness architecture documentation, see the **[REPL Documentation](../docs/repl/scripting-lang/0.0.1/repl.js.html)** which is generated directly from the REPL source code and contains extensive JSDoc comments about:

- Architecture overview and TEA-inspired patterns
- Harness integration examples
- Adapter pattern implementation
- State management and versioning
- Error handling and recovery
- Command routing strategies
- Complete integration examples

## Quick Reference

### Essential Syntax

```plaintext
/* Function definition */
function_name : param1 param2 -> expression;

/* Function application */
function_name arg1 arg2;

/* Pattern matching */
when value is
  pattern1 then result1
  pattern2 then result2
  _ then default_result;

/* Table literals */
{key1: value1, key2: value2};

/* Function references */
map @function_name collection;

/* IO operations */
..out "Hello, World!";
..assert "test" 5 = 5;
..emit "event" data;
..listen "event" handler;
```

### Best Practices

- ✅ **Use spaces around binary operators**: `5 - 3`, `5 + 3`, `5 * 3`
- ✅ **Unary minus works without parentheses**: `-5`, `f -5`
- ✅ **Use parentheses for explicit grouping**: `(-5)`, `(5 + 3) * 2`
- ✅ **Follow functional conventions**: Immutable data, pure functions
- ✅ **Keep functions focused**: Single responsibility principle
- ✅ **Use descriptive names**: Clear intent and purpose
- ✅ **Handle errors explicitly**: Pattern matching over exceptions

## Running Examples

To run examples from these tutorials:

1. Create a `.txt` or `.baba` file with the example code
2. Run: `node lang.js your_file.txt`

Example:
```bash
# Create test.txt with tutorial code
echo "result : 5 - 3;" > test.txt

# Run the example
node lang.js test.txt
```

## File Extensions

Baba Yaga files should use either the `.txt` file extension, or the `.baba` extension.

## Need Help?

- Check the [main README](../README.md) for language overview
- Review [Best Practices](16_Best_Practices.md) for syntax guidelines
- Run the test suite: `./run_tests.sh` to see working examples
- Explore [Advanced Combinators](14_Advanced_Combinators.md) for complex patterns
- Check [Integration Patterns](15_Integration_Patterns.md) for external system integration

Happy learning! 🚀