Documentation

Stands for representation of some Haskell ADT corresponding to Michelson value. Type parameter a is what you put in place of each field of the datatype, e.g. information about field type.

This representation also includes descriptions of constructors and fields.

Representation of a constructor with an optional description.

Representation of a field with an optional description.

Whether given text should be rendered grouped in parentheses (if they make sense).

Description for a Haskell type appearing in documentation.

Generic-deriving instance produces a custom error when Generic is missing:

>>> data Foo = Foo () deriving TypeHasDoc
...
... GHC.Generics.Rep Foo
... is stuck. Likely
... Generic Foo
... instance is missing or out of scope.
...

>>> data Foo = Foo () deriving Generic
>>> instance TypeHasDoc Foo where typeDocMdDescription = "Foo"
...
... No instance for (IsoValue Foo)
...

>>> data Foo = Foo () deriving (Generic, IsoValue)
>>> instance TypeHasDoc Foo where typeDocMdDescription = "Foo"

Field naming strategy used by a type. id by default.

Some common options include: > typeFieldNamingStrategy = stripFieldPrefix > typeFieldNamingStrategy = toSnake . dropPrefix

This is used by the default implementation of typeDocHaskellRep and intended to be reused downstream.

You can also use DerivingVia together with FieldCamelCase and FieldSnakeCase to easily define instances of this class:

data MyType = ... deriving TypeHasFieldNamingStrategy via FieldCamelCase

Empty datatype used as marker for DerivingVia with TypeHasFieldNamingStrategy.

Uses stripFieldPrefix strategy.

Empty datatype used as marker for DerivingVia with TypeHasFieldNamingStrategy.

Uses toSnake . dropPrefix strategy.

Signature of typeDocHaskellRep function.

A value of FieldDescriptionsV is provided by the library to make sure that instances won't replace it with an unchecked value.

When value is Just, it contains types which this type is built from.

First element of provided pair may contain name a concrete type which has the same type constructor as a (or just a for homomorphic types), and the second element of the pair - its unfolding in Haskell.

For example, for some newtype MyNewtype = MyNewtype (Integer, Natural) we would not specify the first element in the pair because MyNewtype is already a concrete type, and second element would contain (Integer, Natural). For polymorphic types like newtype MyPolyNewtype a = MyPolyNewtype (Text, a), we want to describe its representation on some example of a, because working with type variables is too non-trivial; so the first element of the pair may be e.g. "MyPolyNewType Integer", and the second one shows that it unfolds to (Text, Integer).

When rendered, values of this type look like:

• (Integer, Natural) - for homomorphic type.
• MyError Integer = (Text, Integer) - concrete sample for polymorphic type.

Signature of typeDocMichelsonRep function.

As in TypeDocHaskellRep, set the first element of the pair to Nothing for primitive types, otherwise it stands as some instantiation of a type, and its Michelson representation is given in the second element of the pair.

Examples of rendered representation:

• pair int nat - for homomorphic type.
• MyError Integer = pair string int - concrete sample for polymorphic type.

Description of constructors and fields of some datatype.

This type is just two nested maps represented as associative lists. It is supposed to be interpreted like this:

[(Constructor name, (Maybe constructor description, [(Field name, Field description)]))]

Example with a concrete data type:

data Foo
  = Foo
      { fFoo :: Int
      }
  | Bar
      { fBar :: Text
      }
  deriving (Generic)

type FooDescriptions =
  '[ '( "Foo", '( 'Just "foo constructor",
      , '[ '("fFoo", "some number")
         ])
      )
   , '( "Bar", '( 'Nothing,
      , '[ '("fBar", "some string")
         ])
      )
   ]

Constraint, required when deriving TypeHasDoc for polymorphic type with the least possible number of methods defined manually.

Data hides some type implementing TypeHasDoc.

Fully render Michelson representation of a type.

Since this will be used in markdown, the type is forced to a single line.

>>> data Foo = Foo () () () () () () () () () () () () deriving (Generic, IsoValue)
>>> instance TypeHasDoc Foo where typeDocMdDescription = "Foo type"
>>> typeDocBuiltMichelsonRep $ Proxy @Foo
**Final Michelson representation:** `pair (pair (pair unit unit unit) unit unit unit) (pair unit unit unit) unit unit unit`

Require two types to be built from the same type constructor.

E.g. HaveCommonTypeCtor (Maybe Integer) (Maybe Natural) is defined, while HaveCommonTypeCtor (Maybe Integer) [Integer] is not.

Require this type to be homomorphic.

Implement typeDocDependencies via getting all immediate fields of a datatype.

Produces a custom error message for missing Generic instances:

>>> data Foo = Foo ()
>>> length $ genericTypeDocDependencies $ Proxy @Foo
...
... GHC.Generics.Rep Foo
... is stuck. Likely
... Generic Foo
... instance is missing or out of scope.
...

>>> data Foo = Foo () deriving Generic
>>> length $ genericTypeDocDependencies $ Proxy @Foo
1

Note: this will not include phantom types, I'm not sure yet how this scenario should be handled (@martoon).

Render a reference to a type which consists of type constructor (you have to provide name of this type constructor and documentation for the whole type) and zero or more type arguments.

More generic version of customTypeDocMdReference, it accepts arguments not as types with doc, but printers for them.

Derive typeDocMdReference, for homomorphic types only.

Derive typeDocMdReference, for polymorphic type with one type argument, like Maybe Integer.

Derive typeDocMdReference, for polymorphic type with two type arguments, like Lambda Integer Natural.

Implement typeDocHaskellRep for a homomorphic type.

Note that it does not require your type to be of IsHomomorphic instance, which can be useful for some polymorphic types which, for documentation purposes, we want to consider homomorphic.

Example: Operation is in fact polymorphic, but we don't want this fact to be reflected in the documentation.

Produces a custom error message for missing Generic instances:

>>> data Foo = Foo ()
>>> isJust $ homomorphicTypeDocHaskellRep (Proxy @Foo) []
...
... GHC.Generics.Rep Foo
... is stuck. Likely
... Generic Foo
... instance is missing or out of scope.
...

>>> data Foo = Foo () deriving Generic
>>> isJust $ homomorphicTypeDocHaskellRep (Proxy @Foo) []
True

Implement typeDocHaskellRep on example of given concrete type.

This is a best effort attempt to implement typeDocHaskellRep for polymorphic types, as soon as there is no simple way to preserve type variables when automatically deriving Haskell representation of a type.

Produces a custom error message for missing Generic instances:

>>> data Foo a = Foo a
>>> isJust $ concreteTypeDocHaskellRep @(Foo Integer) @(Foo ()) Proxy []
...
... GHC.Generics.Rep (Foo Integer)
... is stuck. Likely
... Generic (Foo Integer)
... instance is missing or out of scope.
...

>>> data Foo a = Foo a deriving (Generic, IsoValue)
>>> isJust $ concreteTypeDocHaskellRep @(Foo Integer) @(Foo ()) Proxy []
True

Version of concreteTypeDocHaskellRep which does not ensure whether the type for which representation is built is any similar to the original type which you implement a TypeHasDoc instance for.

>>> data Foo = Foo ()
>>> isJust $ unsafeConcreteTypeDocHaskellRep @Foo @() Proxy []
...
... GHC.Generics.Rep Foo
... is stuck. Likely
... Generic Foo
... instance is missing or out of scope.
...

>>> data Foo = Foo () deriving (Generic, IsoValue)
>>> isJust $ unsafeConcreteTypeDocHaskellRep @Foo @() Proxy []
True

Add field name for newtype.

Since newtype field is automatically erased. Use this function to add the desired field name.

Erase fields from Haskell datatype representation.

Use this when rendering fields names is undesired.

Like haskellRepAdjust, but can't add or remove field names.

Adjust field names using a function. Can add or remove field names.

Implement typeDocMichelsonRep for homomorphic type.

Implement typeDocMichelsonRep on example of given concrete type.

This function exists for the same reason as concreteTypeDocHaskellRep.

Version of unsafeConcreteTypeDocHaskellRep which does not ensure whether the type for which representation is built is any similar to the original type which you implement a TypeHasDoc instance for.

Doc element with description of a type.

Doc element with description of contract storage type.

Shortcut for DStorageType.

Generic traversal for automatic deriving of some methods in TypeHasDoc.

Product type traversal for TypeHasDoc.

Create a DType in form suitable for putting to typeDocDependencies.

Proxy version of dTypeDep.

Show given ADTRep in a neat way.

Show type, wrapping into parentheses if necessary.