From 39d7ced75f0de30f56bba18f97fd7e4633fff5f6 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Fri, 6 Dec 2019 17:36:47 +1100 Subject: [PATCH] Add doc/note/effects.md --- doc/glossary.md | 11 +++-------- doc/note/effects.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 8 deletions(-) create mode 100644 doc/note/effects.md diff --git a/doc/glossary.md b/doc/glossary.md index 9750bd40..92b46897 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -16,14 +16,9 @@ but they're not the only way. Wuffs does not use them. #### Effect -An extension of the type system, applied to functions. Wuffs has three effect -categories: pure, impure and coroutine. Pure means that the function has no -side effects - it does not change any observable state. The other two -categories may have side effects, with [coroutines](/doc/note/coroutines.md) -also being able to suspend and resume. - -Impure functions are marked with a `!` at their definition and at call sites. -Coroutines are similarly marked, with a `?`. Pure functions have no mark. +An extension of the type system, such as purity (freedom from side effects), +applied to functions. See the [effects](/doc/note/effects.md) note for more +details. #### Fact diff --git a/doc/note/effects.md b/doc/note/effects.md new file mode 100644 index 00000000..408ea539 --- /dev/null +++ b/doc/note/effects.md @@ -0,0 +1,32 @@ +# Effects + +Wuffs functions have one of three effects: pure, impure and coroutine. Pure +means that the function has no side effects - it does not change any observable +state. For example, the body of a pure function (with a `this` receiver) cannot +assign to a `this.foo` field. The other two categories may have side effects, +with [coroutines](/doc/note/coroutines.md) also being able to suspend and +resume. + +Impure functions are marked with a `!` at their definition and at call sites. +Coroutines are similarly marked, with a `?`. Pure functions have no mark. + +For those used to C/C++ syntax, in Wuffs, the unary not operator is spelled +`not` instead of `!`, and Wuffs has no ternary operator like C/C++'s `?`. + +Sub-expressions in Wuffs must be pure. Only the outermost function call can +have a `!` or `?` mark. You can't write: + +``` +foo!(bar(), baz!(), qux) +``` + +Instead, you have to explicitly split it. + +``` +b = baz!() +foo!(bar(), b, qux) +``` + +For similar reasons, `x += 1` is a statement in Wuffs, not an expression. This +avoids the ambiguous order of execution in C/C++'s `x = x++`, which is actually +undefined behavior.