lorentz-0.6.0: EDSL for the Michelson Language
Safe HaskellNone
LanguageHaskell2010

Lorentz.Entrypoints.Doc

Description

Utilities for declaring and documenting entry points.

Synopsis

Documentation

data DEntrypoint (kind :: Type) Source #

Gathers information about single entrypoint.

We assume that entry points might be of different kinds, which is designated by phantom type parameter. For instance, you may want to have several groups of entry points corresponding to various parts of a contract - specifying different kind type argument for each of those groups will allow you defining different DocItem instances with appropriate custom descriptions for them.

Constructors

DEntrypoint 

Fields

Instances

Instances details
Eq (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

Ord (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

Show (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

DocItem (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

type DocItemPlacement (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

type DocItemReferenced (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

class EntryArrow kind name body where Source #

Provides arror for convenient entrypoint documentation

Methods

(#->) :: (Label name, Proxy kind) -> body -> body Source #

Lift entrypoint implementation.

Entrypoint names should go with "e" prefix.

Instances

Instances details
(name ~ AppendSymbol "e" epName, body ~ ((param & s) :-> out), KnownSymbol epName, DocItem (DEntrypoint kind), TypeHasDoc param, HasAnnotation param, KnownValue param) => EntryArrow (kind :: Type) name body Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

Methods

(#->) :: (Label name, Proxy kind) -> body -> body Source #

data PlainEntrypointsKind Source #

Default value for DEntrypoint type argument.

Instances

Instances details
Eq (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

Ord (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

Show (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

DocItem (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

type DocItemPlacement (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

type DocItemReferenced (DEntrypoint PlainEntrypointsKind) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

diEntrypointToMarkdown :: HeaderLevel -> DEntrypoint level -> Markdown Source #

Default implementation of docItemToMarkdown for entry points.

data DEntrypointArg Source #

Describes argument of an entrypoint.

Constructors

DEntrypointArg 

Fields

  • epaArg :: Maybe DType

    Argument of the entrypoint. Pass Nothing if no argument is required.

  • epaBuilding :: [ParamBuildingStep]

    Describes a way to lift an entrypoint argument into full parameter which can be passed to the contract.

    Steps are supposed to be applied in the order opposite to one in which they are given. E.g. suppose that an entrypoint is called as Run (Service1 arg); then the first step (actual last) should describe wrapping into Run constructor, and the second step (actual first) should be about wrapping into Service1 constructor.

  • epaType :: Type

    Untyped representation of entrypoint, used for printing its michelson type representation.

data DType where #

Constructors

DType :: forall a. TypeHasDoc a => Proxy a -> DType 

Instances

Instances details
Eq DType 
Instance details

Defined in Michelson.Typed.Haskell.Doc

Methods

(==) :: DType -> DType -> Bool #

(/=) :: DType -> DType -> Bool #

Ord DType 
Instance details

Defined in Michelson.Typed.Haskell.Doc

Methods

compare :: DType -> DType -> Ordering #

(<) :: DType -> DType -> Bool #

(<=) :: DType -> DType -> Bool #

(>) :: DType -> DType -> Bool #

(>=) :: DType -> DType -> Bool #

max :: DType -> DType -> DType #

min :: DType -> DType -> DType #

Show DType 
Instance details

Defined in Michelson.Typed.Haskell.Doc

Methods

showsPrec :: Int -> DType -> ShowS #

show :: DType -> String #

showList :: [DType] -> ShowS #

DocItem DType 
Instance details

Defined in Michelson.Typed.Haskell.Doc

Associated Types

type DocItemPlacement DType :: DocItemPlacementKind #

type DocItemReferenced DType :: DocItemReferencedKind #

type DocItemPlacement DType 
Instance details

Defined in Michelson.Typed.Haskell.Doc

type DocItemReferenced DType 
Instance details

Defined in Michelson.Typed.Haskell.Doc

class KnownSymbol con => DeriveCtorFieldDoc con (cf :: CtorField) where Source #

Pick a type documentation from CtorField.

Instances

Instances details
KnownSymbol con => DeriveCtorFieldDoc con 'NoFields Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

(TypeHasDoc ty, HasAnnotation ty, KnownValue ty, KnownSymbol con) => DeriveCtorFieldDoc con ('OneField ty) Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

newtype ParamBuilder Source #

When describing the way of parameter construction - piece of incremental builder for this description.

Constructors

ParamBuilder 

Fields

  • unParamBuilder :: Markdown -> Markdown

    Argument stands for previously constructed parameter piece, and returned value - a piece constructed after our step.

Instances

Instances details
Eq ParamBuilder Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

Show ParamBuilder Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

Buildable ParamBuilder Source # 
Instance details

Defined in Lorentz.Entrypoints.Doc

data ParamBuildingDesc Source #

Constructors

ParamBuildingDesc 

Fields

data ParamBuildingStep Source #

Describes a parameter building step.

This can be wrapping into (Haskell) constructor, or a more complex transformation.

Constructors

PbsWrapIn Text ParamBuildingDesc

Wraps something into constructor with given name. Constructor should be the one which corresponds to an entrypoint defined via field annotation, for more complex cases use PbsCustom.

PbsCallEntrypoint EpName

Directly call an entrypoint marked with a field annotation.

PbsCustom ParamBuildingDesc

Other action.

PbsUncallable [ParamBuildingStep]

This entrypoint cannot be called, which is possible when an explicit default entrypoint is present. This is not a true entrypoint but just some intermediate node in or tree and neither it nor any of its parents are marked with a field annotation.

It contains dummy ParamBuildingSteps which were assigned before entrypoints were taken into account.

mkPbsWrapIn :: Text -> ParamBuilder -> ParamBuildingStep Source #

Make a ParamBuildingStep that tells about wrapping an argument into a constructor with given name and uses given ParamBuilder as description of Michelson part.

clarifyParamBuildingSteps :: ParamBuildingStep -> (inp :-> out) -> inp :-> out Source #

Go over contract code and update every occurrence of DEntrypointArg documentation item, adding the given step to its "how to build parameter" description.

mkUType :: forall (x :: T). SingI x => Notes x -> Type #

mkDEpUType :: forall t. (KnownValue t, HasAnnotation t) => Type Source #

type DocumentEntrypoints kind a = (Generic a, GDocumentEntrypoints kind (Rep a)) Source #

Constraint for documentEntrypoints.

documentEntrypoint :: forall kind epName param s out. (KnownSymbol epName, DocItem (DEntrypoint kind), TypeHasDoc param, HasAnnotation param, KnownValue param) => ((param & s) :-> out) -> (param & s) :-> out Source #

Wrapper for documenting single entrypoint which parameter isn't going to be unwrapped from some datatype.

entryCase unwraps a datatype, however, sometimes we want to have entrypoint parameter to be not wrapped into some datatype.

entryCase :: forall dt entrypointKind out inp clauses. (CaseTC dt out inp clauses, DocumentEntrypoints entrypointKind dt) => Proxy entrypointKind -> IsoRecTuple clauses -> (dt & inp) :-> out Source #

Version of entryCase_ for tuples.

entryCase_ :: forall dt entrypointKind out inp. (InstrCaseC dt, RMap (CaseClauses dt), DocumentEntrypoints entrypointKind dt) => Proxy entrypointKind -> Rec (CaseClauseL inp out) (CaseClauses dt) -> (dt & inp) :-> out Source #

Like case_, to be used for pattern-matching on a parameter or its part.

Modifies documentation accordingly. Including description of entrypoints' arguments, thus for them you will need to supply TypeHasDoc instance.

finalizeParamCallingDoc :: forall cp inp out. (NiceParameterFull cp, RequireSumType cp, HasCallStack) => ((cp ': inp) :-> out) -> (cp ': inp) :-> out Source #

Modify param building steps with respect to entrypoints that given parameter declares.

Each contract with entrypoints should eventually call this function, otherwise, in case if contract uses built-in entrypoints feature, the resulting parameter building steps in the generated documentation will not consider entrypoints and thus may be incorrect.

Calling this twice over the same code is also prohibited.

areFinalizedParamBuildingSteps :: [ParamBuildingStep] -> Bool Source #

Whether finalizeParamCallingDoc has already been applied to these steps.

entryCaseSimple_ :: forall cp out inp. (InstrCaseC cp, RMap (CaseClauses cp), DocumentEntrypoints PlainEntrypointsKind cp, NiceParameterFull cp, RequireFlatParamEps cp) => Rec (CaseClauseL inp out) (CaseClauses cp) -> (cp & inp) :-> out Source #

entryCaseSimple :: forall cp out inp clauses. (CaseTC cp out inp clauses, DocumentEntrypoints PlainEntrypointsKind cp, NiceParameterFull cp, RequireFlatParamEps cp) => IsoRecTuple clauses -> (cp & inp) :-> out Source #

Version of entryCase for contracts with flat parameter, use it when you need only one entryCase all over the contract implementation.

This method calls finalizeParamCallingDoc inside.

type family RequireFlatEpDerivation cp deriv :: Constraint where ... Source #

Equations

RequireFlatEpDerivation _ EpdNone = () 
RequireFlatEpDerivation _ EpdPlain = () 
RequireFlatEpDerivation cp deriv = TypeError (('Text "Parameter is not flat" :$$: (('Text "For parameter `" :<>: 'ShowType cp) :<>: 'Text "`")) :$$: (('Text "With entrypoints derivation way `" :<>: 'ShowType deriv) :<>: 'Text "`"))