Appendix E: Learning Resources

“Learning never stops. The best programmers are eternal students, always curious, always growing.” - Noah Gift

Current Status

⚠️ Important: Ruchy is an experimental language in early development. Most traditional learning resources don’t exist yet.

Actual Available Resources

Official Sources

This Book: You’re reading it - the primary documentation for Ruchy
GitHub Repository: https://github.com/paiml/ruchy - The source code and compiler
Ruchy Book Repository: https://github.com/paiml/ruchy-book - This book’s source
Ruchy Syntax Tools: https://github.com/paiml/ruchy-syntax-tools - Professional editor support
Rosetta Ruchy: https://github.com/paiml/rosetta-ruchy - Cross-language benchmarks and learning examples

What Actually Exists

The Ruchy Compiler: A transpiler from Ruchy to Rust
This Documentation: The book you’re currently reading
Example Code: Some examples in the compiler repository
Grammar Specification: Located at docs/architecture/grammer.md in the compiler repo
Professional Editor Support: Comprehensive syntax highlighting for 9+ platforms
VS Code Extension: Full development experience with IntelliSense and snippets
Cross-Language Benchmarks: Polyglot performance comparisons and code translations
Learning Examples: Side-by-side implementations in Ruchy, Rust, Python, JavaScript, Go, and C

Learning Approach

Since Ruchy transpiles to Rust, the best way to understand Ruchy is to:

0. Explore Cross-Language Examples (Recommended First Step)

The Rosetta Ruchy project provides the fastest way to understand Ruchy through side-by-side comparisons:

# Clone the benchmark and examples repository
git clone https://github.com/paiml/rosetta-ruchy
cd rosetta-ruchy

# Explore cross-language implementations
ls examples/
# Shows same algorithms implemented in:
# - Ruchy (.ruchy files)
# - Rust (.rs files)  
# - Python (.py files)
# - JavaScript (.js files)
# - Go (.go files)
# - C (.c files)

Key Benefits:

✅ Performance Comparisons - See how Ruchy achieves Rust-like performance
✅ Syntax Translation - Learn Ruchy by comparing to languages you know
✅ Real Examples - Practical algorithms, not toy programs
✅ Benchmark Data - Empirical evidence of zero-cost abstractions
✅ Advanced Features - Formal verification and AST analysis tools

Learning Strategy:

Start with a language you know (Python, JavaScript, etc.)
Compare the equivalent Ruchy implementation
Run both versions and compare performance
Study the generated Rust code to understand transpilation

# Example: Compare sorting algorithms
cd examples/sorting
cat quicksort.py    # Familiar Python version
cat quicksort.ruchy # Equivalent Ruchy version
cat quicksort.rs    # Generated Rust code

# Run performance comparison
./benchmark.sh     # Shows performance across all languages

1. Learn Rust First

Ruchy compiles to Rust, so understanding Rust is essential:

The Rust Programming Language Book: https://doc.rust-lang.org/book/
Rust by Example: https://doc.rust-lang.org/rust-by-example/
Rustlings: https://github.com/rust-lang/rustlings

2. Study the Ruchy Grammar

Read the grammar specification to understand Ruchy’s syntax:

# In the Ruchy compiler repository
cat docs/architecture/grammer.md

3. Experiment with Transpilation

See how Ruchy code becomes Rust:

# Write Ruchy code
echo 'fun main() { println("Hello") }' > test.ruchy

# Transpile to Rust
ruchy transpile test.ruchy -o test.rs

# Examine the generated Rust code
cat test.rs

Development Tools & Editor Setup

Professional Editor Support

The Ruchy Syntax Tools project provides comprehensive language support across all major development platforms:

# Install syntax highlighting support
npm install ruchy-syntax-tools

Supported Editors & Platforms

VS Code - Complete extension with IntelliSense, themes, snippets
TextMate - Native macOS editor support
Tree-sitter - High-performance parsing for modern editors
Monaco - Web-based VS Code engine
CodeMirror 6 - Modern web text editor
highlight.js - Web application syntax highlighting
Prism.js - Lightweight web syntax highlighter
Rouge - Ruby-based highlighter (Jekyll, GitLab)
Pygments - Python-based highlighter (GitHub, Sphinx)

VS Code Setup (Recommended)

Install the complete Ruchy development experience:

# Install via VS Code marketplace
code --install-extension ruchy-syntax-tools

# Or install manually from GitHub
git clone https://github.com/paiml/ruchy-syntax-tools
cd ruchy-syntax-tools/vscode
code --install-extension ruchy-*.vsix

Features:

✅ Syntax Highlighting - Full language support with proper tokenization
✅ IntelliSense - Code completion and error detection
✅ Code Snippets - Quick insertion of common Ruchy patterns
✅ Theme Integration - Optimized for popular VS Code themes
✅ Error Highlighting - Real-time syntax error detection

Web Development Integration

For documentation sites and online tutorials:

<!-- highlight.js integration -->
<link rel="stylesheet" href="node_modules/ruchy-syntax-tools/highlight/ruchy.css">
<script src="node_modules/ruchy-syntax-tools/highlight/ruchy.js"></script>
<script>hljs.highlightAll();</script>

<!-- Prism.js integration -->
<link href="node_modules/ruchy-syntax-tools/prism/ruchy.css" rel="stylesheet">
<script src="node_modules/ruchy-syntax-tools/prism/ruchy.js"></script>

Performance: Average syntax processing time of 1.8ms with 85%+ language construct coverage across all platforms.

Since Ruchy builds on Rust concepts, these resources are relevant:

Rust Resources

Official Rust Documentation: https://www.rust-lang.org/learn
Rust Community: https://www.rust-lang.org/community
Rust Forum: https://users.rust-lang.org/
Rust Subreddit: https://reddit.com/r/rust

Similar Language Projects

Learning about other experimental languages can provide context:

Zig: A language focused on simplicity and performance
V: A simple language for building software
Nim: A statically typed compiled language

Contributing to Ruchy

The best way to learn is by contributing:

How to Contribute

Report Issues: Find bugs or suggest improvements
Submit PRs: Fix issues or add features
Improve Documentation: Help make this book better
Write Examples: Create example programs

Development Resources

Rust Compiler Development: Understanding how compilers work
Language Design: Study programming language theory
Parser Combinators: Learn about parsing techniques

What Doesn’t Exist Yet

Be aware that these common resources do not exist for Ruchy:

Not Available

❌ Official website (ruchy.org doesn’t exist)
❌ Package registry (no packages.ruchy.org)
❌ Online playground (no play.ruchy.org)
❌ IDE extensions or plugins
❌ Video courses or tutorials
❌ Community forums specific to Ruchy
❌ Books (other than this one)
❌ Certification programs
❌ Commercial training

Future Plans

These resources are planned but not yet available:

Planned Resources

Official binary releases
Language server protocol (LSP) implementation
VS Code extension
Online playground
More comprehensive examples
Video tutorials

Getting Help

Current Support Channels

GitHub Issues: https://github.com/paiml/ruchy/issues - Report bugs or ask questions
Source Code: Study the compiler implementation for deep understanding

Understanding Error Messages

Since Ruchy transpiles to Rust, you’ll often see Rust error messages:

Transpilation errors from Ruchy compiler
Rust compilation errors from rustc
Runtime errors from the generated binary

Recommended Learning Path

Week 1-2: Learn Rust basics if you haven’t already
Week 3: Study this Ruchy book thoroughly
Week 4: Read the Ruchy grammar specification
Week 5: Write simple Ruchy programs and study the transpiled Rust
Week 6+: Contribute to the Ruchy compiler or documentation

Important Reminders

Experimental: Ruchy is experimental and changing
Limited Resources: Most traditional learning resources don’t exist
Rust Knowledge Required: Understanding Rust is essential
Community Building: You’re an early adopter helping build the community

Learning Ruchy at this stage means being a pioneer. You’re not just learning a language; you’re helping shape it. The lack of traditional resources is an opportunity to contribute and create the resources future learners will use.

Remember: Every expert was once a beginner, and every established language was once experimental.

The Ruchy Programming Language