Describes a Data encoded Plutarch type that requires some additional validation to ensure its structure is indeed what we expect. This is especially useful for datums or other user-supplied arguments, since these can be malformed.

Why the CPS

pwithValidated is written in continuation-passing style (or CPS) for reasons of efficiency. As pwithValidated is meant to check structure (and nothing more), our first instinct would be to write something like

pwithValidated :: Term s PData -> Term s PBool

or

pwithValidated :: Term s PData -> Term s PUnit

and rely on perror to sort things out. However, constructing either PUnit or PBool isn't free, and ultimately, this value ends up unused. At the same time, we want to ensure that the validation specified in pwithValidated is actually performed, which neither of the above signatures can promise anything about.

CPS solves both of these problems. Since the result of pwithValidated is technically a function that must behave the same no matter what type of r it operates over, we can't do anything except potentially mess with the argument PData or error out, which means we don't need to allocate any 'result value'. Furthermore, by working in CPS, we ensure that any validation defined in pwithValidated must happen, even if the PData (or whatever it's supposed to be) is never handled or forced.

Important note

It is essential practice to document what exactly any given instance of PValidateData checks. Each instance should specify this: all the instances provided by Plutarch and its related libraries follow this rule.

Since: 1.12.0

Given a PData, check that it is, indeed, structured as a expects. If it is, return that same PData 'rewrapped' into PAsData a.

This helper exists to avoid having to work in CPS when writing regular code. It is kept out of PValidateData for efficiency and safety reasons.

Since: 1.12.0

Helper to define a do-nothing instance of PValidateData. Useful when defining an instance for a complex type where we want to validate some parts, but not others.

Since: 1.12.0

Helper to define an instance of PValidateData for newtypes over Terms, which 'borrows' the PValidateData instance for whatever the newtype is wrapping.

Since: 1.12.0