GitHub

Computations

DataAxesFormats.Computations — Module

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.

DataAxesFormats.Computations.@computation — Macro 
@computation Contract(...) function something(daf::DafWriter, ...)
    return ...
end

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

@computation Contract(...) Contract(name = "second", ...) Contract(name = "third", ...) function something(
    first::DafReader/DafWriter; second::DafReader/DafWriter, third::DafReader/DafWriter, ...
)
    return ...
end

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

  • It has the same effect as @documented , that is, allows using DEFAULT in the documentation string, and using function_default to access the default value of named parameters.
  • 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), or CONTRACT1 and CONTRACT2 and CONTRACT3 (for the triple contract case).
Note

For each Contract parameter (if any), there needs to be a DafReader or DafWriter , which the contract(s) will be applied to. These parameters should be the initial positional parameters of the function.

DataAxesFormats.Computations.CONTRACT — Constant

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 .

Note

The first argument of the function must be a DafWriter , which the contract will be applied to.

Index