What you will learn in Write Powerful Rust Macros

by Sam Van Overmeire

Read it on liveBook Get the book at manning.com

Chapter by chapter

Chapter 1: Going meta

1.1 A day in the life of a Rust developer · 1.2 What is metaprogramming? · 1.3 Metaprogramming in Rust · 1.3.1 Macro galore · 1.3.2 Appropriate use cases · 1.3.3 Unfit for purpose: When not to use macros · 1.4 Approach of this book · 1.5 Exercise · 1.6 Summary

What you learn in chapter 1 →

Chapter 2: Declarative macros

2.1 Creating vectors · 2.1.1 Syntax basics · 2.1.2 Declaring and exporting declarative macros · 2.1.3 The first matcher explained · 2.1.4 nonemtpy matchers · 2.2 Use cases · 2.2.1 Varargs and default arguments · 2.2.2 More than one way to expand code · 2.2.3 Newtypes · 2.2.4 DSLs · 2.2.5 Composing is easy · 2.2.6 Currying, on the other hand . . . · 2.2.7 Hygiene is something to consider as well · 2.3 From the real world · 2.4 Exercises · 2.5 Summary

What you learn in chapter 2 →

Chapter 3: A “Hello, World” procedural macro

3.1 Basic setup of a procedural macro project · 3.2 Analyzing the procedural macro setup · 3.3 Generating output · 3.4 Experimenting with our code · 3.5 cargo expand · 3.6 The same macro—without syn and quote · 3.7 From the real world · 3.8 Exercises · 3.9 Summary

What you learn in chapter 3 →

Chapter 4: Making fields public with attribute macros

4.1 Setup of an attribute macro project · 4.2 Attribute macros vs. derive macros · 4.3 First steps in public visibility · 4.4 Getting and using fields · 4.5 Possible extensions · 4.6 More than one way to parse a stream · 4.6.1 Delegating tasks to a custom struct · 4.6.2 Implementing the Parse trait · 4.6.3 Going low, low, low with cursor · 4.7 Even more ways to develop and debug · 4.8 From the real world · 4.9 Exercises · 4.10 Summary

What you learn in chapter 4 →

Chapter 5: Hiding information and creating mini-DSLs with function-like macros

5.1 Hiding information · 5.1.1 Setup of the information-hiding macro · 5.1.2 Recreating the struct · 5.1.3 Generating the helper methods · 5.2 Debugging by writing normal code · 5.3 Composing · 5.4 Anything you can do, I can do better · 5.5 From the real world · 5.6 Exercises · 5.7 Summary

What you learn in chapter 5 →

Chapter 6: Testing a builder macro

6.1 Builder macro project setup · 6.2 Fleshing out the structure of our setup · 6.3 Adding white-box unit tests · 6.4 Black-box unit tests · 6.4.1 A happy path test · 6.4.2 A happy path test with an actual property · 6.4.3 Testing enables refactoring · 6.4.4 Further improvements and testing · 6.4.5 An alternative approach · 6.4.6 Unhappy path · 6.5 What kinds of unit tests do I need? · 6.6 Beyond unit tests · 6.7 From the real world · 6.8 Exercises · 6.9 Summary

What you learn in chapter 6 →

Chapter 7: From panic to result: Error handling

7.1 Errors and control flow · 7.2 Pure and impure functions · 7.3 Alternatives to exceptions · 7.4 Rust’s Result and panics · 7.5 Setup of the panic project · 7.6 Mutable or immutable returns · 7.7 Getting results · 7.8 Don’t panic · 7.8.1 Changing the panic into a Result · 7.8.2 Debugging observations · 7.9 Error-handling flavors · 7.9.1 Using syn for error handling · 7.9.2 Using proc_macro_error for error handling · 7.9.3 Deciding between syn and proc_macro_error · 7.10 From the real world · 7.11 Exercises · 7.12 Summary

What you learn in chapter 7 →

Chapter 8: Builder with attributes

8.1 A rename attribute · 8.1.1 Testing the new attribute · 8.1.2 Implementing the attribute’s behavior · 8.1.3 Parsing variations · 8.2 Alternative naming for attributes · 8.3 Sensible defaults · 8.4 A better error message for defaults · 8.5 Build back better · 8.5.1 Avoiding illegal states and the type state pattern · 8.5.2 Combining the builder pattern with type state · 8.6 Avoiding scattered conditionals · 8.7 Attribute tokens and attributes · 8.8 Other attributes · 8.9 From the real world · 8.10 Exercises · 8.11 Summary

What you learn in chapter 8 →

Chapter 9: Writing an infrastructure DSL

9.1 What is IaC? What is AWS? · 9.2 How our DSL works · 9.3 Parsing our input · 9.3.1 Project setup and usage examples · 9.3.2 Implementing the Parse trait for our structs · 9.4 Two alternative parsing approaches · 9.4.1 Using Punctuated with a custom struct · 9.4.2 Using Punctuated with a custom enum and builder · 9.5 Actually creating the services · 9.6 The two AWS clients · 9.7 Errors and declarative macros · 9.8 The right kind of testing · 9.9 From the real world · 9.10 Exercises · 9.11 Summary

What you learn in chapter 9 →

Chapter 10: Macros and the outside world

10.1 A function-like configuration macro · 10.1.1 Macro project structure · 10.1.2 Code overview · 10.1.3 Using full paths · 10.2 Adding another macro · 10.3 Features · 10.4 Documenting a macro · 10.5 Publishing our macro · 10.6 From the real world · 10.7 Where to go from here · 10.8 Exercises · 10.9 Summary

What you learn in chapter 10 →

Concepts explained in this book

TokenStreamA token stream is a sequence of Rust tokens used as input or output during macro expansion and source-code generation.
declarative macromacro_rules! is Rust's declaration syntax for defining declarative macros from matcher and transcriber rules.
macroA Rust macro is a compile-time language construct that generates or transforms Rust source code through expansion.
derive macroA Rust derive attribute requests compiler or procedural generation of trait implementations for a type.
attribute macroAn attribute macro is a Rust procedural macro that defines a custom attribute and replaces the annotated item with generated output.
result typeResult is the Rust standard-library enum representing either successful output or an error value.
parsingParsing is the process of analyzing an input sequence according to a grammar and constructing its syntactic structure.
domain-specific languageA domain-specific language is a language designed to express concepts and operations within a particular application domain.
genericsA generic function is a function parameterized by types or other compile-time parameters.
quotequote is a Rust library and macro for generating source-token streams from interpolated syntax.
procedural macroA procedural macro is a Rust macro implemented as code that receives a token stream and programmatically produces another token stream.
macro matcherA macro matcher is the pattern portion of a declarative macro rule that determines which invocation tokens the rule accepts.
builder patternThe builder pattern constructs a complex value through an intermediate builder with configurable operations before finalization.
function-like macroA function-like macro is a Rust procedural macro invoked with the ! operator that accepts arbitrary token input and replaces that input with generated output.
abstract syntax treeAn abstract syntax tree is a hierarchical representation of a program's syntactic structure and relevant semantic elements.
AWS LambdaAWS Lambda is a serverless computing platform that runs code in response to events without requiring users to manage servers.
macro transcriberA macro transcriber is the output-template portion of a declarative macro definition that specifies generated syntax for a matched invocation.
DeriveInputDeriveInput is a syn syntax structure representing the input item received by a derive macro, including a struct or enum.
type stateThe type state pattern encodes an object's permitted states in its type so invalid state transitions or configurations are rejected at compile time.
bucketA bucket is a cloud-infrastructure storage resource that holds collections of objects or similar data.
token treeA Rust token tree is a syntactic token or delimited sequence of tokens that can be captured as a broadly permissive macro fragment.
black-box testingBlack-box testing evaluates software through externally observable behavior and public interfaces without relying on implementation details.
compositionFunction composition combines functions so that the output of one becomes the input of another.
proc-macro crate settingA proc-macro library is a Rust crate whose exported procedural macro items are compiled for use during another crate's compilation.
parse_macro_inputparse_macro_input is a syn-provided procedural macro that parses a procedural macro's input token stream into a specified Rust syntax type.
cargo featureA Cargo feature is a named compile-time configuration option that conditionally enables additive crate functionality or dependencies.
marker traitA marker trait is a trait with no methods or associated properties that classifies implementing types.
Amazon S3Amazon S3 is an object storage service whose data is organized into named storage containers called buckets.
AWS SDK for RustAWS SDK for Rust is a Rust library providing programmatic clients for interacting with AWS services.
punctuatedPunctuated is a syn sequence structure that stores syntax elements together with their punctuation separators.
compilation testA compile test is a software test whose expected outcome is successful compilation of generated or written code.
parse2parse2 is a syn function that parses a proc-macro2 token stream into a specified Rust syntax type and checks that the input has been fully consumed.
newtype idiomA newtype is a distinct wrapper type around an existing value that gives the value stronger type-level meaning and can enforce construction invariants.
white-box testingWhite-box testing evaluates software with knowledge of and access to its internal implementation, including private code paths.
expressionA Rust expression is a syntactic construct that evaluates to a value.
panicA panic is Rust's unrecoverable failure mechanism that stops ordinary execution and may unwind the stack to clean up resources.
compile timeCompile time is the phase in which source code is analyzed and transformed into an executable or library artifact.
syn::Errorsyn::Error is syn's error type for reporting parsing and syntax-processing failures with source spans and diagnostic messages.
macro recursionMacro recursion is the expansion behavior in which a macro invocation expands to another invocation of the same macro.
orphan ruleAn orphan rule restricts trait implementations so that at least the trait or the implemented type is local to the defining crate.
compile-time errorA compile error is a compiler diagnostic indicating that source code violates language or compilation rules and cannot be successfully compiled.
blanket implementationA blanket implementation is a trait implementation written for every type satisfying specified bounds.
fragment specifierA fragment specifier is the annotation in a declarative macro matcher that selects the syntactic category accepted by a metavariable.
macro parameterA macro variable is a named binding in a declarative macro that refers to syntax captured by a matcher.
macro repetitionA macro repetition operator specifies whether a repeated macro pattern occurs zero or more, one or more, or zero or one times.
metavariableA metavariable is a declarative-macro binding whose fragment specifier determines the syntactic category of captured input.
ToTokensToTokens is a quote trait whose implementations convert Rust syntax-related values into token streams.
impure functionAn impure function is a function whose behavior or result can depend on or produce effects beyond its input parameters.
pure functionA pure function is a function with no observable side effects whose result depends only on its input parameters.
custom keywordA custom keyword is a syntax token declared through syn's custom_keyword macro that implements parsing and lookahead support for a DSL-specific keyword.
metaprogrammingMetaprogramming is the practice of writing code that treats other code as data so it can manipulate or generate code or add capabilities.
cargo checkcargo check is a Cargo command that compiles a Rust project for error checking without producing a final executable.
LitIntLitInt is syn's syntax structure representing a Rust integer literal together with its source span.
DefaultDefault is the standard Rust trait for constructing a default value of a type.
MetaListMetaList is a syn syntax structure representing list-form Rust metadata such as an attribute path followed by nested arguments.
proc_macro_errorproc_macro_error is a Rust library that provides procedural-macro facilities for reporting compile-time errors with reduced boilerplate.
variadic argumentsVariadic arguments are function-call arguments whose number is determined at the call site rather than fixed by the declaration.
parse_nested_metaparse_nested_meta is a syn parsing operation that iterates over nested metadata inside an attribute and delegates each entry to a callback.
infrastructure as codeInfrastructure as code is the practice of defining and managing computing infrastructure through executable code or declarative machine-readable configuration.
matcher-transcriber pairA matcher-transcriber pair is a declarative macro rule consisting of an input matcher and its corresponding output transcriber.
DataStructDataStruct is a syn syntax structure representing the parsed components and data of a Rust struct declaration.
syn dataData is a syn enum representing whether a parsed input contains a struct, enum, or union.
syn fieldField is a syn syntax structure representing a Rust struct or enum field and its properties.
macro expansionMacro expansion is the process of replacing a macro invocation with the source code generated or transformed by that macro.
monomorphizationMonomorphization is the compilation transformation that creates concrete specialized copies of a generic function for the types with which it is instantiated.
proc_macro_deriveproc_macro_derive is the Rust attribute that marks a procedural macro function as a derive macro implementation and assigns its invocation name.
tokenizationLexing is the process of converting raw source text into a sequence of lexical tokens.
cargo-expandcargo expand is a Cargo subcommand that displays the Rust source code produced by macro expansion.
inert attributeAn inert attribute is an attribute that remains available during processing rather than removing itself during macro expansion.
call_sitecall_site is a Span-associated function that creates a span resolved at the location where a procedural macro is invoked.
identifier fragment specifierAn identifier fragment specifier matches an identifier token as an input fragment in a Rust declarative macro.
type fragment specifierA type fragment specifier is a declarative-macro matcher specifier that matches Rust type syntax.
cargo init commandcargo init is a Cargo command that creates a new Rust package with generated project files.
rename attributeA rename attribute is the book-specific helper attribute that specifies an alternate property name for generated builder code.
integration testIntegration testing evaluates the behavior and interactions of multiple software components, often across external system boundaries.
active attributeAn active attribute is an attribute that is removed during attribute processing after its macro expands.
trybuildtrybuild is a Rust testing tool for compiling test cases and checking their expected compiler errors or successful compilation.
macro hygieneMacro hygiene is the property that prevents identifiers introduced or referenced by a macro expansion from unintentionally colliding with identifiers in surrounding code.
end-to-end testingAn end-to-end test evaluates the workings of an entire system using most or all of its real dependencies.
algebraic data typeAn algebraic data type is a composite type formed from product and sum type constructors to represent a defined set of values.
EitherEither is a sum-type pattern representing one of two alternatives, conventionally a successful result or a failure.
enumAn enum is a Rust sum type with a fixed set of named variants that may carry associated data and methods.
product typeA product type is a composite type whose possible values are combinations of values from all its component fields.
additive featureAn additive feature is a crate feature that only adds functionality and does not disable functionality already available.
conditional compilationConditional compilation is the selection of source items for compilation based on compile-time configuration conditions.
returntypeReturnType is a syn syntax structure representing a Rust function's return-type syntax, including either no explicit type or an arrow followed by a type.
AWSAWS is Amazon Web Services, a cloud computing platform providing infrastructure and managed application services.
AWS CloudFormationAWS CloudFormation is an AWS infrastructure-as-code service that provisions and updates resources from declarative templates.
no-panicno-panic is a Rust procedural macro library that statically verifies that annotated functions cannot panic.
absolute pathA full path is a Rust path that identifies an item through its complete namespace qualification.

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.