howtorust - Interactive Rust Tutorial & Cheatsheet

An interactive command-line tool for learning Rust concepts through executable examples. Each chapter covers a fundamental Rust topic with examples progressing from beginner to advanced levels.

Features

• 8 Comprehensive Chapters covering core Rust concepts
• 75 Executable Examples organized by difficulty (beginner → intermediate → advanced)
• Comprehensive Commentary - every example includes detailed explanations with Rust Book references
• Interactive CLI with syntax-highlighted code display
• Professional Module Organization - all modules use subdirectory structure
• Real, Runnable Code - see the code, output, and commentary together
• Progressive Learning - examples build from simple to complex within each topic

Installation

From Source

# Clone or navigate to the project directory
cd rust_traits

# Install the binary
cargo install --path .

This will install the howtorust binary to your Cargo bin directory (usually ~/.cargo/bin/), which should already be in your PATH.

Verify Installation

howtorust --help

Usage

List All Available Chapters

howtorust --list

This displays all 8 chapters:

• ownership - Understanding Rust's ownership system
• modules - Packages, Crates, and Modules
• generics - Generic Types
• traits - Defining shared behavior
• lifetimes - Validating references
• errors - Error Handling with Result and Option
• closures - Anonymous functions
• iterators - Processing sequences of values

View a Chapter

howtorust ownership

This will:

1. Display all examples in the chapter grouped by difficulty
2. Enter an interactive menu where you can:
   • Type a number to view and run that example
   • Type list to see all examples again
   • Type quit to exit

Run a Specific Example

howtorust traits --example basic_trait

This directly displays and executes a specific example without the interactive menu.

Example Workflow

# 1. See what's available
howtorust --list

# 2. Explore ownership chapter
howtorust ownership

# 3. In the interactive menu, type a number (e.g., "1") to run an example
# 4. Type "list" to see all examples
# 5. Type "quit" to exit

# Or run a specific example directly
howtorust closures --example move_keyword

Chapter Overview

1. Understanding Ownership

Learn about Rust's ownership system, move semantics, borrowing, and references.

Examples: basic_ownership, clone_vs_move, function_ownership, borrowing_immutable, borrowing_mutable, multiple_references, reference_rules, slice_internals, dangling_reference_prevention

2. Packages, Crates, and Modules

Organize code with modules, understand visibility, and use the module system.

Examples: basic_module, nested_modules, use_keyword, use_as, pub_use, glob_imports, module_visibility, super_keyword, struct_privacy

3. Generic Types

Write flexible, reusable code with generic type parameters.

Examples: generic_function, generic_struct, multiple_generic_params, generic_methods, generic_enums, trait_bounds, where_clause, generic_associated_types, const_generics

4. Traits

Define shared behavior across types with trait definitions and implementations.

Examples: basic_trait, default_implementation, trait_bounds, multiple_trait_bounds, trait_objects, return_trait, derive_traits, associated_types, operator_overloading, supertraits

5. Lifetimes

Understand and use lifetime annotations to validate references.

Examples: basic_lifetime, lifetime_elision, struct_lifetimes, multiple_lifetimes, lifetime_bounds, method_lifetimes, static_lifetime, lifetime_subtyping, higher_ranked_trait_bounds

6. Error Handling

Handle errors gracefully with Result, Option, and custom error types.

Examples: basic_result, basic_option, unwrap_and_expect, question_mark_operator, option_combinators, result_combinators, custom_error_types, error_conversion, multiple_error_types, early_return_pattern

7. Closures

Use anonymous functions that capture their environment with different capture modes.

Examples: basic_closure, closure_type_inference, capturing_environment, fn_traits, move_keyword, closures_as_parameters, returning_closures, closure_caching, closure_composition

8. Iterators

Process sequences efficiently with iterator adapters and consumers.

Examples: basic_iteration, iterator_methods, consuming_adapters, chaining_iterators, fold_reduce, enumerate_zip, find_any_all, custom_iterator, lazy_evaluation, flat_map_flatten

Project Structure

rust_traits/
├── Cargo.toml              # Project configuration
├── README.md               # This file
├── MODULE_ORGANIZATION.md  # Guide to module organization patterns
└── src/
    ├── lib.rs              # Public API and module declarations
    ├── main.rs             # CLI interface with commentary display
    │
    ├── closures/           # 📁 All modules use subdirectory organization
    │   ├── mod.rs          # Module root
    │   ├── examples.rs     # Example definitions with commentary
    │   └── runners.rs      # Example execution
    ├── ownership/
    ├── packages_crates_modules/
    ├── generics/
    ├── traits/
    ├── lifetimes/
    ├── error_handling/
    └── iterators/

Module Organization:

• All 8 modules use subdirectory organization for consistency
• Each module contains mod.rs, examples.rs, and runners.rs
• Demonstrates professional Rust project structure
• See MODULE_ORGANIZATION.md for detailed patterns

Each module contains:

• Example definitions with code, description, and comprehensive commentary
• Commentary includes Rust Book references, explanations, and best practices
• Executable functions that demonstrate each concept
• A run_example() function to execute specific examples

Development

Building

cargo build --release

Running Without Installing

cargo run -- ownership
cargo run -- --list
cargo run -- traits --example basic_trait

Running Tests

cargo test

Shell Completion

To enable shell completion for the howtorust command, you can set up tab completion for your shell.

Bash

Add to your ~/.bashrc or ~/.bash_profile:

_howtorust_completion() {
    local cur prev chapters
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"

    chapters="ownership modules generics traits lifetimes errors closures iterators"

    case "${prev}" in
        howtorust)
            COMPREPLY=( $(compgen -W "--list --help ${chapters}" -- ${cur}) )
            return 0
            ;;
        --example)
            # Could be enhanced to suggest example names per chapter
            return 0
            ;;
        *)
            if [[ ${cur} == -* ]] ; then
                COMPREPLY=( $(compgen -W "--example --list --help" -- ${cur}) )
            else
                COMPREPLY=( $(compgen -W "${chapters}" -- ${cur}) )
            fi
            return 0
            ;;
    esac
}

complete -F _howtorust_completion howtorust

Then reload your shell:

source ~/.bashrc

Zsh

Add to your ~/.zshrc:

_howtorust() {
    local -a chapters
    chapters=(
        'ownership:Understanding Ownership'
        'modules:Packages, Crates, and Modules'
        'generics:Generic Types'
        'traits:Traits'
        'lifetimes:Lifetimes'
        'errors:Error Handling'
        'closures:Closures'
        'iterators:Iterators'
    )

    _arguments \
        '1: :->chapter' \
        '--list[List all chapters]' \
        '--help[Show help message]' \
        '--example[Run specific example]:example name:'

    case $state in
        chapter)
            _describe 'chapter' chapters
            ;;
    esac
}

compdef _howtorust howtorust

Then reload your shell:

source ~/.zshrc

Fish

Create ~/.config/fish/completions/howtorust.fish:

# Chapter completions
complete -c howtorust -n "__fish_is_first_token" -a "ownership" -d "Understanding Ownership"
complete -c howtorust -n "__fish_is_first_token" -a "modules" -d "Packages, Crates, and Modules"
complete -c howtorust -n "__fish_is_first_token" -a "generics" -d "Generic Types"
complete -c howtorust -n "__fish_is_first_token" -a "traits" -d "Traits"
complete -c howtorust -n "__fish_is_first_token" -a "lifetimes" -d "Lifetimes"
complete -c howtorust -n "__fish_is_first_token" -a "errors" -d "Error Handling"
complete -c howtorust -n "__fish_is_first_token" -a "closures" -d "Closures"
complete -c howtorust -n "__fish_is_first_token" -a "iterators" -d "Iterators"

# Flag completions
complete -c howtorust -n "__fish_is_first_token" -l list -s l -d "List all chapters"
complete -c howtorust -n "__fish_is_first_token" -l help -s h -d "Show help message"
complete -c howtorust -l example -d "Run specific example"

Fish will automatically load this on next shell start.

Testing Completion

After setting up completion, try:

howtorust <TAB>        # Should show chapter names and flags
howtorust own<TAB>     # Should complete to "ownership"
howtorust ownership --<TAB>  # Should show --example flag

Dependencies

• colored (2.1) - Terminal color output for syntax highlighting and UI

Learning Path

Recommended order for learning:

1. ownership - Start here! Understanding ownership is fundamental
2. modules - Learn how to organize code
3. errors - Essential for writing robust Rust programs
4. traits - Core abstraction mechanism
5. generics - Write flexible, reusable code
6. lifetimes - Advanced ownership concepts
7. closures - Functional programming in Rust
8. iterators - Efficient data processing

Tips

• Start with beginner examples in each chapter
• Run examples to see actual output
• Read the code carefully - it's designed to be instructive
• Experiment by modifying examples in the source code
• Use --list frequently to navigate between chapters

License

This project is designed for educational purposes.

Contributing

Feel free to:

• Add more examples to existing chapters
• Improve example descriptions
• Enhance syntax highlighting
• Add new chapters for other Rust concepts
• Fix bugs or improve documentation

Author

An educational project for learning and teaching Rust concepts interactively.