Computations

Support writing "well-behaved" computations. Such computations declare a Contract describing their inputs and outputs. This is enforced, so that the implementation need not worry about missing inputs, and the caller can rely on the results. It is also self-documenting, so the generated documentation is always contains a clear up-to-date description of the contract.

@computation function something(...)
    return ...
end

@computation Contract(...) function something(daf::DafWriter, ...)
    return ...
end

@computation Contract(...) Contract(...) function something(
    first::DafReader/DafWriter, second::DafReader/DafWriter, ...
)
    return ...
end

Mark a function as a Daf computation. This has the following effects:

• It verifies that the Daf data satisfies the Contract , when the computation is invoked and when it is complete (using verify_input and verify_output ).

• It stashes the contract(s) (if any) in a global variable. This allows expanding CONTRACT in the documentation string (for a single contract case), or CONTRACT1 and CONTRACT2 (for the dual contract case).

• It stashes the default value of named arguments. This allows expanding DEFAULT in the documentation string, which is especially useful if these defaults are computed, read from global constants, etc.

• It logs the invocation of the function (using @debug ), including the actual values of the named arguments (using depict ).

function_contract(func::Function[, index::Integer = 1])::Contract

Access the contract of a function annotated by @computation . By default the first contract is returned. If the @computation has two contracts, you can specify the index of the contract to return.

function_default(func::Function, parameter::Symbol)::Contract

Access the default of a parameter of a function annotated by @computation .

When using @computation :

'''
    something(daf::DafWriter, x::Int = $(DEFAULT.x); y::Bool = $(DEFAULT.y))

...
If `x` (default: $(DEFAULT.y)) is even, ...
...
If `y` (default: $(DEFAULT.y)) is set, ...
...
'''
@computation Contract(...) function something(daf::DafWriter, x::Int = 0; y::Bool = false)
    return ...
end

Then $(DEFAULT.x) will be expanded with the default value of the parameter x . It is good practice to contain a description of the effects of each parameter somewhere in the documentation, and it is polite to also provide its default value. This can be done in either the signature line or in the text, or both. Using DEFAULT ensures that the correct value is used in the documentation.

When using @computation :

'''
...
# Contract
...
$(CONTRACT)
...
'''
@computation Contract(...) function something(daf::DafWriter, ...)
    return ...
end

Then $(CONTRACT) will be expanded with a description of the Contract . This is based on DocStringExtensions .

Same as CONTRACT , but reference the contract for the 1st Daf argument for a @computation with two such arguments.

Same as CONTRACT , but reference the contract for the 2nd Daf argument for a @computation with two such arguments.