Builder 派生宏文档

Builder 派生宏用于为 Rust 中的结构体生成构建器方法，该库最大的特点是它在编译时对结构体进行验证。用户可以采用几种配置来定义复杂结构体的有效性，并在结构体创建之前进行检查。

库还会检查结构体永远无法有效或始终有效的场景，但这仍在进行中。错误总是会被发出，但警告仅在夜间渠道上发出。这是由于 proc_macro_error 的限制。

先决条件

要使用 Builder 派生宏，你应该在项目的 Cargo.toml 文件中将 const_typed_builder crate 添加到项目的依赖中

[dependencies]
const_typed_builder = "0.3"

此外，请确保你的代码中有以下使用语句

use const_typed_builder::Builder;

概述

该 crate 可以用于在编译时检查结构体的有效性。用户只能在结构体有效后才能调用构建。这是通过检查所有必填字段是否实例化以及所有用户定义的 "组" 是否有效来完成的。

示例

基本用法

use const_typed_builder::Builder;

#[derive(Builder)]
pub struct Foo {
    bar: String,
}

let foo = Foo::builder()
    .bar("Hello world!".to_string()) // <- The program would not compile without this call
    .build();                        // <- Because this function is only implemented for the
                                     // .. version of FooBuilder where `bar` is initialized

launchd 的子集

use const_typed_builder::Builder;
use std::path::PathBuf;

#[derive(Builder)]
pub struct ResourceLimits {
    core: Option<u64>,
    // ...
}
#[derive(Builder)]
#[group(program = at_least(1))]
pub struct Launchd {
    #[builder(mandatory)]
    label: Option<String>,
    disabled: Option<bool>,
    user_name: Option<String>,
    group_name: Option<String>,
    // ...
    #[builder(group = program)]
    program: Option<PathBuf>,
    bundle_program: Option<String>,
    #[builder(group = program)]
    program_arguments: Option<Vec<String>>,
    // ...
    #[builder(skip)]
    on_demand: Option<bool>, // NB: deprecated (see KeepAlive), but still needed for reading old plists.
    #[builder(skip)]
    service_ipc: Option<bool>, // NB: "Please remove this key from your launchd.plist."
    // ...
    #[builder(propagate)]
    soft_resource_limits: Option<ResourceLimits>,
    #[builder(propagate)]
    hard_resource_limits: Option<ResourceLimits>,
    // ...
}

let launchd = Launchd::builder()
    .label("my_label".to_string())    // <- 1: Mandatory
    .program("./my_program".into())   // <- 2: Launchd expects that least one of these fields is set..
    .program_arguments(               // <- 2: .. We can remove either one, but never both
        vec!["my_arg".to_string()]
    ) 
//  .on_demand(false)                    <- 3: This function doesn't exist
    .soft_resource_limits(|builder|
        Some(builder.core(Some(1)).build()) // <- 4: Propagating to `ResourceLimits::builder`
    ) 
    .build();

属性

这是对该库功能的一个快速概述。有关所有功能的更深入解释，包括示例，请参阅 const_typed_builder_derive::Builder。 结构体

• #[builder(assume_mandatory)]：表示该结构体中的所有字段都应被视为必填。如果没有提供等号（例如，#[builder(assume_mandatory)]），则将字段的mandatory标志设置为true。如果提供等号（例如，#[builder(assume_mandatory = true)]），则根据值设置字段的mandatory标志。
• #[group(group_name = (exact(N)|at_least(N)|at_most(N)|single)]：将结构体的字段与名为"group_name"的组相关联，并指定组的操作行为。该group_name应为一个字符串标识符。组可以有以下行为之一：
  • exact(N)：在构建器构建过程中，组中必须恰好设置N个字段。
  • at_least(N)：在构建器构建过程中，组中至少需要设置N个字段。
  • at_most(N)：在构建器构建过程中，组中最多只能设置N个字段。
  • single：在构建器构建过程中，组中只能设置一个字段。这是exact(1)的简写。例如，#[group(foo = at_least(2))]创建了一个至少需要初始化2个字段的组。
• #[builder(solver = (brute_force|compiler))]: 请谨慎使用，参见本文件底部说明！ 指定用于构建结构的求解器类型。 solve_type 应为预定义的求解器类型之一，例如 brute_force 或 compiler。如果提供等号（例如，#[builder(solver = brute_force)]），则相应设置“求解器类型”。此属性仍在测试中，默认为 brute_force，只有当编译时间出现问题，您可以尝试 compiler。不过，compiler 给出的保证较少。