TSPL Pitch: Macros and parameter packs

For macros, the new conceptual content will go in the guide in a new Macros chapter, following the existing Concurrency chapter. The high-level outline is as follows (for a detailed outline, see the work in progress linked below):

  • Intro: what's a macro?
  • Using a freestanding macro to produce a value
  • Applying an attached macro to a declaration
  • How macros are expanded
  • How to declare your own macros
  • How to implement a macro. This will highlight some of the most important APIs from SwiftSyntax and link there for more details.
  • Tips for debugging and developing macros, including guidance to use unit tests for your macros.

The reference will need a new section in Declarations for macro declarations, as well as updates in Attributes for @freestanding and @attached.

For parameter packs, the new conceptual content will go in the guide under a new section in the Generics chapter. The high-level outline is as follows (for a detailed outline, see the work in progress linked below):

  • Why parameter packs? To define APIs that vary in arity, without using type erasure.
  • How do you create a parameter pack?
  • How do you repeat more than one type?
  • How do you access the values of a parameter pack?

The reference will need updates in Expressions and Types.

My work so far is on the macros and pack_102835487 branches.


This seems like a good start, but it would be clearer if terms like pack and expansion are defined and exemplified before they are used in rules. In general I think it would be helpful if the large number of new terms and concepts that are introduced with the parameter pack feature would be explained with examples instead of abstract descriptions, not just here but in pitches and proposals.


In the "How to declare your own macros" section, will it cover for both freestanding and attached macros?

I think it will need to, because the approach and APIs you use for a freestanding vs attached macro are different. The discussion of creating macros can start with a freestanding macro, which I can show with an example that doesn't need to read the AST. That lets me show the code for declaring and defining a macro. Then a later example can show an attached macro, which does use the Swift Syntax APIs to read the AST.

EDIT: Replying to @Genaro-Chris's question.

1 Like

In TSPL, it will certainly be the case that new terms are defined when they're first used. In the legacy RST pipeline, we even used special markup for "a new term is being introduced and defined here" — in markdown, it's just italics.

If you're meaning to give feedback about the Swift Evolution proposal, that's certainly welcome — but the authors of the proposal aren't necessarily reading this forum post, so this isn't the best place to share it. The definition I've been looking at for parameter packs is in SE-0393 in the list after "Here are the key concepts introduced by this proposal".

The pull request for macros is here: