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 - the procedure is an entry-point for the program when called from the terminal
@unittest - the procedure is a unit test
@allocator - 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 - 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 - the procedure is a finesse, which implies it is @sideffectfree, @transparent and @const.
@function - the procedure is a function, which implies @sideffectfree, @transparent and @const.
@leakproof - the procedure does not write to external mutable store.
@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 - the procedure does not perform any I/O.
@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 - 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:

General procedures that can do anything - just called procedures
Allocators that can only use assignments on local store, only take const inputs, do not do i/o
Clean procedures that can't use assignments or i/o but can only call cleans, finesses or functions - called clean procedures or 'cleans'
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
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