feat!: Add type-level traversal skip attributes

.github/workflows/ci.yml

@@ -35,28 +35,30 @@ concurrency:
 jobs:
   check:
     name: Check
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+      - uses: Swatinem/rust-cache@v2
+      - name: Delete rust-toolchain.toml
+        run: rm rust-toolchain.toml
       - name: Install toolchain
         uses: dtolnay/rust-toolchain@nightly
         with:
           components: rustfmt,clippy
-      - uses: Swatinem/rust-cache@v2
       - uses: taiki-e/install-action@v2
         with:
           tool: typos-cli,taplo-cli,hawkeye
-      - run: cargo +nightly x lint
+      - run: cargo x lint
 
   test:
     name: Run tests
     strategy:
       matrix:
-        os: [ ubuntu-22.04, macos-14, windows-2022 ]
+        os: [ ubuntu-24.04, macos-14, windows-2022 ]
         rust-version: [ "1.85.0", "stable" ]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: Swatinem/rust-cache@v2
       - name: Delete rust-toolchain.toml
         run: rm rust-toolchain.toml
@@ -70,7 +72,7 @@ jobs:
 
   required:
     name: Required
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     if: ${{ always() }}
     needs:
       - check

CHANGELOG.md

@@ -0,0 +1,14 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+### Breaking changes
+
+* Type-level `#[traverse(skip)]` is no longer supported. Use `#[traverse(skip_self)]` to skip calling the visitor for the annotated struct or enum while still traversing its children.
+
+### New features
+
+* Add type-level `#[traverse(skip_self)]` and `#[traverse(skip_children)]` attributes for structs and enums.
+* `#[traverse(skip_children)]` skips traversing the children of the annotated struct or enum, but still calls the visitor for it, unless `#[traverse(skip_self)]` is also present.

Cargo.toml

@@ -25,7 +25,7 @@ repository = "https://github.com/fast/traversable"
 rust-version = "1.85.0"
 
 [workspace.dependencies]
-traversable-derive = { version = "=0.1.0", path = "traversable-derive" }
+traversable-derive = { version = "=0.2.0", path = "traversable-derive" }
 
 [workspace.lints.rust]
 unknown_lints = "deny"

README.md

@@ -26,7 +26,7 @@ Add `traversable` to your `Cargo.toml` with the `derive` feature:
 
 ```toml
 [dependencies]
-traversable = { version = "0.2", features = ["derive", "std"] }
+traversable = { version = "0.3", features = ["derive", "std"] }
 ```
 
 Define your data structures and derive `Traversable`:
@@ -89,6 +89,11 @@ fn main() {
 
 ## Attributes
 
+The derive macro supports the following attributes on structs and enums:
+
+*   `#[traverse(skip_self)]`: Skips calling the visitor for the annotated type while still traversing its children.
+*   `#[traverse(skip_children)]`: Calls the visitor for the annotated type without traversing its children.
+
 The derive macro supports the following attributes on fields and variants:
 
 *   `#[traverse(skip)]`: Skips traversing into the annotated field or variant.

traversable-derive/Cargo.toml

@@ -14,7 +14,7 @@
 
 [package]
 name = "traversable-derive"
-version = "0.1.0"
+version = "0.2.0"
 
 description = "Procedural macro to derive Traversable and TraversableMut"
 documentation = "https://docs.rs/traversable-derive"

traversable-derive/src/lib.rs

@@ -205,10 +205,15 @@ fn resolve_crate_name() -> Path {
 
 fn impl_traversable(input: DeriveInput, mutable: bool) -> Result<TokenStream> {
     let mut params = Params::from_attrs(input.attrs, "traverse")?;
-    params.validate(&["skip"])?;
+    params.validate(&["skip_self", "skip_children"])?;
 
     let skip_visit_self = params
-        .param("skip")?
+        .param("skip_self")?
+        .map(Param::unit)
+        .transpose()?
+        .is_some();
+    let skip_children = params
+        .param("skip_children")?
         .map(Param::unit)
         .transpose()?
         .is_some();
@@ -250,8 +255,20 @@ fn impl_traversable(input: DeriveInput, mutable: bool) -> Result<TokenStream> {
     };
 
     let traverse_fields = match input.data {
-        Data::Struct(struct_) => traverse_struct(struct_, mutable),
-        Data::Enum(enum_) => traverse_enum(enum_, mutable),
+        Data::Struct(struct_) => {
+            if skip_children {
+                Ok(TokenStream::new())
+            } else {
+                traverse_struct(struct_, mutable)
+            }
+        }
+        Data::Enum(enum_) => {
+            if skip_children {
+                Ok(TokenStream::new())
+            } else {
+                traverse_enum(enum_, mutable)
+            }
+        }
         Data::Union(union_) => {
             return Err(Error::new_spanned(
                 union_.union_token,

traversable/Cargo.toml

@@ -14,7 +14,7 @@
 
 [package]
 name = "traversable"
-version = "0.2.0"
+version = "0.3.0"
 
 description = "Visitor Pattern over Traversable data structures"
 documentation = "https://docs.rs/traversable"

traversable/src/lib.rs

@@ -105,6 +105,13 @@
 //!
 //! ## Attributes
 //!
+//! The derive macro supports the following attributes on structs and enums:
+//!
+//! * `#[traverse(skip_self)]`: Skips calling the visitor for the annotated type while still
+//!   traversing its children.
+//! * `#[traverse(skip_children)]`: Calls the visitor for the annotated type without traversing its
+//!   children.
+//!
 //! The derive macro supports the following attributes on fields and variants:
 //!
 //! * `#[traverse(skip)]`: Skips traversing into the annotated field or variant.
@@ -272,7 +279,14 @@ pub trait VisitorMut {
 ///
 /// # Attributes
 ///
-/// The derive macro supports the following attributes:
+/// The derive macro supports the following attributes on structs and enums:
+///
+/// * `#[traverse(skip_self)]`: Skips calling the visitor for the annotated type while still
+///   traversing its children.
+/// * `#[traverse(skip_children)]`: Calls the visitor for the annotated type without traversing its
+///   children.
+///
+/// The derive macro supports the following attributes on fields and variants:
 ///
 /// * `#[traverse(skip)]`: Skips traversing into the annotated field or variant.
 /// * `#[traverse(with = "function_name")]`: Uses a custom function to traverse the field.
@@ -342,7 +356,14 @@ pub trait Traversable: core::any::Any {
 ///
 /// # Attributes
 ///
-/// The derive macro supports the following attributes:
+/// The derive macro supports the following attributes on structs and enums:
+///
+/// * `#[traverse(skip_self)]`: Skips calling the visitor for the annotated type while still
+///   traversing its children.
+/// * `#[traverse(skip_children)]`: Calls the visitor for the annotated type without traversing its
+///   children.
+///
+/// The derive macro supports the following attributes on fields and variants:
 ///
 /// * `#[traverse(skip)]`: Skips traversing into the annotated field or variant.
 /// * `#[traverse(with = "function_name")]`: Uses a custom function to traverse the field.