Vision proposal

.travis.yml

@@ -8,9 +8,9 @@ rust:
 matrix:
   include:
     - rust: 1.15.0
-      env: JOB=build CARGO_FEATURES="struct_default"
+      env: JOB=build CARGO_FEATURES="skeptic_tests struct_default"
     - rust: nightly
-      env: JOB=build CARGO_FEATURES="nightlytests logging"
+      env: JOB=build CARGO_FEATURES="skeptic_tests nightlytests logging"
     - rust: nightly
       env: JOB=style_check
   allow_failures:
@@ -20,7 +20,7 @@ env:
   matrix:
     - JOB=build
   global:
-  - CARGO_FEATURES=""
+  - CARGO_FEATURES="skeptic_tests"
   - RUST_BACKTRACE=1
   - TRAVIS_CARGO_NIGHTLY_FEATURE=""
   - PKGNAME=derive_builder
@@ -50,22 +50,20 @@ script: |
       # We have to consider the following limitations of cargo in rustc 1.15:
       # - no support for virtual worskpaces, instead we have to cd into a crate.
       # - cargo build/doc does not support `--all`, luckily the
-      #   `derive_builder_test` crate will implicitly build/doc the
-      #   `derive_builder` and `derive_builder_core` crates too.
+      #   `derive_builder` crate will implicitly build/doc the
+      #   `derive_builder_core` crate too.
       commands=(
-        "cd derive_builder_test && travis-cargo build -- --features \"$CARGO_FEATURES\""
-        "cd derive_builder_test && travis-cargo test -- --all --no-fail-fast --features \"$CARGO_FEATURES\""
-        "cd derive_builder_test && travis-cargo doc"
+        "cd derive_builder && travis-cargo build -- --features \"$CARGO_FEATURES\""
+        "cd derive_builder && travis-cargo test -- --all --no-fail-fast --features \"$CARGO_FEATURES\""
+        "cd derive_builder && travis-cargo doc"
       )
       ;;
     style_check)
       commands=(
         "cd derive_builder_core && cargo clippy -- -Dclippy"
         "cd derive_builder      && cargo clippy -- -Dclippy"
-        "cd derive_builder_test && cargo clippy -- -Dclippy"
         "cd derive_builder_core && cargo fmt -- --write-mode diff"
         "cd derive_builder      && cargo fmt -- --write-mode diff"
-        "cd derive_builder_test && cargo fmt -- --write-mode diff"
       )
       ;;
     *)

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to `derive_builder`
+
+Thank you for your interest in contributing to this crate!
+
+## Pull Requests
+
+Please make [pull requests] against the `master` branch.
+[pull requests]: https://help.github.com/articles/using-pull-requests/
+
+All pull requests should clearly describe what they intend to do, or link to
+a github issue, where this is explained.
+
+You should try to make sure your pull request passes all tests. Since some
+tests are behind feature gates it's best to run the script `dev/githook.sh` as
+described in `dev/README.md`. This script is intended to be primarily used as a
+pre-push git hook, but it can be called manually as well.
+
+Please follow this checklist
+- update the `CHANGELOG.md` - add a section `[Unreleased]` at the top, if
+  that's missing.
+- update the documentation in `lib.rs` (optional: `README.md`)
+- add unit tests to `derive_builder_core`, if appropriate
+- add integration tests to `derive_builder` with different variants and also
+  try to test possible side effects with other features of this crate.
+
+### Early Feedback and Help
+
+If you're stuck somewhere and need help or if you just want some early feedback,
+you can either open an issue, or send a preliminary PR. In that case, please
+mark it as **work in progress (WIP)** and state your questions.

Cargo.toml

@@ -1,2 +1,2 @@
 [workspace]
-members = ["derive_builder", "derive_builder_core", "derive_builder_test"]
+members = ["derive_builder", "derive_builder_core"]

derive_builder/CHANGELOG.md

@@ -106,7 +106,7 @@ Requires Rust 1.15 or newer.
  - generate setter methods
  - support for generic structs
 
-[Unreleased]:  https://github.com/colin-kiegel/rust-derive-builder/compare/v0.4.0...HEAD
+[Unreleased]:  https://github.com/colin-kiegel/rust-derive-builder/compare/v0.4.4...HEAD
 [0.4.4]:  https://github.com/colin-kiegel/rust-derive-builder/compare/v0.4.3...v0.4.4
 [0.4.3]:  https://github.com/colin-kiegel/rust-derive-builder/compare/v0.4.2...v0.4.3
 [0.4.2]:  https://github.com/colin-kiegel/rust-derive-builder/compare/v0.4.1...v0.4.2

derive_builder/Cargo.toml

@@ -25,7 +25,7 @@ proc-macro = true
 logging = [ "log", "env_logger", "derive_builder_core/logging" ]
 struct_default = []
 skeptic_tests = ["skeptic"]
-nightlytests = []
+nightlytests = ["compiletest_rs"]
 
 [dependencies]
 syn = "0.11"
@@ -34,6 +34,7 @@ log = { version = "0.3", optional = true }
 env_logger = { version = "0.4", optional = true }
 derive_builder_core = { version = "0.1", path = "../derive_builder_core" }
 skeptic = { version = "0.9", optional = true }
+compiletest_rs = { version = "0.2", optional = true }
 
 [build-dependencies]
 skeptic = { version = "0.9", optional = true }

derive_builder/examples/custom_defaults.rs

@@ -14,7 +14,9 @@ struct Lorem {
 
 impl LoremBuilder {
     fn default_dolor(&self) -> Result<String, String> {
-        self.ipsum.clone().ok_or_else(|| "ipsum must be initialized to build dolor".to_string())
+        self.ipsum
+            .clone()
+            .ok_or_else(|| "ipsum must be initialized to build dolor".to_string())
     }
 
     fn default_sit(&self) -> Result<String, String> {
@@ -39,10 +41,11 @@ fn main() {
         .build()
         .unwrap();
 
-    assert_eq!(x, Lorem {
-        ipsum: "ipsum".to_string(),
-        dolor: "ipsum".to_string(),
-        sit: "sit ipsum".to_string(),
-        amet: "amet ipsum".to_string(),
-    });
+    assert_eq!(x,
+               Lorem {
+                   ipsum: "ipsum".to_string(),
+                   dolor: "ipsum".to_string(),
+                   sit: "sit ipsum".to_string(),
+                   amet: "amet ipsum".to_string(),
+               });
 }

derive_builder/examples/deny_missing_docs.rs

@@ -15,6 +15,9 @@ pub struct Letter {
 }
 
 fn main() {
-    let x = LetterBuilder::default().message("Hello World!").build().unwrap();
+    let x = LetterBuilder::default()
+        .message("Hello World!")
+        .build()
+        .unwrap();
     println!("{}", x.message);
 }

derive_builder/src/doc_tpl/builder_struct.md

@@ -1 +1 @@
-Builder for `{struct_name}`.
+Builder for [`{struct_name}`](struct.{struct_name}.html).

derive_builder/src/lib.rs

@@ -412,16 +412,18 @@
 //!
 //! - Tuple structs and unit structs are not supported as they have no field
 //!   names.
+//! - Generic structs need the boundary `where T: std::clone::Clone` if
+//!   used in combination with the immutable/mutable pattern
 //! - Generic setters introduce a type parameter `VALUE: Into<_>`. Therefore you can't use
 //!  `VALUE` as a type parameter on a generic struct in combination with generic setters.
+//! - The `try_setter` attribute and `owned` builder pattern are not compatible in practice;
+//!   an error during building will consume the builder, making it impossible to continue
+//!   construction.
 //! - When re-exporting the underlying struct under a different name, the
 //!   auto-generated documentation will not match.
 //! - If derive_builder depends on your crate, and vice versa, then a cyclic
 //!   dependency would occur. To break it you could try to depend on the
 //!   [`derive_builder_core`] crate instead.
-//! - The `try_setter` attribute and `owned` builder pattern are not compatible in practice;
-//!   an error during building will consume the builder, making it impossible to continue
-//!   construction.
 //!
 //! ## Debugging Info
 //!

derive_builder/src/options/mod.rs

@@ -1,3 +1,16 @@
+//! Types and functions for parsing attribute options.
+//!
+//! Attribute parsing occurs in multiple stages:
+//!
+//! 1. Builder options on the struct are parsed into `OptionsBuilder<StructMode>`.
+//! 1. The `OptionsBuilder<StructMode>` instance is converted into a starting point for the
+//!    per-field options (`OptionsBuilder<FieldMode>`) and the finished struct-level config,
+//!    called `StructOptions`.
+//! 1. Each struct field is parsed, with discovered attributes overriding or augmenting the
+//!    options specified at the struct level. This creates one `OptionsBuilder<FieldMode>` per
+//!    struct field on the input/target type. Once complete, these get converted into
+//!    `FieldOptions` instances.
+
 use syn;
 use derive_builder_core::BuilderPattern;
 

derive_builder_test/tests/compiletests.rs → derive_builder/tests/compiletests.rs

@@ -32,8 +32,7 @@ fn run_mode(mode: &'static str) {
     let build_dir = env::var("CARGO_TARGET_DIR").unwrap_or(format!("{}/target", base_dir));
     let artefacts_dir = format!("{}/{}", build_dir, PROFILE);
 
-    config.target_rustcflags =
-        Some(format!("-L {} -L {}/deps", artefacts_dir, artefacts_dir));
+    config.target_rustcflags = Some(format!("-L {} -L {}/deps", artefacts_dir, artefacts_dir));
 
     compiletest::run_tests(&config);
 }

derive_builder/tests/custom_default.rs

@@ -36,13 +36,14 @@ mod field_level {
             .build()
             .unwrap();
 
-        assert_eq!(x, Lorem {
-            required: "ipsum".to_string(),
-            explicit_default: "".to_string(),
-            escaped_default: "foo".to_string(),
-            raw_default: "Hello World!".to_string(),
-            computed_default: "ipsum-EMPTY-EMPTY-EMPTY".to_string(),
-        });
+        assert_eq!(x,
+                   Lorem {
+                       required: "ipsum".to_string(),
+                       explicit_default: "".to_string(),
+                       escaped_default: "foo".to_string(),
+                       raw_default: "Hello World!".to_string(),
+                       computed_default: "ipsum-EMPTY-EMPTY-EMPTY".to_string(),
+                   });
     }
 
     #[test]
@@ -55,13 +56,14 @@ mod field_level {
             .build()
             .unwrap();
 
-        assert_eq!(x, Lorem {
-            required: "ipsum".to_string(),
-            explicit_default: "lorem".to_string(),
-            escaped_default: "dolor".to_string(),
-            raw_default: "sit".to_string(),
-            computed_default: "ipsum-lorem-dolor-sit".to_string(),
-        });
+        assert_eq!(x,
+                   Lorem {
+                       required: "ipsum".to_string(),
+                       explicit_default: "lorem".to_string(),
+                       escaped_default: "dolor".to_string(),
+                       raw_default: "sit".to_string(),
+                       computed_default: "ipsum-lorem-dolor-sit".to_string(),
+                   });
     }
 }
 
@@ -107,42 +109,41 @@ mod struct_level {
 
     #[test]
     fn explicit_defaults_are_equal() {
-        let lorem = LoremBuilder::default()
-            .build()
-            .unwrap();
+        let lorem = LoremBuilder::default().build().unwrap();
 
         // new behaviour starting with 0.5.x:
         #[cfg(feature = "struct_default")]
-        assert_eq!(lorem, Lorem {
-            overwritten: true,
-            ..explicit_default()
-        });
+        assert_eq!(lorem,
+                   Lorem {
+                       overwritten: true,
+                       ..explicit_default()
+                   });
 
         // old behaviour since 0.4.x:
         #[cfg(not(feature = "struct_default"))]
-        assert_eq!(lorem, Lorem {
-            overwritten: true,
-            not_type_default: explicit_default(),
-        });
+        assert_eq!(lorem,
+                   Lorem {
+                       overwritten: true,
+                       not_type_default: explicit_default(),
+                   });
     }
 
     #[test]
     fn implicit_defaults_are_equal() {
-        let ipsum = IpsumBuilder::default()
-            .build()
-            .unwrap();
+        let ipsum = IpsumBuilder::default().build().unwrap();
 
         // new behaviour starting with 0.5.x:
         #[cfg(feature = "struct_default")]
         assert_eq!(ipsum, Ipsum::default());
 
         // old behaviour since 0.4.x:
         #[cfg(not(feature = "struct_default"))]
-        assert_eq!(ipsum, Ipsum {
-            not_type_default: Default::default(),
-            also_custom: Default::default(),
-            is_type_default: Default::default(),
-        });
+        assert_eq!(ipsum,
+                   Ipsum {
+                       not_type_default: Default::default(),
+                       also_custom: Default::default(),
+                       is_type_default: Default::default(),
+                   });
     }
 
     #[test]

derive_builder/tests/dummy-crate/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "derive_builder_dummy_crate"
+version = "0.1.0"
+authors = ["Colin Kiegel <kiegel@gmx.de>"]
+description = "This dummy crate serves as a playground to **manually** inspect things like generated documentation. It is **not** tested automatically."
+license = "MIT/Apache-2.0"
+publish = false
+
+[lib]
+path = "src/lib.rs"
+
+[dependencies]
+derive_builder = { path = "../../" }

derive_builder_test/src/lib.rs → derive_builder/tests/dummy-crate/src/lib.rs

@@ -1,3 +1,5 @@
+/// This dummy crate serves as a playground to inspect things like generated documentation
+
 #[macro_use]
 extern crate derive_builder;
 

derive_builder/tests/generic_structs.rs

@@ -51,8 +51,5 @@ fn generic_reference_builder() {
         .build()
         .unwrap();
 
-    assert_eq!(x,
-               GenericReference {
-                   bar: Some(&BAR),
-               });
+    assert_eq!(x, GenericReference { bar: Some(&BAR) });
 }

derive_builder/tests/setter_into.rs

@@ -17,26 +17,14 @@ struct Ipsum {
 
 #[test]
 fn generic_field() {
-    let x = LoremBuilder::default()
-        .foo("foo")
-        .build()
-        .unwrap();
+    let x = LoremBuilder::default().foo("foo").build().unwrap();
 
-    assert_eq!(x,
-               Lorem {
-                   foo: "foo".to_string(),
-               });
+    assert_eq!(x, Lorem { foo: "foo".to_string() });
 }
 
 #[test]
 fn generic_struct() {
-    let x = IpsumBuilder::default()
-        .foo(42u8)
-        .build()
-        .unwrap();
+    let x = IpsumBuilder::default().foo(42u8).build().unwrap();
 
-    assert_eq!(x,
-               Ipsum {
-                   foo: 42u32,
-               });
+    assert_eq!(x, Ipsum { foo: 42u32 });
 }

derive_builder/tests/setter_name.rs

@@ -7,7 +7,7 @@ extern crate derive_builder;
 #[builder(setter(prefix="with"))]
 struct Lorem {
     ipsum: &'static str,
-    #[builder(setter(name="foo"))] // takes precedence over prefix
+    #[builder(setter(name="foo"))]
     pub dolor: &'static str,
 }