ci: update publish workflow

.github/workflows/ci.yml

@@ -9,112 +9,30 @@ env:
   RUSTFLAGS: --deny warnings
   RUSTDOCFLAGS: --deny warnings
 jobs:
-  # Run tests
+  build-and-test:
-  test:
-    name: Tests
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    env:
+      SCCACHE_GHA_ENABLED: "true"
+      RUSTC_WRAPPER: "sccache"
     steps:
-      - name: Checkout repository
+      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
-      - name: Install Rust toolchain
+      - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install --no-install-recommends \
-            libasound2-dev libudev-dev libwayland-dev \
-            libxkbcommon-dev
-      - name: Populate target directory from cache
-        uses: Leafwing-Studios/cargo-cache@v2
         with:
-          sweep-cache: true
+          toolchain: stable
+          components: clippy, rustfmt
+      - name: Run sccache-cache
+        uses: mozilla-actions/sccache-action@v0.0.9
       - name: Install cargo-nextest
-        run: cargo install cargo-nextest --locked
+        uses: taiki-e/install-action@cargo-nextest
-      - name: Run tests with nextest
+      - name: Run Clippy
+        run: cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
+      - name: Run formatting
+        run: cargo fmt --all --check
+      - name: Run Tests
         run: |
-          cargo nextest run \
+          cargo nextest run --all-features --all-targets
-            --all-features \
+          cargo test --locked --workspace --all-features --doc
-            --all-targets
+      - name: Check Documentation
-          # Workaround for https://github.com/rust-lang/cargo/issues/6669
+        run: cargo doc --locked --workspace --all-features --document-private-items --no-deps
-          cargo test \
-            --locked \
-            --workspace \
-            --all-features \
-            --doc
-  # Run clippy lints
-  clippy:
-    name: Clippy
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          components: clippy
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install --no-install-recommends \
-            libasound2-dev libudev-dev libwayland-dev \
-            libxkbcommon-dev
-      - name: Populate target directory from cache
-        uses: Leafwing-Studios/cargo-cache@v2
-        with:
-          sweep-cache: true
-      - name: Run clippy lints
-        run: |
-          cargo clippy \
-            --locked \
-            --workspace \
-            --all-features \
-            -- \
-            --deny warnings
-  # Check formatting
-  format:
-    name: Format
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          components: rustfmt
-      - name: Run cargo fmt
-        run: |
-          cargo fmt \
-            --all \
-            -- \
-            --check
-  # Check documentation
-  doc:
-    name: Docs
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install --no-install-recommends \
-            libasound2-dev libudev-dev libwayland-dev \
-            libxkbcommon-dev
-      - name: Populate target directory from cache
-        uses: Leafwing-Studios/cargo-cache@v2
-        with:
-          sweep-cache: true
-      - name: Check documentation
-        run: |
-          cargo doc \
-            --locked \
-            --workspace \
-            --all-features \
-            --document-private-items \
-            --no-deps

.github/workflows/publish.yml

@@ -15,10 +15,9 @@ on:
 jobs:
   audit:
     name: Audit
-    runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions-rust-lang/audit@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -28,11 +27,17 @@ jobs:
       - audit
     runs-on: ubuntu-latest
     timeout-minutes: 25
+    env:
+      SCCACHE_GHA_ENABLED: "true"
+      RUSTC_WRAPPER: "sccache"
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
       - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          components: clippy, rustfmt
+      - name: Run sccache-cache
+        uses: mozilla-actions/sccache-action@v0.0.9
       - name: cargo-release Cache
         id: cargo_release_cache
         uses: actions/cache@v4
@@ -60,11 +65,4 @@ jobs:
         # to the tag while building, which is a detached head
 
         run: |
-          cargo release \
+          cargo release publish --workspace --all-features --allow-branch HEAD --no-confirm --no-verify --execute
-            publish \
-            --workspace \
-            --all-features \
-            --allow-branch HEAD \
-            --no-confirm \
-            --no-verify \
-            --execute

Cargo.lock

@@ -50,7 +50,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
 
 [[package]]
 name = "filecaster"
-version = "0.2.0"
+version = "0.2.3"
 dependencies = [
  "filecaster-derive",
  "merge",
@@ -58,11 +58,12 @@ dependencies = [
  "serde_json",
  "tempfile",
  "toml",
+ "trybuild",
 ]
 
 [[package]]
 name = "filecaster-derive"
-version = "0.2.0"
+version = "0.2.3"
 dependencies = [
  "claims",
  "filecaster",
@@ -87,6 +88,12 @@ dependencies = [
  "wasi",
 ]
 
+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
 [[package]]
 name = "hashbrown"
 version = "0.15.4"
@@ -281,6 +288,12 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "target-triple"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ac9aa371f599d22256307c24a9d748c041e548cbf599f35d890f9d365361790"
+
 [[package]]
 name = "tempfile"
 version = "3.20.0"
@@ -294,6 +307,15 @@ dependencies = [
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "termcolor"
+version = "1.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06794f8f6c5c898b3275aebefa6b8a1cb24cd2c6c79397ab15774837a0bc5755"
+dependencies = [
+ "winapi-util",
+]
+
 [[package]]
 name = "toml"
 version = "0.9.2"
@@ -333,6 +355,21 @@ version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fcc842091f2def52017664b53082ecbbeb5c7731092bad69d2c63050401dfd64"
 
+[[package]]
+name = "trybuild"
+version = "1.0.110"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32e257d7246e7a9fd015fb0b28b330a8d4142151a33f03e6a497754f4b1f6a8e"
+dependencies = [
+ "glob",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "target-triple",
+ "termcolor",
+ "toml",
+]
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.18"
@@ -348,6 +385,15 @@ dependencies = [
  "wit-bindgen-rt",
 ]
 
+[[package]]
+name = "winapi-util"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf221c93e13a30d793f7645a0e7762c55d169dbb0a49671918a2319d289b10bb"
+dependencies = [
+ "windows-sys 0.59.0",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.59.0"

Cargo.toml

@@ -3,8 +3,8 @@ resolver = "2"
 members = ["filecaster", "filecaster-derive"]
 
 [workspace.dependencies]
-filecaster-derive = { path = "filecaster-derive" }
+filecaster-derive = { version = "0.2", path = "filecaster-derive" }
-serde = { version = "1.0", features = ["derive"] }
+serde = { version = "1.0", features = ["derive"], default-features = false }
 merge = "0.2"
 # dev-dependencies
 filecaster = { path = "filecaster" }
@@ -12,6 +12,7 @@ claims = "0.8"
 serde_json = "1.0"
 tempfile = "3.10"
 toml = "0.9"
+trybuild = "1.0"
 
 [workspace.lints.clippy]
 pedantic = "warn"

README.md

@@ -5,45 +5,71 @@ Procedural macro to derive configuration from files, with optional merging capab
 ## Features
 
 - **Derive Configuration:** Easily load configuration from files into your Rust structs.
-- **Default Values:** Specify default values for struct fields using the `#[default = "..."]` attribute.
+- **Default Values:** Specify default values for struct fields using the `#[from_file(default = "...")]` attribute.
 - **Optional Merging:** When the `merge` feature is enabled, allows merging multiple configuration sources.
 
 ## Usage
 
 ```toml
 [dependencies]
-filecaster = "0.1"
+filecaster = "0.2"
 ```
 
 ```rust
 use filecaster::FromFile;
 
-#[derive(Debug, Clone, FromFile)]
+#[derive(Debug, Clone, PartialEq, FromFile)]
-pub struct MyConfig {
+struct AppConfig {
-    #[from_file(default = "localhost")]
+    /// If the user does not specify a host, use `"127.0.0.1"`.
-    pub host: String,
+    #[from_file(default = "127.0.0.1")]
+    host: String,
+
+    /// Port number; defaults to `8080`.
     #[from_file(default = 8080)]
-    pub port: u16,
+    port: u16,
-    #[from_file(default = false)]
+
-    pub enabled: bool,
+    /// If not set, use `false`. Requires `bool: Default`.
+    auto_reload: bool,
 }
 
 fn main() {
-    // Simulate loading from a file (e.g., JSON, YAML, TOML)
+    // Simulate file content (e.g., from a JSON file)
-    let file_content = r#"
+    let file_content = r#"{ "host": "localhost", "port": 3000 }"#;
-        {
-            "host": "localhost"
-        }
-    "#;
 
-    let config_from_file: MyConfig = serde_json::from_str(file_content).unwrap();
+    // The `AppConfigFile` struct is automatically generated by `#[derive(FromFile)]`.
-    let config = MyConfig::from_file(Some(config_from_file));
+    // It has all fields as `Option<T>`.
+    let partial_config: AppConfigFile = serde_json::from_str(file_content).unwrap();
+    let partial_config2 = partial_config.clone();
 
-    println!("Config: {:?}", config);
+    // Use the generated `from_file` method to get the final config.
-    // Expected output: Config { host: "localhost", port: 8080, enabled: false }
+    // Default values are applied for missing fields.
+    let config = AppConfig::from_file(Some(partial_config));
+    // or
+    let config: AppConfig = partial_config2.into();
+
+    assert_eq!(config.host, "localhost");
+    assert_eq!(config.port, 3000);
+    assert_eq!(config.auto_reload, false); // `bool::default()` is `false`
+
+    println!("Final Config: {:#?}", config);
+
+    // Example with no file content (all defaults)
+    let default_config = AppConfig::from_file(None);
+    assert_eq!(default_config.host, "127.0.0.1");
+    assert_eq!(default_config.port, 8080);
+    assert_eq!(default_config.auto_reload, false);
 }
 ```
 
+## Examples
+
+Use `cargo run --example <example_name>` to execute a specific example. For example:
+
+```bash
+cargo run --example simple
+cargo run --example nested
+```
+
 ## Documentation
 
 Full documentation is available at [docs.rs](https://docs.rs/filecaster).

filecaster-derive/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "filecaster-derive"
-version = "0.2.0"
+version = "0.2.3"
 edition = "2024"
 authors = ["Kristofers Solo <dev@kristofers.xyz>"]
 description = "Procedural derive macro for `filecaster`: automatically implement `FromFile` for your structs."

filecaster-derive/src/from_file.rs

@@ -6,6 +6,7 @@ use syn::{
 };
 
 const WITH_MERGE: bool = cfg!(feature = "merge");
+const WITH_SERDE: bool = cfg!(feature = "serde");
 
 /// Entry point: generate the shadow struct + `FromFile` impls.
 pub fn impl_from_file(input: &DeriveInput) -> Result<TokenStream> {
@@ -59,12 +60,14 @@ fn extract_named_fields(input: &DeriveInput) -> Result<&FieldsNamed> {
             Fields::Named(fields) => Ok(fields),
             _ => Err(Error::new_spanned(
                 &input.ident,
-                "FromFile can only be derived for structs with named fields",
+                r#"FromFile only works on structs with *named* fields.
+Tuple structs and unit structs are not supported."#,
             )),
         },
         _ => Err(Error::new_spanned(
             &input.ident,
-            "FromFile can only be derived for structs",
+            r#"FromFile only works on structs.
+Enums are not supported."#,
         )),
     }
 }
@@ -123,11 +126,16 @@ fn process_fields(fields: &FieldsNamed) -> Result<(Vec<TokenStream>, Vec<TokenSt
 
 /// Derive clause for the shadow struct
 fn build_derive_clause() -> TokenStream {
-    quote! {
+    let mut traits = vec![quote! {Debug}, quote! {Clone}, quote! {Default}];
-        #[derive(Debug, Clone, Default)]
+    if WITH_SERDE {
-        #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
+        traits.extend([quote! { serde::Deserialize }, quote! { serde::Serialize }]);
-        #[cfg_attr(feature = "merge", derive(merge::Merge))]
     }
+
+    if WITH_MERGE {
+        traits.push(quote! { merge::Merge });
+    }
+
+    quote! { #[derive( #(#traits),* )] }
 }
 
 /// Add Default bound to every generic parameter
@@ -166,13 +174,13 @@ fn parse_default(list: &MetaList) -> Result<Option<Expr>> {
             let value = meta.value()?;
             let expr = value.parse::<Expr>()?;
 
-            if let Expr::Lit(expr_lit) = &expr {
+            if let Expr::Lit(expr_lit) = &expr
-                if let Lit::Str(lit_str) = &expr_lit.lit {
+                && let Lit::Str(lit_str) = &expr_lit.lit
-                    default_expr = Some(parse_quote! {
+            {
-                        #lit_str.to_string()
+                default_expr = Some(parse_quote! {
-                    });
+                    #lit_str.to_string()
-                    return Ok(());
+                });
-                }
+                return Ok(());
             }
             default_expr = Some(expr);
         }

filecaster-derive/src/lib.rs

@@ -1,80 +1,98 @@
-//! # filecaster
+//! # filecaster-derive
 //!
-//! `filecaster` is a small `proc-macro` crate that provides a derive‐macro
+//! `filecaster-derive` is the procedural macro crate for `filecaster`. It provides the
-//! `#[derive(FromFile)]` to make it trivial to load partial configurations
+//! `#[derive(FromFile)]` macro, which automates the process of loading partial
-//! from files, merge them with defaults, and get a fully‐populated struct.
+//! configurations from files, merging them with default values, and constructing
+//! fully-populated Rust structs.
+//!
+//! This crate significantly simplifies configuration management by generating
+//! the necessary boilerplate code for the `FromFile` trait (defined in the
+//! `filecaster` crate).
 //!
 //! ## What it does
 //!
 //! For any struct with named fields, `#[derive(FromFile)]` generates:
 //!
-//! 1. A companion `<YourStruct>NameFile` struct in which each field is wrapped
+//! 1.  A companion "shadow" struct (e.g., `YourStructFile` for `YourStruct`)
-//!    in `Option<...>`.
+//!     where each field is wrapped in `Option<T>`. This shadow struct is
-//! 2. A constructor `YourStruct::from_file(file: Option<YourStructFile>) -> YourStruct`
+//!     designed for deserialization from configuration files (e.g., JSON, TOML, YAML).
-//!    that takes your partially‐filled file struct, fills in `None` fields
+//! 2.  An implementation of the `FromFile` trait for your original struct. This
-//!    with either:
+//!     includes the `from_file` method, which takes an `Option<YourStructFile>`
-//!    - an expression you supply via `#[from_file(default = ...)]`, or
+//!     and constructs your final `YourStruct`. It intelligently fills in `None`
-//!    - `Default::default()` (requires `T: Default`)
+//!     fields with either:
-//! 3. An implementation of `From<Option<YourStructFile>> for YourStruct`.
+//!     -   An expression you supply via `#[from_file(default = ...)]`.
+//!     -   `Default::default()` (if no `default` attribute is provided, requiring `T: Default`).
 //!
-//! Because each field in the file‐struct is optional, you can deserialize
+//! ## Optional per-field defaults
-//! e.g. JSON, YAML or TOML into it via Serde, then call `.from_file(...)`
-//! to get your final struct.
-//!
-//! ## Optional per‐field defaults
 //!
 //! Use a `#[from_file(default = <expr>)]` attribute on any field to override
 //! the fallback value. You may supply any expression valid in that struct’s
-//! context. If you omit it, the macro will require `T: Default` and call
+//! context. If you omit it, the macro will require the field's type to implement
-//! `unwrap_or_default()`.
+//! `Default` and will call `Default::default()`.
 //!
-//! Example:
+//! ## Example
 //!
 //! ```rust
 //! use filecaster::FromFile;
 //!
-//! #[derive(Debug, Clone, FromFile)]
+//! #[derive(Debug, Clone, PartialEq, FromFile)]
 //! struct AppConfig {
 //!     /// If the user does not specify a host, use `"127.0.0.1"`.
 //!     #[from_file(default = "127.0.0.1")]
 //!     host: String,
 //!
-//!     /// Number of worker threads; defaults to `4`.
+//!     /// Port number; defaults to `8080`.
-//!     #[from_file(default = 4)]
+//!     #[from_file(default = 8080)]
-//!     workers: usize,
+//!     port: u16,
 //!
-//!     /// If not set, use `false`.
+//!     /// If not set, use `false`. Requires `bool: Default`.
-//!     auto_reload: bool,  // requires `bool: Default`
+//!     auto_reload: bool,
 //! }
 //!
-//! let file_content = r#"
+//! fn example() {
-//!     {
+//!     // Simulate file content (e.g., from a JSON file)
-//!         "host": "localhost"
+//!     let file_content = r#"{ "host": "localhost", "port": 3000 }"#;
-//!     }
-//! "#;
 //!
-//! let config_from_file = serde_json::from_str::<AppConfigFile>(file_content).unwrap();
+//!     // The `AppConfigFile` struct is automatically generated by `#[derive(FromFile)]`.
-//! // After deserializing the partial config from disk (e.g. with Serde):
+//!     // It has all fields as `Option<T>`.
-//! let cfg = AppConfig::from_file(Some(config_from_file));
+//!     let partial_config: AppConfigFile = serde_json::from_str(file_content).unwrap();
-//! println!("{cfg:#?}");
+//!     let partial_config2 = partial_config.clone();
+//!
+//!     // Use the generated `from_file` method to get the final config.
+//!     // Default values are applied for missing fields.
+//!     let config = AppConfig::from_file(Some(partial_config));
+//!     // or
+//!     let config: AppConfig = partial_config2.into();
+//!
+//!     assert_eq!(config.host, "localhost");
+//!     assert_eq!(config.port, 3000);
+//!     assert_eq!(config.auto_reload, false); // `Default::default()` for bool is `false`
+//!
+//!     println!("Final Config: {:#?}", config);
+//!
+//!     // Example with no file content (all defaults)
+//!     let default_config = AppConfig::from_file(None);
+//!     assert_eq!(default_config.host, "127.0.0.1");
+//!     assert_eq!(default_config.port, 8080);
+//!     assert_eq!(default_config.auto_reload, false);
+//! }
 //! ```
 //!
 //! ## Feature flags
 //!
-//! - `merge`
+//! -   `serde`: Enables `serde` serialization/deserialization support for the
-//!   If you enable the `merge` feature, the generated `<Name>File` struct will
+//!     generated shadow structs. This is typically required to deserialize
-//!   also derive `merge::Merge`, and you can layer multiple partial files
+//!     your configuration from file formats like JSON, TOML, or YAML.
-//!   together before calling `.from_file(...)`. Any field‐level merge strategy
+//! -   `merge`: If enabled, the generated shadow struct will also derive
-//!   annotations (`#[merge(...)]`) are applied automatically.
+//!     `merge::Merge`. This allows you to layer multiple partial configuration
+//!     files together before calling `.from_file(...)`. Any field-level
+//!     `#[merge(...)]` attributes will be respected.
 //!
 //! ## Limitations
-//!  
+//!
-//! - Only works on structs with _named_ fields (no tuple‐structs or enums).
+//! -   Only works on structs with _named_ fields (no tuple structs or enums).
-//! - All fields without a `#[from_file(default = ...)]` must implement `Default`.
+//! -   All fields without a `#[from_file(default = ...)]` attribute must
-//!  
+//!     implement the `Default` trait.
-//! ## License
-//!  
-//! MIT OR Apache-2.0
 
 mod from_file;
 

filecaster/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "filecaster"
-version = "0.2.0"
+version = "0.2.3"
 edition = "2024"
 authors = ["Kristofers Solo <dev@kristofers.xyz>"]
 description = "Procedural macro to derive configuration from files, with optional merging capabilities."
@@ -28,3 +28,4 @@ merge = { workspace = true, optional = true }
 serde_json.workspace = true
 tempfile.workspace = true
 toml.workspace = true
+trybuild.workspace = true

filecaster/examples/data/nested.json

@@ -0,0 +1,7 @@
+{
+  "key": "json key",
+  "number": 123,
+  "nested": {
+    "inner_number": 42
+  }
+}

filecaster/examples/data/nested.toml

@@ -0,0 +1,6 @@
+key = "toml key"
+number = 456
+
+[nested]
+inner_key = "inner toml key"
+inner_number = 99

filecaster/examples/data/simple.json

@@ -0,0 +1,4 @@
+{
+  "key": "json key",
+  "number": 123
+}

filecaster/examples/data/simple.toml

@@ -0,0 +1,2 @@
+number = 456
+exists = true

filecaster/examples/nested.rs

@@ -0,0 +1,59 @@
+use filecaster::FromFile;
+use std::fs;
+
+#[derive(Debug, FromFile)]
+pub struct InnerData {
+    #[from_file(default = "inner default")]
+    pub inner_key: String,
+    #[from_file(default = 42)]
+    pub inner_number: i32,
+}
+
+#[derive(Debug, FromFile)]
+pub struct MyData {
+    #[from_file(default = "default key")]
+    pub key: String,
+    #[from_file(default = 0)]
+    pub number: i32,
+    pub nested: InnerData,
+}
+
+fn main() {
+    // Get the absolute current directory
+    let current_dir = std::env::current_dir().expect("Failed to get current directory");
+    // Path to the data directory
+    let data_dir = current_dir.join("filecaster/examples/data");
+
+    // Paths to JSON and TOML files
+    let json_path = data_dir.join("nested.json");
+    let toml_path = data_dir.join("nested.toml");
+
+    // Read and parse JSON file
+    let json_content = fs::read_to_string(&json_path)
+        .unwrap_or_else(|e| panic!("Failed to read JSON file at {:?}: {}", json_path, e));
+    let json_data: MyData = serde_json::from_str::<MyDataFile>(&json_content)
+        .unwrap_or_else(|e| panic!("Failed to parse JSON in {:?}: {}", json_path, e))
+        .into();
+
+    // Read and parse TOML file
+    let toml_content = fs::read_to_string(&toml_path)
+        .unwrap_or_else(|e| panic!("Failed to read TOML file at {:?}: {}", toml_path, e));
+    let toml_data: MyData = toml::from_str::<MyDataFile>(&toml_content)
+        .unwrap_or_else(|e| panic!("Failed to parse TOML in {:?}: {}", toml_path, e))
+        .into();
+
+    // Output the parsed data
+    dbg!(&json_data);
+    dbg!(&toml_data);
+
+    // Example assertions (adjust based on your actual file contents)
+    assert_eq!(json_data.key, "json key");
+    assert_eq!(json_data.number, 123);
+    assert_eq!(json_data.nested.inner_key, "inner default");
+    assert_eq!(json_data.nested.inner_number, 42);
+
+    assert_eq!(toml_data.key, "toml key");
+    assert_eq!(toml_data.number, 456);
+    assert_eq!(toml_data.nested.inner_key, "inner toml key");
+    assert_eq!(toml_data.nested.inner_number, 99);
+}

filecaster/examples/simple.rs

@@ -0,0 +1,48 @@
+use filecaster::FromFile;
+use std::fs;
+
+#[derive(Debug, FromFile)]
+pub struct MyData {
+    #[from_file(default = "default key")]
+    pub key: String,
+    pub number: i32,
+    pub exists: bool,
+}
+
+fn main() {
+    // Get the absolute current directory
+    let current_dir = std::env::current_dir().expect("Failed to get current directory");
+    // Path to the data directory
+    let data_dir = current_dir.join("filecaster/examples/data");
+
+    // Paths to JSON and TOML files
+    let json_path = data_dir.join("simple.json");
+    let toml_path = data_dir.join("simple.toml");
+
+    // Read and parse JSON file
+    let json_content = fs::read_to_string(&json_path)
+        .unwrap_or_else(|e| panic!("Failed to read JSON file at {:?}: {}", json_path, e));
+    let json_data: MyData = serde_json::from_str::<MyDataFile>(&json_content)
+        .unwrap_or_else(|e| panic!("Failed to parse JSON in {:?}: {}", json_path, e))
+        .into();
+
+    // Read and parse TOML file
+    let toml_content = fs::read_to_string(&toml_path)
+        .unwrap_or_else(|e| panic!("Failed to read TOML file at {:?}: {}", toml_path, e));
+    let toml_data: MyData = toml::from_str::<MyDataFile>(&toml_content)
+        .unwrap_or_else(|e| panic!("Failed to parse TOML in {:?}: {}", toml_path, e))
+        .into();
+
+    // Output the parsed data
+    dbg!(&json_data);
+    dbg!(&toml_data);
+
+    // Example assertions (adjust based on your actual file contents)
+    assert_eq!(json_data.key, "json key".to_string());
+    assert_eq!(json_data.number, 123);
+    assert!(!json_data.exists); // `bool::default()` is `false`
+
+    assert_eq!(toml_data.key, "default key".to_string());
+    assert_eq!(toml_data.number, 456);
+    assert!(toml_data.exists);
+}

filecaster/src/lib.rs

@@ -1,10 +1,130 @@
+//! # filecaster
+//!
+//! `filecaster` provides the core `FromFile` trait, which is used in conjunction with the
+//! `filecaster-derive` crate to enable automatic deserialization and merging of
+//! configuration from various file formats into Rust structs.
+//!
+//! This crate defines the fundamental interface for types that can be constructed
+//! from an optional "shadow" representation, typically deserialized from a file.
+//! The `filecaster-derive` crate provides a procedural macro to automatically
+//! implement this trait for your structs, handling default values and merging logic.
+//!
+//! ## How it works
+//!
+//! The `FromFile` trait defines how a final configuration struct (`Self`) can be
+//! constructed from an optional intermediate "shadow" struct (`Self::Shadow`).
+//! The `filecaster-derive` macro generates this `Shadow` struct and the
+//! `from_file` implementation for your configuration types.
+//!
+//! When you derive `FromFile` for a struct, `filecaster-derive` creates a
+//! corresponding `YourStructFile` (the `Shadow` type) where all fields are
+//! wrapped in `Option<T>`. This `YourStructFile` can then be deserialized
+//! from a file (e.g., JSON, TOML, YAML) using `serde`.
+//!
+//! The `from_file` method then takes this `Option<YourStructFile>` and
+//! constructs your final `YourStruct`, applying default values for any fields
+//! that were `None` in the `YourStructFile`.
+//!
+//! ## Example
+//!
+//! While the `FromFile` trait is implemented via the `filecaster-derive` macro,
+//! here's a conceptual example of how it's used:
+//!
+//! ```rust,ignore
+//! use filecaster::FromFile;
+//! use serde::{Deserialize, Serialize};
+//!
+//! // This struct would typically have `#[derive(FromFile)]`
+//! // from the `filecaster-derive` crate.
+//! #[derive(Debug, Default, PartialEq, Serialize, Deserialize)]
+//! struct AppConfig {
+//!     host: String,
+//!     port: u16,
+//!     auto_reload: bool,
+//! }
+//!
+//! // The `Shadow` type is automatically generated by `filecaster-derive`
+//! // and would look something like this:
+//! #[derive(Debug, Default, PartialEq, Serialize, Deserialize)]
+//! struct AppConfigFile {
+//!     host: Option<String>,
+//!     port: Option<u16>,
+//!     auto_reload: Option<bool>,
+//! }
+//!
+//! // The `FromFile` implementation is also automatically generated.
+//! // For demonstration, here's a simplified manual implementation:
+//! impl FromFile for AppConfig {
+//!     type Shadow = AppConfigFile;
+//!
+//!     fn from_file(file: Option<Self::Shadow>) -> Self {
+//!         let file = file.unwrap_or_default();
+//!         AppConfig {
+//!             host: file.host.unwrap_or_else(|| "127.0.0.1".to_string()),
+//!             port: file.port.unwrap_or(8080),
+//!             auto_reload: file.auto_reload.unwrap_or(true),
+//!         }
+//!     }
+//! }
+//!
+//! fn example() {
+//!     // Simulate deserializing from a file
+//!     let file_content = r#"{ "host": "localhost", "port": 3000 }"#;
+//!     let partial_config: AppConfigFile = serde_json::from_str(file_content).unwrap();
+//!
+//!     // Construct the final config using the FromFile trait
+//!     let config = AppConfig::from_file(Some(partial_config));
+//!
+//!     assert_eq!(config.host, "localhost");
+//!     assert_eq!(config.port, 3000);
+//!     assert_eq!(config.auto_reload, false); // `Default::default()` for bool is `false`
+//!
+//!     println!("Final Config: {:#?}", config);
+//!
+//!     // Example with no file content (all defaults)
+//!     let default_config = AppConfig::from_file(None);
+//!     assert_eq!(default_config.host, "127.0.0.1");
+//!     assert_eq!(default_config.port, 8080);
+//!     assert_eq!(default_config.auto_reload, false);
+//! }
+//! ```
+//!
+//! ## Feature flags
+//!
+//! - `derive`: Enables the `filecaster-derive` crate, allowing you to use `#[derive(FromFile)]`.
+//! - `serde`: Enables `serde` serialization/deserialization support for the `FromFile` trait.
+//! - `merge`: Enables `merge` crate support, allowing for merging multiple partial configurations.
+
 pub use filecaster_derive::FromFile;
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 
 /// Marker for types that can be built from an [`Option<Shadow>`] produced by the macro.
+///
+/// The `FromFile` trait is the core interface for `filecaster`. It defines how a
+/// final configuration struct (`Self`) can be constructed from an optional
+/// intermediate "shadow" struct (`Self::Shadow`).
+///
+/// The `Self::Shadow` associated type represents the intermediate structure
+/// that is typically deserialized from a configuration file. All fields in
+/// `Self::Shadow` are usually `Option<T>`, allowing for partial configurations.
+///
+/// The `from_file` method takes an `Option<Self::Shadow>` and is responsible
+/// for producing a fully-populated `Self` instance. This involves applying
+/// default values for any fields that were `None` in the `Shadow` instance.
+///
+/// This trait is primarily designed to be implemented automatically via the
+/// `#[derive(FromFile)]` procedural macro provided by the `filecaster-derive` crate.
 pub trait FromFile: Sized {
+    /// The intermediate "shadow" type that is typically deserialized from a file.
+    ///
+    /// This type usually mirrors the main struct but with all fields wrapped in `Option<T>`.
     type Shadow: Default;
+    /// Constructs the final struct from an optional shadow representation.
+    ///
+    /// If `file` is `None`, a default `Shadow` instance should be used.
+    /// The implementation should then populate `Self` by taking values from
+    /// `file` where present, and applying defaults otherwise.
     fn from_file(file: Option<Self::Shadow>) -> Self;
 }
 

filecaster/tests/ui.rs

@@ -0,0 +1,7 @@
+use trybuild::TestCases;
+
+#[test]
+fn ui() {
+    let t = TestCases::new();
+    t.compile_fail("tests/ui/*.rs");
+}

filecaster/tests/ui/enum_not_supported.rs

@@ -0,0 +1,9 @@
+use filecaster::FromFile;
+
+#[derive(FromFile)]
+enum MyEnum {
+    A,
+    B,
+}
+
+fn main() {}

filecaster/tests/ui/enum_not_supported.stderr

@@ -0,0 +1,6 @@
+error: FromFile only works on structs.
+       Enums are not supported.
+ --> tests/ui/enum_not_supported.rs:4:6
+  |
+4 | enum MyEnum {
+  |      ^^^^^^

filecaster/tests/ui/tuple_struct_not_supported.rs

@@ -0,0 +1,6 @@
+use filecaster::FromFile;
+
+#[derive(FromFile)]
+struct MyTuple(i32, String);
+
+fn main() {}

filecaster/tests/ui/tuple_struct_not_supported.stderr

@@ -0,0 +1,6 @@
+error: FromFile only works on structs with *named* fields.
+       Tuple structs and unit structs are not supported.
+ --> tests/ui/tuple_struct_not_supported.rs:4:8
+  |
+4 | struct MyTuple(i32, String);
+  |        ^^^^^^^