Terminology

Attribute Arguments and Sub-Arguments

FieldX adopts a function-like syntax for specifying struct parameters through attributes. These parameters are referred to as arguments. Some arguments may require further customization, in which case they also take a function-like form and are referred to as sub-arguments.

This design choice supports deep nesting of parameters. For example:

#[fxstruct(
    builder(
        attributes_fn(allow(dead_code)),
        doc("Builder for the struct."),
    )
)]

Struct- and field-level arguments

As mentioned in the Basics, the fxstruct macro is applied to the struct itself and utilizes parameters provided by fieldx attributes. Consequently, this book frequently refers to various entities (primarily attribute arguments) as either struct-level or field-level.

For instance, it may be noted that a struct-level argument defines a default value, while a field-level argument overrides it. Similarly, certain functionalities might be available at the struct level but not at the field level.

Helper Arguments

Some arguments in FieldX are associated with implementation methods, whether generated by FieldX itself or provided by the user. These arguments are referred to as helper arguments, and they share some common sub-arguments. A more detailed overview of them will be provided later in this book, but for now, let's mention a literal string sub-argument that allows custom names to be defined for the argument-bound methods. Depending on the context, the argument may specify either the full name of the method or just a part of it, most commonly a prefix:

#[fxstruct(get("get_"))]

#[fieldx(get("field_alias"))]

Argument Disabler

Many arguments in FieldX are boolean flags by default, meaning they enable certain functionality. However, there are cases where it may be necessary to disable functionality instead. The two most common scenarios for this are:

• Debugging or testing purposes, where functionality needs to be temporarily disabled.
• Overriding a struct-level default at the field level.

To address this, FieldX introduces the concept of an argument disabler: a sub-argument named off.

#[fxstruct(get)]
struct MyStruct {
    // Override the struct-level `get`
    #[fieldx(get(off))]
    field: String,
    ...
}

Builder and Builder Methods

The term builder in FieldX can be confusing because it is used in two distinct contexts:

1. Builder type: A type generated by the fxstruct macro that facilitates step-by-step construction of an instance of the annotated struct. This concept aligns with the builder pattern.
2. Builder methods: User-defined methods for initializing fields lazily.

The term builder methods originated from similar implementations of the lazy initialization pattern in Perl and Raku modules. It was adopted in FieldX before the builder pattern was introduced, leading to the dual usage of the term. In most cases, the intended meaning is either clear from the context or explicitly clarified.

Modes of Operation

FieldX supports three modes of operation: sync, async, and plain (unsync). While their names are largely self-explanatory, here is a brief overview:

• Sync: Designed for synchronous code, this mode ensures thread-safe access to fields.
• Async: Tailored for asynchronous code, this mode facilitates field access in an async context. It is particularly useful for lazy fields, enabling users to implement async builder methods.
• Plain: This mode does not enforce thread safety or async compatibility. Depending on the field configuration, it may explicitly lack Sync and Send traits due to its container wrapper type, or it might "incidentally" be thread-safe due to the inherent properties of the field type.

The implications of sync and async modes are explored further in the corresponding section.

Fallible and Infallible

By default, FieldX expects user-provided code to be infallible, meaning that it does not return a Result¹. However, this constraint can be challenging to meet in practice. To address this, FieldX offers an escape hatch: support for fallible code that can return a Result type. The only requirement is that users declare the error type their code may return.

1. Of course, it is always possible to panic, but it's the behavior being frowned upon. ↩