Typestate API

This section teaches you the builder's typestate API. It describes the underlying component traits and types of the builder type and how to use them.

Reading this is optional. By default, both the typestate API and the builder's type signature (except for the initial state) are not visible/nameable outside of the module where the builder was generated. You can use bon perfectly fine without ever touching the typestate API so closely.

Why Would I Need It Anyway?

The typestate API should only come into play when you have a use case that isn't expressible with existing configuration attributes.

Here are some example use cases when you'd need to interact with the typestate API:

• Denoting the builder's type when...
  • returning it from a function
  • declaring it as a parameter of a function
  • storing it in a struct
• Defining a setter that...
  • is unsafe or async
  • declares its own named generic parameters
  • sets multiple members at once
  • cooks you a dinner 🍝

Just kidding 😸, the Typestate API can't cook you a dinner 😳, but you can definitely cook something cool using it 💪!

Spoiler: the typestate API is rather simple, and it's designed for humans. You will not feel like writing some cryptic code that should've been generated by a macro otherwise.

Note, however, that if you have to resort to the typestate API a lot, then it may indicate that bon may be missing some attributes' syntax sugar for your use case. Feel free to create a feature request via an issue or discussion on Github, or message us on Discord about it.

---

Now, click the "Next page" link at the bottom to start learning 🚀