Annotations - Spicery/Nutmeg GitHub Wiki

Overview

Annotations are additional information or modifications applied to a procedure that typically conveys the intent of the coder for how that procedure is to be used. You can stack as many annotations as you like in front of a procedure definition. e.g.

[clean]
[const(in)]
[leakproof]
def add1( n ): n + 1 enddef

At this time there is no support for adding user annotations. This would count as a user-defined language extension, which is a planned feature.

List of Annotations

  • command(Commands) - the procedure is an entry-point for the program when called from the terminal
  • unittest(Unittests) - the procedure is a unit test
  • allocator(Allocators) - the procedure is an allocator ([transparent], [const(in)])
  • [[sideffectfree - the procedure does not detectably mutate store ([leakproof]) nor detectably perform I/O ([soundproof]). It is at liberty to use side-effects that are not detectable from the outside.
  • clean(Clean) - the procedure is written without <-- assignments or using I/O internally. It also only invokes other [clean] or [sideffectfree] procedures. This implies it is [sideeffectfree].
  • finesse(Finesses) - the procedure is a finesse, which implies it is [sideffectfree], [transparent] and [const].
  • function(Functions) - the procedure is a function, which implies [sideffectfree], [transparent] and [const].
  • leakproof(Leakproof) - the procedure does not write to external mutable store.
  • impervious(Impervious) - the procedure does not read or write to external mutable store - internal store can be referenced. Note that being [impervious] implies [const(in)].
  • soundproof(Soundproof) - the procedure does not perform any I/O.
  • transparent(Transparent) - the procedure is both [impervious] and [soundproof]. Hence its outputs depend only on the inputs so that the same inputs will always deliver the same results.
  • [const(in)], [const(out)], [const] - the procedure only has const inputs, const outputs or both
  • [val(in)], [val(out)], [val] - the procedure only has val (or const) inputs, val (or const) outputs or both throughout
  • resource(Resources)] - the value is loaded at runtime from the resources
  • [local], [nonlocal] - scope within a block/endblock construct
  • lazy[Lazy] - the procedure defers all arguments involved in function calls (i.e. yields futures)

Fundamental Annotations

The following annotations relate to core concepts in Nutmeg.

  • [clean]
  • [leakproof] & [impervious]
  • [soundproof]
  • [const(in)], [const(out)], [const]
  • [val(in)], [val(out)], [val]

Procedures fall into a rough hierarchy of function-ness in Nutmeg:

  1. General procedures that can do anything - just called procedures
  2. Allocators that can only use assignments on local store, only take const inputs, do not do i/o
  3. Clean procedures that can't use assignments or i/o but can only call cleans, finesses or functions - called clean procedures or 'cleans'
  4. Finesses that only accept and return const values, do not perform i/o or assign non-local store and can only call other finesses or functions
  5. Functions that only accept and return const values, do not perform i/o, can't use side-effects and can only call other finesses or functions

They are related by which properties they have from

  • Side-effect free: [clean] - clean procedures and functions
  • Do not affect non-local store: [leakproof] - finesses, allocators and functions
  • const inputs: [const(in)] - finesses, allocators and functions
  • const outputs: [const(out)] - finesses and functions

Venn diagram of annotations