@booklib/skills 1.3.2 → 1.4.0

package/skills/programming-with-rust/examples/after.md

@@ -0,0 +1,107 @@
+# After: Programming with Rust
+
+The same service rewritten with idiomatic Rust — proper ownership, Result-based error handling, borrowing over cloning, iterator adapters, and trait bounds.
+
+```rust
+use std::collections::HashMap;
+use std::fmt;
+use std::sync::{Arc, Mutex};
+
+// Custom error type — callers can match on variants (Ch 12)
+#[derive(Debug)]
+pub enum ConfigError {
+    Io(std::io::Error),
+    UserNotFound(String),
+}
+
+impl fmt::Display for ConfigError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ConfigError::Io(e) => write!(f, "I/O error: {e}"),
+            ConfigError::UserNotFound(name) => write!(f, "user not found: {name}"),
+        }
+    }
+}
+
+impl std::error::Error for ConfigError {}
+
+impl From<std::io::Error> for ConfigError {
+    fn from(e: std::io::Error) -> Self {
+        ConfigError::Io(e)
+    }
+}
+
+// &str instead of String — works with both literals and String via deref coercion (Ch 4)
+// Returns Result — caller decides how to handle failure (Ch 12)
+fn load_config(path: &str) -> Result<String, ConfigError> {
+    let content = std::fs::read_to_string(path)?;  // ? propagates I/O error (Ch 12)
+    Ok(content)
+}
+
+// Borrows the map — no clone, caller retains ownership (Ch 8, 10)
+fn get_user<'a>(users: &'a HashMap<String, String>, name: &str) -> Result<&'a str, ConfigError> {
+    users
+        .get(name)
+        .map(|s| s.as_str())
+        .ok_or_else(|| ConfigError::UserNotFound(name.to_string()))
+}
+
+// Iterator adapters replace manual index loop (Ch 6)
+fn active_names(users: &[(String, bool)]) -> Vec<&str> {
+    users
+        .iter()
+        .filter(|(_, active)| *active)
+        .map(|(name, _)| name.as_str())
+        .collect()
+}
+
+// Safe shared counter with Arc<Mutex<T>> (Ch 19)
+fn make_counter() -> Arc<Mutex<u32>> {
+    Arc::new(Mutex::new(0))
+}
+
+fn increment(counter: &Arc<Mutex<u32>>) {
+    let mut count = counter.lock().expect("mutex poisoned");
+    *count += 1;
+}
+
+// Trait bound instead of concrete type — accepts anything Display (Ch 14, 17)
+fn print_item(item: &impl fmt::Display) {
+    println!("{item}");
+}
+
+fn main() -> Result<(), ConfigError> {
+    let config = load_config("config.toml")?;  // ? instead of unwrap (Ch 12)
+    println!("{config}");
+
+    let mut users = HashMap::new();
+    users.insert(String::from("alice"), String::from("admin"));
+
+    // Borrow users — still usable after the call (Ch 8)
+    let role = get_user(&users, "alice")?;
+    println!("{role}");
+    println!("{users:?}");  // still valid — was only borrowed
+
+    let items = vec![
+        (String::from("alice"), true),
+        (String::from("bob"), false),
+    ];
+    let names = active_names(&items);
+    println!("{names:?}");
+
+    let counter = make_counter();
+    increment(&counter);
+    println!("count: {}", counter.lock().unwrap());
+
+    Ok(())
+}
+```
+
+**Key improvements:**
+- `ConfigError` gives callers structured, matchable errors (Ch 12)
+- `?` replaces `.unwrap()` for clean error propagation (Ch 12)
+- `&str` / `&HashMap` parameters borrow instead of consuming (Ch 4, 8, 10)
+- Iterator adapters replace manual index loops (Ch 6)
+- `Arc<Mutex<T>>` replaces `unsafe static mut` for safe shared state (Ch 19)
+- `impl fmt::Display` trait bound instead of concrete `String` parameter (Ch 14, 17)
+- `main()` returns `Result` so errors surface cleanly (Ch 12)

package/skills/programming-with-rust/examples/before.md

@@ -0,0 +1,59 @@
+# Before: Programming with Rust
+
+A user service with common Rust anti-patterns — ownership misuse, panic-prone error handling, unnecessary cloning, and poor trait design.
+
+```rust
+use std::collections::HashMap;
+
+// No custom error type — callers can't match on failures
+fn load_config(path: String) -> String {  // takes owned String unnecessarily
+    std::fs::read_to_string(path).unwrap()  // panics on any I/O error
+}
+
+// Clones entire map just to read it
+fn get_user(users: HashMap<String, String>, name: String) -> String {
+    let users_copy = users.clone();  // unnecessary clone of the whole map
+    match users_copy.get(&name) {
+        Some(user) => user.clone(),
+        None => String::from("unknown"),  // silently returns fallback — hides missing users
+    }
+}
+
+// Accumulates with a manual loop instead of iterator adapters
+fn active_names(users: Vec<(String, bool)>) -> Vec<String> {
+    let mut result = Vec::new();
+    for i in 0..users.len() {
+        if users[i].1 == true {
+            result.push(users[i].0.clone());
+        }
+    }
+    result
+}
+
+// Shared state with no synchronization
+static mut COUNTER: u32 = 0;
+
+fn increment() {
+    unsafe {
+        COUNTER += 1;  // data race — undefined behavior in concurrent code
+    }
+}
+
+// Concrete type parameter instead of trait bound
+fn print_user(user: String) {
+    println!("{}", user);
+}
+
+fn main() {
+    let config = load_config(String::from("config.toml"));
+    println!("{}", config);
+
+    let mut users = HashMap::new();
+    users.insert(String::from("alice"), String::from("admin"));
+
+    // Moves users into get_user — can't use it after
+    let name = get_user(users, String::from("alice"));
+    println!("{}", name);
+    // println!("{:?}", users);  // would fail: users was moved
+}
+```

package/skills/programming-with-rust/references/api_reference.md

@@ -0,0 +1,152 @@
+# Programming with Rust — Chapter Reference
+
+All 23 chapters from Donis Marshall's "Programming with Rust" with key topics and priority levels.
+
+## Ch 1: Introduction to Rust
+**Key topics:** Functional programming, expression-oriented, pattern-oriented, safeness, ownership, lifetimes, fearless concurrency, zero-cost abstraction, Rust terminology, tools
+**Priority:** Foundation
+
+## Ch 2: Getting Started
+**Key topics:** Cargo, crates, library vs binary, `main` function, command-line arguments, comments, `rustup`
+**Priority:** Foundation
+
+## Ch 3: Variables
+**Key topics:** Immutability by default (`let` vs `let mut`), integer types, overflow behavior, floating point, boolean, char, pointers, references, operators
+**Priority:** Important — immutability by default is a key Rust safety idiom
+
+## Ch 4: Strings
+**Key topics:** `&str` (string slice, stack) vs `String` (heap-allocated, owned), deref coercion, `format!`, helpful string functions
+**Idiom:** Accept `&str` in function parameters — `String` derefs to `&str` automatically
+**Priority:** Important
+
+## Ch 5: Console
+**Key topics:** `println!`, positional/variable/named arguments, padding/alignment, `Display` trait, `Debug` trait, `format!`, `write!`
+**Priority:** Suggestion
+
+## Ch 6: Control Flow
+**Key topics:** `if` as expression, `while`, `for`/`in` (iterator-based), `loop`, `break`/`continue`, loop labels, `Iterator` trait
+**Idiom:** Use `for item in collection` over manual indexing; use iterator adapters over manual loops
+**Priority:** Important
+
+## Ch 7: Collections
+**Key topics:** Arrays (fixed-size, stack), slices, Vecs (heap, growable), multidimensional, `HashMap` (entry API, iteration, update)
+**Priority:** Important
+
+## Ch 8: Ownership
+**Key topics:** Stack vs heap, shallow vs deep copy, move semantics, borrow, copy semantics, `Clone` trait, `Copy` trait
+**Critical rules:**
+- Each value has exactly one owner
+- When owner goes out of scope, value is dropped
+- Move transfers ownership — old binding is invalid
+- `Copy` types (primitives) are copied instead of moved
+**Priority:** Critical
+
+## Ch 9: Lifetimes
+**Key topics:** Lifetime annotation syntax (`'a`), lifetime elision rules, function headers, complex lifetimes, `'static`, structs/methods with lifetimes, subtyping, anonymous lifetimes, generics and lifetimes
+**Idiom:** Rely on elision; annotate only when compiler cannot infer (multiple reference params with ambiguous output lifetime)
+**Priority:** Critical
+
+## Ch 10: References
+**Key topics:** Declaration, borrowing, dereferencing, comparing references, reference notation, mutability, limits to multiple borrowers
+**Critical rules:**
+- At any time: one `&mut T` OR any number of `&T` — never both
+- References must not outlive the referent
+**Priority:** Critical
+
+## Ch 11: Functions
+**Key topics:** Function definition, parameters, return values, `const fn`, nested functions, function pointers, function aliases
+**Priority:** Important
+
+## Ch 12: Error Handling
+**Key topics:** `Result<T, E>`, `Option<T>`, panics, `panic!` macro, handling panics, `.unwrap()`, `.expect()`, `?` operator, `match` on Result/Option, `.map()`, rich errors, custom error types
+**Critical rules:**
+- Library code: always `Result`, never panic
+- Use `?` for propagation, not `.unwrap()`
+- Define custom error types implementing `std::error::Error`
+- Implement `From<E>` for automatic `?` conversion
+**Priority:** Critical
+
+## Ch 13: Structures
+**Key topics:** Struct definition, alternate initialization, move semantics with structs, mutability, methods (`&self`, `&mut self`, `self`), associated functions (`new`), `impl` blocks, operator overloading, tuple structs, unit-like structs
+**Priority:** Important
+
+## Ch 14: Generics
+**Key topics:** Generic functions, trait bounds, `where` clause, generic structs, associated functions, generic enums, generic traits, explicit specialization
+**Idiom:** Use `where` clause for complex bounds; prefer narrowest possible bounds
+**Priority:** Important
+
+## Ch 15: Patterns
+**Key topics:** `let` destructuring, wildcards (`_`), complex patterns, ownership in patterns, irrefutable patterns, ranges, multiple patterns (`|`), control flow patterns, struct destructuring, function parameter patterns, `match` expressions, match guards
+**Idiom:** `match` is exhaustive — let the compiler enforce all cases; use `if let` for single-variant matches
+**Priority:** Important
+
+## Ch 16: Closures
+**Key topics:** Closure syntax, captured variables, closures as arguments/return values, `Fn` (immutable borrow), `FnMut` (mutable borrow), `FnOnce` (move/consume), `move` keyword, `impl` keyword for return types
+**Idiom:** Use `move` closures when passing to threads to transfer ownership of captured values
+**Priority:** Important
+
+## Ch 17: Traits
+**Key topics:** Trait definition, default functions, marker traits (`Send`, `Sync`), associated functions, associated types, extension methods, fully qualified syntax, supertraits, static dispatch (`impl Trait`), dynamic dispatch (`dyn Trait`), enums and traits
+**Critical rules:**
+- Prefer `impl Trait` (static, zero-cost) over `dyn Trait` (runtime overhead via vtable)
+- Use `dyn Trait` only when returning heterogeneous types or building plugin systems
+**Priority:** Critical
+
+## Ch 18: Threads 1
+**Key topics:** Synchronous vs asynchronous calls, `std::thread::spawn`, thread type, `Builder`, CSP (Communicating Sequential Process), async/sync/rendezvous channels (`mpsc`), `try_recv`, store example
+**Idiom:** Prefer message passing (channels) over shared state when possible
+**Priority:** Important
+
+## Ch 19: Threads 2
+**Key topics:** `Mutex<T>`, nonscoped mutex, mutex poisoning, `RwLock<T>`, condition variables (`Condvar`), atomic operations (`AtomicUsize`, etc.), store/load, fetch-and-modify, compare-and-exchange
+**Idiom:** Use `Arc<Mutex<T>>` for shared mutable state; `Arc<RwLock<T>>` for read-heavy workloads
+**Priority:** Critical
+
+## Ch 20: Memory
+**Key topics:** Stack vs heap allocation, static values, `Box<T>` (heap allocation), interior mutability pattern, `RefCell<T>` (runtime borrow checking, single-threaded), `OnceCell<T>` (lazy initialization)
+**Idiom:** Stack-allocate by default; use `Box` only when size is unknown at compile time or for recursive types
+**Priority:** Important
+
+## Ch 21: Macros
+**Key topics:** Tokens, declarative macros (`macro_rules!`), repetition, multiple matchers, procedural macros (derive, attribute, function-like), `#[derive(...)]`
+**Idiom:** Use `#[derive]` before writing manual `impl` blocks; write `macro_rules!` for repeated patterns
+**Priority:** Suggestion
+
+## Ch 22: Interoperability
+**Key topics:** FFI, `extern "C"`, `unsafe` blocks, `libc` crate, structs across FFI, `bindgen` (C → Rust), `cbindgen` (Rust → C)
+**Priority:** Suggestion (only when needed)
+
+## Ch 23: Modules
+**Key topics:** Module items, `pub` visibility, module files, `path` attribute, functions and modules, `crate`/`super`/`self` keywords, legacy module model
+**Idiom:** Organize by domain, not by type; keep `pub` surface minimal; use `pub(crate)` for internal-only APIs
+**Priority:** Important
+
+---
+
+## Priority Summary
+
+**Critical (understand deeply before writing any Rust)**
+- Ch 8: Ownership and move semantics
+- Ch 9: Lifetimes and elision
+- Ch 10: Borrowing rules (one `&mut` OR many `&`)
+- Ch 12: Error handling with Result, ?, custom errors
+- Ch 17: Trait dispatch (impl vs dyn)
+- Ch 19: Thread safety with Mutex/RwLock/Arc
+
+**Important (apply consistently)**
+- Ch 3: Immutability by default
+- Ch 4: `&str` vs `String`
+- Ch 6: Iterator-based loops
+- Ch 11: Function design
+- Ch 13: Structs and impl blocks
+- Ch 14: Generics and bounds
+- Ch 15: Exhaustive pattern matching
+- Ch 16: Closures and move semantics
+- Ch 18: Channels for concurrency
+- Ch 20: Stack vs heap, RefCell
+- Ch 23: Module visibility
+
+**Suggestion (apply when relevant)**
+- Ch 5: Formatting and Display/Debug
+- Ch 21: Macros and derive
+- Ch 22: FFI/interop

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
+}
+```