Skip to content

docs: use one notation for effect annotations - #341

Merged
magnus-madsen merged 1 commit into
masterfrom
docs/effect-notation
Oct 12, 2026
Merged

magnus-madsen merged 1 commit into
masterfrom
docs/effect-notation

Conversation

@magnus-madsen

Copy link
Copy Markdown
Member

Applies one style to every effect annotation in the book, resolving the notation part of #283.

Rules

  • A single effect has no braces: \ IO, \ ef, \ r.
  • Two or more concrete effects use set braces with inner spaces: \ { Http, IO }. Concrete effects are never joined with +.
  • IO comes last.
  • Effect variables never go inside braces. They come first, joined by +, followed by one bare effect or one braced set: \ ef + IO, \ ef1 + ef2 + { Http, IO }, \ r + { Clock, Http, IO }.
  • Pure functions carry no annotation. \ {} appears only where the text is explicitly about the empty effect set.
  • Associated effects such as Aef[m] count as concrete: \ { Aef[m], IO }.

Changes

  • Six singleton sets lose their braces (effects-and-handlers, effect-oriented-programming, effect-polymorphism, logger).
  • Every multi-effect set gains inner spaces (concurrency, introduction, effect-oriented-programming, default-handlers, main, effects-and-handlers, effect-polymorphism).
  • Assert + IO, IO + Aef[m], and Emit[Int32] + Emit[String] become braced sets, which also moves IO last in java-collections.
  • The CPS example in for-llms takes ef + Sleep; mutable-collections and effect-polymorphism use r + IO and r + { Clock, Http, IO }.
  • { } becomes {} in the effect-polymorphism chapter.

Verification

  • A scratch file using every new form, including ef + Sleep in parameter position, r + { ... }, and { Foldable.Aef[m], IO }, compiles and runs on Flix 0.78.0.
  • The quoted E6795 error in polymorphic-effects and common-problems was regenerated from the compiler; only the caret column changes.
  • Comment carets under the rewritten signatures in effect-polymorphism were realigned, and mdbook build succeeds.

Not included: the trailing-semicolon and "pair" vs "tuple" remarks from the second comment on #283, which concern the references chapter and are unrelated to effect notation.

🤖 Generated with Claude Code

Apply a single style to every effect annotation in the book:

- A single effect has no braces: `\ IO`, `\ ef`, `\ r`.
- Two or more concrete effects use set braces with inner spaces:
  `\ { Http, IO }`. Concrete effects are never joined with `+`.
- `IO` comes last.
- Effect variables never go inside braces. They come first, joined
  by `+`, followed by one bare effect or one braced set:
  `\ ef + IO`, `\ r + { Clock, Http, IO }`.
- Pure functions carry no annotation; `\ {}` appears only where the
  text is explicitly about the empty effect set.

The quoted compiler error in the polymorphic-effects and
common-problems chapters was regenerated with Flix 0.78.0 so its
caret matches the rewritten source line. Comment carets in the
effect-polymorphism chapter were realigned.

Refs #283

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@magnus-madsen
magnus-madsen merged commit 3e77057 into master Oct 12, 2026
1 check passed
@magnus-madsen
magnus-madsen deleted the docs/effect-notation branch October 12, 2026 10:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant