@booklib/core 2.0.0

package/skills/programming-with-rust/references/practices-catalog.md

@@ -0,0 +1,335 @@
+# Programming with Rust — Practices Catalog
+
+Deep before/after examples for the most critical Rust idioms from each chapter group.
+
+---
+
+## Ownership: Borrow Instead of Clone (Ch 8)
+
+**Before:**
+```rust
+fn print_names(names: Vec<String>) {  // consumes the Vec
+    for name in names {
+        println!("{name}");
+    }
+}
+// names is gone after this call
+```
+**After:**
+```rust
+fn print_names(names: &[String]) {  // borrows a slice — Vec<String> derefs to &[String]
+    for name in names {
+        println!("{name}");
+    }
+}
+// caller keeps ownership
+```
+
+---
+
+## Ownership: Move Semantics (Ch 8)
+
+**Before:**
+```rust
+let s1 = String::from("hello");
+let s2 = s1;           // s1 is MOVED into s2
+println!("{s1}");      // compile error: s1 was moved
+```
+**After:**
+```rust
+let s1 = String::from("hello");
+let s2 = s1.clone();   // explicit deep copy — both valid
+println!("{s1} {s2}"); // both valid
+
+// Or: borrow instead of cloning
+let s3 = &s1;          // borrow — s1 still owns the data
+println!("{s1} {s3}");
+```
+
+---
+
+## References: Borrow Rules (Ch 10)
+
+```rust
+let mut data = vec![1, 2, 3];
+
+// OK: multiple immutable borrows
+let a = &data;
+let b = &data;
+println!("{a:?} {b:?}");
+
+// OK: one mutable borrow (after immutable borrows end)
+let c = &mut data;
+c.push(4);
+
+// COMPILE ERROR: can't have mutable + immutable borrow at same time
+// let d = &data;
+// let e = &mut data;  // error
+```
+
+---
+
+## Lifetimes: Elision vs Annotation (Ch 9)
+
+**Elision works (no annotation needed):**
+```rust
+fn first_word(s: &str) -> &str {  // compiler infers output lifetime = input lifetime
+    s.split_whitespace().next().unwrap_or("")
+}
+```
+
+**Annotation required (multiple inputs, ambiguous output):**
+```rust
+// Without annotation — compiler can't tell which input the output borrows from
+fn longer<'a>(s1: &'a str, s2: &'a str) -> &'a str {
+    if s1.len() > s2.len() { s1 } else { s2 }
+}
+```
+
+**Struct holding a reference — must annotate:**
+```rust
+struct Excerpt<'a> {
+    text: &'a str,  // struct can't outlive the string it borrows
+}
+```
+
+---
+
+## Error Handling: Result + ? (Ch 12)
+
+**Before:**
+```rust
+fn read_username() -> String {
+    let f = std::fs::File::open("username.txt").unwrap();
+    let mut s = String::new();
+    std::io::Read::read_to_string(&mut std::io::BufReader::new(f), &mut s).unwrap();
+    s
+}
+```
+**After:**
+```rust
+fn read_username() -> Result<String, std::io::Error> {
+    std::fs::read_to_string("username.txt")  // ? propagates automatically
+}
+```
+
+---
+
+## Error Handling: Custom Error Types (Ch 12)
+
+```rust
+use std::fmt;
+
+#[derive(Debug)]
+pub enum AppError {
+    Io(std::io::Error),
+    Parse(std::num::ParseIntError),
+    Custom(String),
+}
+
+impl fmt::Display for AppError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AppError::Io(e)     => write!(f, "I/O: {e}"),
+            AppError::Parse(e)  => write!(f, "parse: {e}"),
+            AppError::Custom(s) => write!(f, "{s}"),
+        }
+    }
+}
+
+impl std::error::Error for AppError {}
+
+// Enables ? to convert std::io::Error → AppError automatically
+impl From<std::io::Error> for AppError {
+    fn from(e: std::io::Error) -> Self { AppError::Io(e) }
+}
+
+impl From<std::num::ParseIntError> for AppError {
+    fn from(e: std::num::ParseIntError) -> Self { AppError::Parse(e) }
+}
+
+fn parse_port(s: &str) -> Result<u16, AppError> {
+    let port: i32 = s.parse()?;  // ParseIntError → AppError via From
+    if port < 1 || port > 65535 {
+        return Err(AppError::Custom(format!("invalid port: {port}")));
+    }
+    Ok(port as u16)
+}
+```
+
+---
+
+## Traits: Static vs Dynamic Dispatch (Ch 17)
+
+**Static dispatch — zero cost, preferred:**
+```rust
+// Monomorphized at compile time — no runtime overhead
+fn notify(item: &impl Summary) {
+    println!("Breaking news! {}", item.summarize());
+}
+
+// Equivalent with explicit generic:
+fn notify<T: Summary>(item: &T) {
+    println!("Breaking news! {}", item.summarize());
+}
+```
+
+**Dynamic dispatch — use only for heterogeneous collections or plugins:**
+```rust
+// Vtable lookup at runtime — small overhead, but enables mixed types
+fn notify_all(items: &[Box<dyn Summary>]) {
+    for item in items {
+        println!("{}", item.summarize());
+    }
+}
+```
+
+---
+
+## Traits: Implementing Standard Traits (Ch 17)
+
+```rust
+use std::fmt;
+
+#[derive(Debug, Clone, PartialEq)]  // derive common traits
+struct Point {
+    x: f64,
+    y: f64,
+}
+
+// Display for user-facing output
+impl fmt::Display for Point {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "({}, {})", self.x, self.y)
+    }
+}
+
+// From for ergonomic conversion
+impl From<(f64, f64)> for Point {
+    fn from((x, y): (f64, f64)) -> Self {
+        Point { x, y }
+    }
+}
+
+let p: Point = (1.0, 2.0).into();  // uses From impl
+println!("{p}");                    // uses Display
+println!("{p:?}");                  // uses Debug
+```
+
+---
+
+## Pattern Matching: Exhaustive match (Ch 15)
+
+**Before:**
+```rust
+let opt: Option<i32> = get_value();
+match opt {
+    Some(x) => println!("{x}"),
+    _ => {}  // silently ignores None — intent unclear
+}
+```
+**After:**
+```rust
+// if let for single-variant match
+if let Some(x) = get_value() {
+    println!("{x}");
+}
+
+// Exhaustive match when both branches matter
+match get_value() {
+    Some(x) => println!("got {x}"),
+    None    => println!("nothing"),
+}
+```
+
+---
+
+## Closures: move for Threads (Ch 16, 18)
+
+**Before:**
+```rust
+let name = String::from("Alice");
+let handle = std::thread::spawn(|| {
+    println!("{name}");  // error: closure may outlive name
+});
+```
+**After:**
+```rust
+let name = String::from("Alice");
+let handle = std::thread::spawn(move || {
+    println!("{name}");  // name is moved into the closure — safe
+});
+handle.join().unwrap();
+```
+
+---
+
+## Concurrency: Arc<Mutex<T>> (Ch 19)
+
+```rust
+use std::sync::{Arc, Mutex};
+use std::thread;
+
+fn main() {
+    let counter = Arc::new(Mutex::new(0u32));
+    let mut handles = vec![];
+
+    for _ in 0..10 {
+        let counter = Arc::clone(&counter);  // clone the Arc, not the data
+        let handle = thread::spawn(move || {
+            let mut num = counter.lock().expect("mutex poisoned");
+            *num += 1;
+        });
+        handles.push(handle);
+    }
+
+    for handle in handles {
+        handle.join().unwrap();
+    }
+
+    println!("Result: {}", *counter.lock().unwrap());  // 10
+}
+```
+
+---
+
+## Memory: RefCell for Interior Mutability (Ch 20)
+
+Use `RefCell<T>` when you need mutability inside an otherwise immutable value (single-threaded only):
+
+```rust
+use std::cell::RefCell;
+
+struct Cache {
+    data: RefCell<Option<String>>,  // interior mutability
+}
+
+impl Cache {
+    fn get(&self) -> String {
+        // borrow_mut even though &self is immutable
+        let mut data = self.data.borrow_mut();
+        if data.is_none() {
+            *data = Some(expensive_computation());
+        }
+        data.as_ref().unwrap().clone()
+    }
+}
+// For multi-threaded use, replace RefCell with Mutex
+```
+
+---
+
+## Modules: Visibility (Ch 23)
+
+```rust
+// lib.rs
+pub mod api {           // public module
+    pub struct Request { /* ... */ }    // public type
+    pub(crate) fn validate() { }       // crate-internal only
+    fn internal_helper() { }           // private to module
+}
+
+mod storage {           // private module — not part of public API
+    pub(super) fn save() { }  // accessible to parent module only
+}
+```

package/skills/programming-with-rust/scripts/review.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""
+review.py — Pre-analysis script for Programming with Rust reviews.
+Usage: python review.py <file.rs>
+
+Scans a Rust source file for anti-patterns from the book:
+unwrap misuse, unnecessary cloning, unsafe shared state, manual index loops,
+missing Result return types, static mut, and more.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+CHECKS = [
+    (
+        r"\.unwrap\(\)",
+        "Ch 12: .unwrap()",
+        "panics on failure in production paths — use ?, .expect(\"reason\"), or match",
+    ),
+    (
+        r"\.clone\(\)",
+        "Ch 8: .clone()",
+        "verify cloning is necessary — prefer borrowing (&T or &mut T) to avoid heap allocation",
+    ),
+    (
+        r"static\s+mut\s+\w+",
+        "Ch 19: static mut",
+        "data race risk — replace with Arc<Mutex<T>> or std::sync::atomic types",
+    ),
+    (
+        r"unsafe\s*\{",
+        "Ch 20: unsafe block",
+        "minimize unsafe scope; add a // SAFETY: comment explaining the invariant being upheld",
+    ),
+    (
+        r"for\s+\w+\s+in\s+0\s*\.\.\s*\w+\.len\(\)",
+        "Ch 6: Manual index loop",
+        "use iterator adapters: for item in &collection, or .iter().enumerate() if index is needed",
+    ),
+    (
+        r"\bpanic!\s*\(",
+        "Ch 12: panic!()",
+        "panics should be reserved for unrecoverable programmer errors — use Result<T, E> for recoverable failures",
+    ),
+    (
+        r"Box<dyn\s+\w+>",
+        "Ch 17: dyn Trait (dynamic dispatch)",
+        "prefer impl Trait for static dispatch (zero-cost) unless you need a heterogeneous collection",
+    ),
+    (
+        r"Rc\s*::\s*(new|clone)\b",
+        "Ch 19: Rc usage",
+        "Rc is not Send — if shared across threads, use Arc instead",
+    ),
+    (
+        r"\.expect\s*\(\s*\)",
+        "Ch 12: .expect() with empty string",
+        "add a meaningful reason: .expect(\"invariant: config is always loaded before this point\")",
+    ),
+]
+
+
+def scan(source: str) -> list[dict]:
+    findings = []
+    lines = source.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if stripped.startswith("//"):
+            continue
+        for pattern, label, advice in CHECKS:
+            if re.search(pattern, line):
+                findings.append({
+                    "line": lineno,
+                    "text": line.rstrip(),
+                    "label": label,
+                    "advice": advice,
+                })
+    return findings
+
+
+def sep(char="-", width=70) -> str:
+    return char * width
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python review.py <file.rs>")
+        sys.exit(1)
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+
+    if path.suffix.lower() != ".rs":
+        print(f"Warning: expected a .rs file, got '{path.suffix}' — continuing anyway")
+
+    source = path.read_text(encoding="utf-8", errors="replace")
+    findings = scan(source)
+    groups: dict[str, list] = {}
+    for f in findings:
+        groups.setdefault(f["label"], []).append(f)
+
+    print(sep("="))
+    print("PROGRAMMING WITH RUST — PRE-REVIEW REPORT")
+    print(sep("="))
+    print(f"File   : {path}")
+    print(f"Lines  : {len(source.splitlines())}")
+    print(f"Issues : {len(findings)} potential anti-patterns across {len(groups)} categories")
+    print()
+
+    if not findings:
+        print("  [OK] No common Rust anti-patterns detected.")
+        print()
+    else:
+        for label, items in groups.items():
+            print(sep())
+            print(f"  {label}  ({len(items)} occurrence{'s' if len(items) != 1 else ''})")
+            print(sep())
+            print(f"  Advice: {items[0]['advice']}")
+            print()
+            for item in items[:5]:
+                print(f"  line {item['line']:>4}:  {item['text'][:100]}")
+            if len(items) > 5:
+                print(f"  ... and {len(items) - 5} more")
+            print()
+
+    severity = (
+        "HIGH" if len(findings) >= 5
+        else "MEDIUM" if len(findings) >= 2
+        else "LOW" if findings
+        else "NONE"
+    )
+    print(sep("="))
+    print(f"SEVERITY: {severity}  |  Key chapters: Ch 8 (ownership), Ch 12 (errors), Ch 17 (traits), Ch 19 (concurrency), Ch 20 (memory)")
+    print(sep("="))
+
+
+if __name__ == "__main__":
+    main()