ValidLiterals.Class

WARNING: For implementors of new Validate instances only!

This module exposes functions whose use is easily screwed up. Users of validated literals should use the interface exported by ValidLiterals. This module only exists for implementers of new Validate instances.

Documentation

class Validate a b where

Class for validated, compile-time, partial conversions from type a to b.

Minimal complete definition

fromLiteral

Methods

fromLiteral :: a -> Maybe b

Converts a values into validated b values

spliceValid :: a -> b -> Q (TExp b)

WARNING: Don't use! For implementors of Validate instances only!

Produces the actual Typed Template Haskell splice for the validated value to splice into the source text. Since you may want to implement a Validate instance for types that cannot have Lift instances, this function receives both the original a value and the resulting b as input.

This allows it to either:

1. Splice the resulting b into the source using it's Lift instance, or a custom splice.
2. Splice the initial a into the source using it's Lift instance, and perform the conversion again at runtime, and coercing via, e.g., fromJust. Since fromLiteral is pure (right?!) this should be perfectly safe.

Clearly, splicing the result directly is much safer (it avoids any shenanigans with unsafePerformIO) and more efficient (no conversion at runtime). However, this is just not always possible, since, for example, ByteString does not have a Lift instance and we may still want to have validated newtypes of ByteString.

Default implementation: The default implementation (using DefaultSignatures) uses b's Lift instance to do the efficient thing of directly splicing the resulting b into the source.

spliceValid :: Lift b => a -> b -> Q (TExp b)

WARNING: Don't use! For implementors of Validate instances only!

Produces the actual Typed Template Haskell splice for the validated value to splice into the source text. Since you may want to implement a Validate instance for types that cannot have Lift instances, this function receives both the original a value and the resulting b as input.

This allows it to either:

1. Splice the resulting b into the source using it's Lift instance, or a custom splice.
2. Splice the initial a into the source using it's Lift instance, and perform the conversion again at runtime, and coercing via, e.g., fromJust. Since fromLiteral is pure (right?!) this should be perfectly safe.

Clearly, splicing the result directly is much safer (it avoids any shenanigans with unsafePerformIO) and more efficient (no conversion at runtime). However, this is just not always possible, since, for example, ByteString does not have a Lift instance and we may still want to have validated newtypes of ByteString.

Default implementation: The default implementation (using DefaultSignatures) uses b's Lift instance to do the efficient thing of directly splicing the resulting b into the source.

hackySpliceValid :: (Lift a, Validate a b) => a -> b -> Q (TExp b)

Default implementation for spliceValid, uses the Lift instance for a and fromJust to redo the conversion at runtime and (unsafely) coerce from 'Maybe b' to b. . Since fromLiteral is pure (right?!) this should be perfectly safe.