docs: modernize examples to unquoted macro attrs, infallible sharded API, optional map_error

- `struct_method`/`expires_per_key`: unquoted `convert` blocks; `struct_method` adds `companions_vis`
- `kitchen_sink`: unquoted `create` expressions
- `disk`: unquoted `map_error` closure plus a `From<RedbCacheError>` path with no `map_error`
- `sharded`: correct the mislabeled `.expect` on the `load_record` Result

Author: jaemk

examples/disk.rs

@@ -21,16 +21,34 @@ enum ExampleError {
 // When the macro constructs your RedbCache instance (the default disk engine),
 // the default cache files will be stored
 // under $system_cache_dir/<exe>_cached_disk_cache/
+//
+// `map_error` is an unquoted closure here; the legacy quoted-string form
+// (`map_error = r##"|e| ..."##`) is still accepted.
 #[concurrent_cached(
     disk = true,
     ttl_secs = 30,
-    map_error = r##"|e| ExampleError::DiskError(format!("{:?}", e))"##
+    map_error = |e| ExampleError::DiskError(format!("{e:?}"))
 )]
 fn cached_sleep_secs(secs: u64) -> Result<(), ExampleError> {
     std::thread::sleep(Duration::from_secs(secs));
     Ok(())
 }
 
+// `map_error` is now optional: when the function's error type implements
+// `From<RedbCacheError>`, the macro converts store errors automatically via
+// `Into::into`, so no `map_error` closure is needed.
+impl From<cached::RedbCacheError> for ExampleError {
+    fn from(e: cached::RedbCacheError) -> Self {
+        ExampleError::DiskError(format!("{e:?}"))
+    }
+}
+
+#[concurrent_cached(disk = true, ttl_secs = 30)]
+fn cached_sleep_secs_from(secs: u64) -> Result<(), ExampleError> {
+    std::thread::sleep(Duration::from_secs(secs));
+    Ok(())
+}
+
 fn main() {
     print!("1. first sync call with a 2 seconds sleep...");
     io::stdout().flush().unwrap();
@@ -64,4 +82,10 @@ fn main() {
     }
     cache.flush().unwrap(); // one durable commit persisting the cheap writes above
     println!("flushed 3 cheap writes to disk in a single durable commit");
+
+    // No `map_error` needed: ExampleError: From<RedbCacheError> handles conversion.
+    print!("call without map_error (From<RedbCacheError>) ...");
+    io::stdout().flush().unwrap();
+    cached_sleep_secs_from(1).unwrap();
+    println!("done");
 }

examples/expires_per_key.rs

@@ -48,7 +48,7 @@ impl Expires for MyValue {
 // Add `max_size = N` to switch to an LRU-bounded ExpiringLruCache.
 // `key`/`convert` narrow the cache key to just user_id so expiry_offset_ms only
 // influences the token's lifetime, not which cache slot it occupies.
-#[cached(expires = true, key = "u64", convert = "{ user_id }")]
+#[cached(expires = true, key = "u64", convert = { user_id })]
 fn fetch_token(user_id: u64, expiry_offset_ms: u64) -> MyValue {
     println!("  -> [fetch_token] generating new token for user {user_id}...");
     let n = CALL_N.fetch_add(1, Ordering::Relaxed);
@@ -72,7 +72,7 @@ fn get_session_token(expiry_offset_ms: u64) -> MyValue {
 // `expires = true` composes with a `Result` return: only the `Ok(MyValue)` is
 // cached (and expires per-value via `Expires`); an `Err` is never cached, so a
 // failing call always re-executes.
-#[cached(expires = true, key = "u64", convert = "{ user_id }")]
+#[cached(expires = true, key = "u64", convert = { user_id })]
 fn fetch_token_result(user_id: u64, expiry_offset_ms: u64, fail: bool) -> Result<MyValue, String> {
     println!("  -> [fetch_token_result] generating token for user {user_id} (fail={fail})...");
     if fail {
@@ -88,7 +88,7 @@ fn fetch_token_result(user_id: u64, expiry_offset_ms: u64, fail: bool) -> Result
 // `expires = true` composes with an `Option` return: only `Some(MyValue)` is
 // cached (and expires per-value); a `None` is never cached, so a miss keeps
 // re-executing until a `Some` is produced.
-#[cached(expires = true, key = "u64", convert = "{ user_id }")]
+#[cached(expires = true, key = "u64", convert = { user_id })]
 fn fetch_token_option(user_id: u64, expiry_offset_ms: u64, found: bool) -> Option<MyValue> {
     println!("  -> [fetch_token_option] generating token for user {user_id} (found={found})...");
     if !found {

examples/kitchen_sink.rs

@@ -29,7 +29,7 @@ fn fib(n: u32) -> u32 {
 // Note that the cache key type is a tuple of function argument types.
 #[cached(
     ty = "UnboundCache<u32, u32>",
-    create = "{ UnboundCache::builder().capacity(50).build().unwrap() }"
+    create = UnboundCache::builder().capacity(50).build().unwrap()
 )]
 fn fib_specific(n: u32) -> u32 {
     if n == 0 || n == 1 {
@@ -50,7 +50,7 @@ fn slow(a: u32, b: u32) -> u32 {
 // Note that the cache key type is a `String` created from the borrow arguments
 #[cached(
     ty = "LruCache<String, usize>",
-    create = "{ LruCache::builder().max_size(100).build().unwrap() }",
+    create = LruCache::builder().max_size(100).build().unwrap(),
     convert = r#"{ format!("{a}{b}") }"#
 )]
 fn keyed(a: &str, b: &str) -> usize {
@@ -137,7 +137,7 @@ impl<K: Hash + Eq, V> Cached<K, V> for MyCache<K, V> {
 #[cached(
     name = "CUSTOM",
     ty = "MyCache<u32, ()>",
-    create = "{ MyCache::with_capacity(50) }"
+    create = MyCache::with_capacity(50)
 )]
 fn custom(n: u32) {
     if n == 0 {

examples/sharded.rs

@@ -92,8 +92,8 @@ fn main() {
     // Result: only Ok is cached
     let r1 = load_record(42);
     let r2 = load_record(42);
-    assert_eq!(r1.as_deref().expect("infallible"), "record_42");
-    assert_eq!(r2.as_deref().expect("infallible"), "record_42");
+    assert_eq!(r1.as_deref().expect("load_record returns Ok"), "record_42");
+    assert_eq!(r2.as_deref().expect("load_record returns Ok"), "record_42");
     println!("load_record(42) = {:?} (cached)", r1);
 
     // Option: None is NOT cached by default; the function re-executes each time

examples/struct_method.rs

@@ -54,10 +54,19 @@ impl Worker {
     /// `convert` folds `self.id` into the key so different instances
     /// do not share cache entries.
     ///
-    /// A `compute_no_cache` sibling is also generated (same visibility)
-    /// for calling the raw computation without touching the cache.
+    /// A `compute_no_cache` sibling is also generated for calling the raw
+    /// computation without touching the cache. Its visibility defaults to the
+    /// method's own; `companions_vis = "pub(crate)"` overrides it independently.
     /// The `_prime_cache` companion is NOT generated for `in_impl` methods.
-    #[cached(in_impl = true, key = "(u64, u32)", convert = "{ (self.id, n) }")]
+    ///
+    /// `convert` is an unquoted block here (`{ (self.id, n) }`); the legacy
+    /// quoted-string form (`convert = "{ (self.id, n) }"`) is still accepted.
+    #[cached(
+        in_impl = true,
+        key = "(u64, u32)",
+        convert = { (self.id, n) },
+        companions_vis = "pub(crate)"
+    )]
     fn compute(&self, n: u32) -> u32 {
         println!("  [miss] Worker(id={}) compute(n={n})", self.id);
         self.factor * n
@@ -128,7 +137,7 @@ trait Processor {
 
 /// Cached computation for any `Processor`-like object.
 /// Key: `(id, input)`.  `factor` is only used on a cache miss.
-#[cached(key = "(u64, u32)", convert = "{ (id, input) }")]
+#[cached(key = "(u64, u32)", convert = { (id, input) })]
 fn processor_compute(id: u64, factor: u32, input: u32) -> u32 {
     println!("  [miss] processor_compute(id={id}, factor={factor}, input={input})");
     input * factor