Module Prelude¶

The pieces that make up the Daml language.

Typeclasses¶

class Action m => CanAssert m where

Constraint that determines whether an assertion can be made in this context.

assertFail
: Text -> m t

Abort since an assertion has failed. In an Update, Scenario, Script, or Trigger context this will throw an AssertionFailed exception. In an Either Text context, this will return the message as an error.

instance CanAssert Scenario

instance CanAssert Update

instance CanAssert (Either Text)

class HasInterfaceTypeRep i where

(Daml-LF >= 1.15) Exposes the interfaceTypeRep function. Available only for interfaces.

class HasToInterface t i where

(Daml-LF >= 1.15) Exposes the toInterface and toInterfaceContractId functions.

class HasFromInterface t i where

(Daml-LF >= 1.15) Exposes fromInterface and fromInterfaceContractId functions.

fromInterface
: i -> Optional t

(Daml-LF >= 1.15) Attempt to convert an interface value back into a template value. A None indicates that the expected template type doesn’t match the underyling template type for the interface value.

For example, fromInterface @MyTemplate value will try to convert the interface value value into the template type MyTemplate.

class HasInterfaceView i v where

_view
: i -> v

class HasTime m where

The HasTime class is for where the time is available: Scenario and Update.

getTime
: HasCallStack => m Time

Get the current time.

instance HasTime Scenario

instance HasTime Update

class Action m => CanAbort m where

The CanAbort class is for Action s that can be aborted.

abort
: Text -> m a

Abort the current action with a message.

instance CanAbort Scenario

instance CanAbort Update

instance CanAbort (Either Text)

class HasSubmit m cmds where

submit
: HasCallStack => Party -> cmds a -> m a

submit p cmds submits the commands cmds as a single transaction from party p and returns the value returned by cmds.

If the transaction fails, submit also fails.

submitMustFail
: HasCallStack => Party -> cmds a -> m ()

submitMustFail p cmds submits the commands cmds as a single transaction from party p.

It only succeeds if the submitting the transaction fails.

instance HasSubmit Scenario Update

class Functor f => Applicative f where

pure
: a -> f a

Lift a value.

(<*>)
: f (a -> b) -> f a -> f b

Sequentially apply the function.

A few functors support an implementation of <*> that is more efficient than the default one.

liftA2
: (a -> b -> c) -> f a -> f b -> f c

Lift a binary function to actions.

Some functors support an implementation of liftA2 that is more efficient than the default one. In particular, if fmap is an expensive operation, it is likely better to use liftA2 than to fmap over the structure and then use <*>.

(*>)
: f a -> f b -> f b

Sequence actions, discarding the value of the first argument.

(<*)
: f a -> f b -> f a

Sequence actions, discarding the value of the second argument.

instance Applicative ((->) r)

instance Applicative (State s)

instance Applicative Down

instance Applicative Scenario

instance Applicative Update

instance Applicative Optional

instance Applicative Formula

instance Applicative NonEmpty

instance Applicative (Validation err)

instance Applicative (Either e)

instance Applicative ([])

class Applicative m => Action m where

(>>=)
: m a -> (a -> m b) -> m b

Sequentially compose two actions, passing any value produced by the first as an argument to the second.

instance Action ((->) r)

instance Action (State s)

instance Action Down

instance Action Scenario

instance Action Update

instance Action Optional

instance Action Formula

instance Action NonEmpty

instance Action (Either e)

instance Action ([])

class Action m => ActionFail m where

This class exists to desugar pattern matches in do-notation. Polymorphic usage, or calling fail directly, is not recommended. Instead consider using CanAbort.

fail
: Text -> m a

Fail with an error message.

instance ActionFail Scenario

instance ActionFail Update

instance ActionFail Optional

instance ActionFail (Either Text)

instance ActionFail ([])

class Semigroup a where

The class of semigroups (types with an associative binary operation).

(<>)
: a -> a -> a

An associative operation.

instance Ord k => Semigroup (Map k v)

instance Semigroup (TextMap b)

instance Semigroup All

instance Semigroup Any

instance Semigroup (Endo a)

instance Multiplicative a => Semigroup (Product a)

instance Additive a => Semigroup (Sum a)

instance Semigroup (NonEmpty a)

instance Ord a => Semigroup (Max a)

instance Ord a => Semigroup (Min a)

instance Ord k => Semigroup (Set k)

instance Semigroup (Validation err a)

instance Semigroup Ordering

instance Semigroup Text

instance Semigroup [a]

class Semigroup a => Monoid a where

The class of monoids (types with an associative binary operation that has an identity).

mempty
: a

Identity of (<>)

mconcat
: [a] -> a

Fold a list using the monoid. For example using mconcat on a list of strings would concatenate all strings to one lone string.

instance Ord k => Monoid (Map k v)

instance Monoid (TextMap b)

instance Monoid All

instance Monoid Any

instance Monoid (Endo a)

instance Multiplicative a => Monoid (Product a)

instance Additive a => Monoid (Sum a)

instance Ord k => Monoid (Set k)

instance Monoid Ordering

instance Monoid Text

instance Monoid [a]

class HasSignatory t where

Exposes signatory function. Part of the Template constraint.

signatory
: t -> [Party]

The signatories of a contract.

class HasObserver t where

Exposes observer function. Part of the Template constraint.

observer
: t -> [Party]

The observers of a contract.

class HasEnsure t where

Exposes ensure function. Part of the Template constraint.

ensure
: t -> Bool

A predicate that must be true, otherwise contract creation will fail.

class HasAgreement t where

Exposes agreement function. Part of the Template constraint.

agreement
: t -> Text

The agreement text of a contract.

class HasCreate t where

Exposes create function. Part of the Template constraint.

create
: t -> Update (ContractId t)

Create a contract based on a template t.

class HasFetch t where

Exposes fetch function. Part of the Template constraint.

fetch
: ContractId t -> Update t

Fetch the contract data associated with the given contract ID. If the ContractId t supplied is not the contract ID of an active contract, this fails and aborts the entire transaction.

class HasArchive t where

Exposes archive function. Part of the Template constraint.

archive
: ContractId t -> Update ()

Archive the contract with the given contract ID.

class HasTemplateTypeRep t where

Exposes templateTypeRep function in Daml-LF 1.7 or later. Part of the Template constraint.

class HasToAnyTemplate t where

Exposes toAnyTemplate function in Daml-LF 1.7 or later. Part of the Template constraint.

class HasFromAnyTemplate t where

Exposes fromAnyTemplate function in Daml-LF 1.7 or later. Part of the Template constraint.

class HasExercise t c r where

Exposes exercise function. Part of the Choice constraint.

exercise
: ContractId t -> c -> Update r

Exercise a choice on the contract with the given contract ID.

class HasExerciseGuarded t c r where

(1.dev only) Exposes exerciseGuarded function. Only available for interface choices.

exerciseGuarded
: (t -> Bool) -> ContractId t -> c -> Update r

(1.dev only) Exercise a choice on the contract with the given contract ID, only if the predicate returns True.

class HasToAnyChoice t c r where

Exposes toAnyChoice function for Daml-LF 1.7 or later. Part of the Choice constraint.

class HasFromAnyChoice t c r where

Exposes fromAnyChoice function for Daml-LF 1.7 or later. Part of the Choice constraint.

class HasKey t k where

Exposes key function. Part of the TemplateKey constraint.

key
: t -> k

The key of a contract.

class HasLookupByKey t k where

Exposes lookupByKey function. Part of the TemplateKey constraint.

lookupByKey
: k -> Update (Optional (ContractId t))

Look up the contract ID t associated with a given contract key k.

You must pass the t using an explicit type application. For instance, if you want to look up a contract of template Account by its key k, you must call lookupByKey @Account k.

class HasFetchByKey t k where

Exposes fetchByKey function. Part of the TemplateKey constraint.

fetchByKey
: k -> Update (ContractId t, t)

Fetch the contract ID and contract data associated with a given contract key.

You must pass the t using an explicit type application. For instance, if you want to fetch a contract of template Account by its key k, you must call fetchByKey @Account k.

class HasMaintainer t k where

Exposes maintainer function. Part of the TemplateKey constraint.

class HasToAnyContractKey t k where

Exposes toAnyContractKey function in Daml-LF 1.7 or later. Part of the TemplateKey constraint.

class HasFromAnyContractKey t k where

Exposes fromAnyContractKey function in Daml-LF 1.7 or later. Part of the TemplateKey constraint.

class HasExerciseByKey t k c r where

Exposes exerciseByKey function.

class IsParties a where

Accepted ways to specify a list of parties: either a single party, or a list of parties.

toParties
: a -> [Party]

Convert to list of parties.

instance IsParties Party

instance IsParties (Optional Party)

instance IsParties (NonEmpty Party)

instance IsParties (Set Party)

instance IsParties [Party]

class Functor f where

A Functor is a typeclass for things that can be mapped over (using its fmap function. Examples include Optional, [] and Update).

fmap
: (a -> b) -> f a -> f b

fmap takes a function of type a -> b, and turns it into a function of type f a -> f b, where f is the type which is an instance of Functor.

For example, map is an fmap that only works on lists. It takes a function a -> b and a [a], and returns a [b].

(<$)
: a -> f b -> f a

Replace all locations in the input f b with the same value a. The default definition is fmap . const, but you can override this with a more efficient version.

class Eq a where

The Eq class defines equality (==) and inequality (/=). All the basic datatypes exported by the "Prelude" are instances of Eq, and Eq may be derived for any datatype whose constituents are also instances of Eq.

Usually, == is expected to implement an equivalence relationship where two values comparing equal are indistinguishable by "public" functions, with a "public" function being one not allowing to see implementation details. For example, for a type representing non-normalised natural numbers modulo 100, a "public" function doesn’t make the difference between 1 and 201. It is expected to have the following properties:

Reflexivity: x == x = True

Symmetry: x == y = y == x

Transitivity: if x == y && y == z = True, then x == z = True

Substitutivity: if x == y = True and f is a "public" function whose return type is an instance of Eq, then f x == f y = True

Negation: x /= y = not (x == y)

Minimal complete definition: either == or /=.

(==)
: a -> a -> Bool

(/=)
: a -> a -> Bool

instance (Eq a, Eq b) => Eq (Either a b)

instance Eq BigNumeric

instance Eq Bool

instance Eq Int

instance Eq (Numeric n)

instance Eq Ordering

instance Eq RoundingMode

instance Eq Text

instance Eq a => Eq [a]

instance Eq ()

instance (Eq a, Eq b) => Eq (a, b)

instance (Eq a, Eq b, Eq c) => Eq (a, b, c)

instance (Eq a, Eq b, Eq c, Eq d) => Eq (a, b, c, d)

instance (Eq a, Eq b, Eq c, Eq d, Eq e) => Eq (a, b, c, d, e)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f) => Eq (a, b, c, d, e, f)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g) => Eq (a, b, c, d, e, f, g)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h) => Eq (a, b, c, d, e, f, g, h)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i) => Eq (a, b, c, d, e, f, g, h, i)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j) => Eq (a, b, c, d, e, f, g, h, i, j)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k) => Eq (a, b, c, d, e, f, g, h, i, j, k)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k, Eq l) => Eq (a, b, c, d, e, f, g, h, i, j, k, l)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k, Eq l, Eq m) => Eq (a, b, c, d, e, f, g, h, i, j, k, l, m)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k, Eq l, Eq m, Eq n) => Eq (a, b, c, d, e, f, g, h, i, j, k, l, m, n)

instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k, Eq l, Eq m, Eq n, Eq o) => Eq (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)

class Eq a => Ord a where

The Ord class is used for totally ordered datatypes.

Instances of Ord can be derived for any user-defined datatype whose constituent types are in Ord. The declared order of the constructors in the data declaration determines the ordering in derived Ord instances. The Ordering datatype allows a single comparison to determine the precise ordering of two objects.

The Haskell Report defines no laws for Ord. However, <= is customarily expected to implement a non-strict partial order and have the following properties:

Transitivity: if x <= y && y <= z = True, then x <= z = True

Reflexivity: x <= x = True

Antisymmetry: if x <= y && y <= x = True, then x == y = True

Note that the following operator interactions are expected to hold:

x >= y = y <= x

x < y = x <= y && x /= y

x > y = y < x

x < y = compare x y == LT

x > y = compare x y == GT

x == y = compare x y == EQ

min x y == if x <= y then x else y = ‘True’

max x y == if x >= y then x else y = ‘True’

Minimal complete definition: either compare or <=. Using compare can be more efficient for complex types.

compare
: a -> a -> Ordering

(<)
: a -> a -> Bool

(<=)
: a -> a -> Bool

(>)
: a -> a -> Bool

(>=)
: a -> a -> Bool

max
: a -> a -> a

min
: a -> a -> a

instance (Ord a, Ord b) => Ord (Either a b)

instance Ord BigNumeric

instance Ord Bool

instance Ord Int

instance Ord (Numeric n)

instance Ord Ordering

instance Ord RoundingMode

instance Ord Text

instance Ord a => Ord [a]

instance Ord ()

instance (Ord a, Ord b) => Ord (a, b)

instance (Ord a, Ord b, Ord c) => Ord (a, b, c)

instance (Ord a, Ord b, Ord c, Ord d) => Ord (a, b, c, d)

instance (Ord a, Ord b, Ord c, Ord d, Ord e) => Ord (a, b, c, d, e)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f) => Ord (a, b, c, d, e, f)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g) => Ord (a, b, c, d, e, f, g)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h) => Ord (a, b, c, d, e, f, g, h)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i) => Ord (a, b, c, d, e, f, g, h, i)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j) => Ord (a, b, c, d, e, f, g, h, i, j)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k) => Ord (a, b, c, d, e, f, g, h, i, j, k)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k, Ord l) => Ord (a, b, c, d, e, f, g, h, i, j, k, l)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k, Ord l, Ord m) => Ord (a, b, c, d, e, f, g, h, i, j, k, l, m)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k, Ord l, Ord m, Ord n) => Ord (a, b, c, d, e, f, g, h, i, j, k, l, m, n)

instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k, Ord l, Ord m, Ord n, Ord o) => Ord (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)

class NumericScale n where

Is this a valid scale for the Numeric type?

This typeclass is used to prevent the creation of Numeric values with too large a scale. The scale controls the number of digits available after the decimal point, and it must be between 0 and 37 inclusive.

Thus the only available instances of this typeclass are NumericScale 0 through NumericScale 37. This cannot be extended without additional compiler and runtime support. You cannot implement a custom instance of this typeclass.

If you have an error message in your code of the form "No instance for (NumericScale n)", this is probably caused by having a numeric literal whose scale cannot be inferred by the compiler. You can usually fix this by adding a type signature to the definition, or annotating the numeric literal directly (for example, instead of writing 3.14159 you can write (3.14159 : Numeric 5)).

numericScale
: proxy n -> Int

Get the scale of a Numeric as an integer. For example, numericScale (3.14159 : Numeric 5) equals 5.

instance NumericScale 0

instance NumericScale 1

instance NumericScale 10

instance NumericScale 11

instance NumericScale 12

instance NumericScale 13

instance NumericScale 14

instance NumericScale 15

instance NumericScale 16

instance NumericScale 17

instance NumericScale 18

instance NumericScale 19

instance NumericScale 2

instance NumericScale 20

instance NumericScale 21

instance NumericScale 22

instance NumericScale 23

instance NumericScale 24

instance NumericScale 25

instance NumericScale 26

instance NumericScale 27

instance NumericScale 28

instance NumericScale 29

instance NumericScale 3

instance NumericScale 30

instance NumericScale 31

instance NumericScale 32

instance NumericScale 33

instance NumericScale 34

instance NumericScale 35

instance NumericScale 36

instance NumericScale 37

instance NumericScale 4

instance NumericScale 5

instance NumericScale 6

instance NumericScale 7

instance NumericScale 8

instance NumericScale 9

class IsNumeric t where

Types that can be represented by decimal literals in Daml.

fromNumeric
: NumericScale m => Numeric m -> t

Convert from Numeric. Raises an error if the number can’t be represented exactly in the target type.

fromBigNumeric
: BigNumeric -> t

Convert from BigNumeric. Raises an error if the number can’t be represented exactly in the target type.

instance IsNumeric BigNumeric

instance NumericScale n => IsNumeric (Numeric n)

class Bounded a where

Use the Bounded class to name the upper and lower limits of a type.

You can derive an instance of the Bounded class for any enumeration type. minBound is the first constructor listed in the data declaration and maxBound is the last.

You can also derive an instance of Bounded for single-constructor data types whose constituent types are in Bounded.

Ord is not a superclass of Bounded because types that are not totally ordered can still have upper and lower bounds.

minBound
: a

maxBound
: a

instance Bounded Bool

instance Bounded Int

class Enum a where

Use the Enum class to define operations on sequentially ordered types: that is, types that can be enumerated. Enum members have defined successors and predecessors, which you can get with the succ and pred functions.

Types that are an instance of class Bounded as well as Enum should respect the following laws:

Both succ maxBound and pred minBound should result in a runtime error.

fromEnum and toEnum should give a runtime error if the result value is not representable in the result type. For example, toEnum 7 : Bool is an error.

enumFrom and enumFromThen should be defined with an implicit bound, like this:
enumFrom     x   = enumFromTo     x maxBound
enumFromThen x y = enumFromThenTo x y bound
    where
        bound | fromEnum y >= fromEnum x = maxBound
              | otherwise                = minBound
succ
: a -> a

Returns the successor of the given value. For example, for numeric types, succ adds 1.

If the type is also an instance of Bounded, succ maxBound results in a runtime error.

pred
: a -> a

Returns the predecessor of the given value. For example, for numeric types, pred subtracts 1.

If the type is also an instance of Bounded, pred minBound results in a runtime error.

toEnum
: Int -> a

Convert a value from an Int to an Enum value: ie, toEnum i returns the item at the i th position of (the instance of) Enum

fromEnum
: a -> Int

Convert a value from an Enum value to an Int: ie, returns the Int position of the element within the Enum.

If fromEnum is applied to a value that’s too large to fit in an Int, what is returned is up to your implementation.

enumFrom
: a -> [a]

Return a list of the Enum values starting at the Int position. For example:

enumFrom 6 : [Int] = [6,7,8,9,...,maxBound : Int]

enumFromThen
: a -> a -> [a]

Returns a list of the Enum values with the first value at the first Int position, the second value at the second Int position, and further values with the same distance between them.

For example:

enumFromThen 4 6 : [Int] = [4,6,8,10...]

enumFromThen 6 2 : [Int] = [6,2,-2,-6,...,minBound :: Int]

enumFromTo
: a -> a -> [a]

Returns a list of the Enum values with the first value at the first Int position, and the last value at the last Int position.

This is what’s behind the language feature that lets you write [n,m..].

For example:

enumFromTo 6 10 : [Int] = [6,7,8,9,10]

enumFromThenTo
: a -> a -> a -> [a]

Returns a list of the Enum values with the first value at the first Int position, the second value at the second Int position, and further values with the same distance between them, with the final value at the final Int position.

This is what’s behind the language feature that lets you write [n,n'..m].

For example:

enumFromThenTo 4 2 -6 : [Int] = [4,2,0,-2,-4,-6]

enumFromThenTo 6 8 2 : [Int] = []

instance Enum Bool

instance Enum Int

class Additive a where

Use the Additive class for types that can be added. Instances have to respect the following laws:

(+) must be associative, ie: (x + y) + z = x + (y + z)

(+) must be commutative, ie: x + y = y + x

x + aunit = x

negate gives the additive inverse, ie: x + negate x = aunit

(+)
: a -> a -> a

Add the two arguments together.

aunit
: a

The additive identity for the type. For example, for numbers, this is 0.

(-)
: a -> a -> a

Subtract the second argument from the first argument, ie. x - y = x + negate y

negate
: a -> a

Negate the argument: x + negate x = aunit

instance Additive BigNumeric

instance Additive Int

instance Additive (Numeric n)

class Multiplicative a where

Use the Multiplicative class for types that can be multiplied. Instances have to respect the following laws:

(*) is associative, ie:(x * y) * z = x * (y * z)

(*) is commutative, ie: x * y = y * x

x * munit = x

(*)
: a -> a -> a

Multipy the arguments together

munit
: a

The multiplicative identity for the type. For example, for numbers, this is 1.

(^)
: a -> Int -> a

x ^ n raises x to the power of n.

instance Multiplicative BigNumeric

instance Multiplicative Int

instance Multiplicative (Numeric n)

class (Additive a, Multiplicative a) => Number a where

Number is a class for numerical types. As well as the rules for Additive and Multiplicative, instances also have to respect the following law:

(*) is distributive with respect to (+). That is: a * (b + c) = (a * b) + (a * c) and (b + c) * a = (b * a) + (c * a)

instance Number BigNumeric

instance Number Int

instance Number (Numeric n)

class Signed a where

The Signed is for the sign of a number.

signum
: a -> a

Sign of a number. For real numbers, the ‘signum’ is either -1 (negative), 0 (zero) or 1 (positive).

abs
: a -> a

The absolute value: that is, the value without the sign.

instance Signed BigNumeric

instance Signed Int

instance Signed (Numeric n)

class Multiplicative a => Divisible a where

Use the Divisible class for types that can be divided. Instances should respect that division is the inverse of multiplication, i.e. x * y / y is equal to x whenever it is defined.

(/)
: a -> a -> a

x / y divides x by y

instance Divisible Int

instance Divisible (Numeric n)

class Divisible a => Fractional a where

Use the Fractional class for types that can be divided and where the reciprocal is well defined. Instances have to respect the following laws:

When recip x is defined, it must be the inverse of x with respect to multiplication: x * recip x = munit

When recip y is defined, then x / y = x * recip y

recip
: a -> a

Calculates the reciprocal: recip x is 1/x.

instance Fractional (Numeric n)

class Show a where

Use the Show class for values that can be converted to a readable Text value.

Derived instances of Show have the following properties:

The result of show is a syntactically correct expression that only contains constants (given the fixity declarations in force at the point where the type is declared). It only contains the constructor names defined in the data type, parentheses, and spaces. When labelled constructor fields are used, braces, commas, field names, and equal signs are also used.

If the constructor is defined to be an infix operator, then showsPrec produces infix applications of the constructor.

If the precedence of the top-level constructor in x is less than d (associativity is ignored), the representation will be enclosed in parentheses. For example, if d is 0 then the result is never surrounded in parentheses; if d is 11 it is always surrounded in parentheses, unless it is an atomic expression.

If the constructor is defined using record syntax, then show will produce the record-syntax form, with the fields given in the same order as the original declaration.

showsPrec
: Int -> a -> ShowS

Convert a value to a readable Text value. Unlike show, showsPrec should satisfy the rule showsPrec d x r ++ s == showsPrec d x (r ++ s)

show
: a -> Text

Convert a value to a readable Text value.

showList
: [a] -> ShowS

Allows you to show lists of values.

instance (Show a, Show b) => Show (Either a b)

instance Show BigNumeric

instance Show Bool

instance Show Int

instance Show (Numeric n)

instance Show Ordering

instance Show RoundingMode

instance Show Text

instance Show a => Show [a]

instance Show ()

instance (Show a, Show b) => Show (a, b)

instance (Show a, Show b, Show c) => Show (a, b, c)

instance (Show a, Show b, Show c, Show d) => Show (a, b, c, d)

instance (Show a, Show b, Show c, Show d, Show e) => Show (a, b, c, d, e)

Data Types¶

data AnyChoice

Existential choice type that can wrap an arbitrary choice.

AnyChoice

Field Type Description

getAnyChoice Any

getAnyChoiceTemplateTypeRep TemplateTypeRep

instance Eq AnyChoice

instance Ord AnyChoice

data AnyContractKey

Existential contract key type that can wrap an arbitrary contract key.

AnyContractKey

Field Type Description

getAnyContractKey Any

getAnyContractKeyTemplateTypeRep TemplateTypeRep

instance Eq AnyContractKey

instance Ord AnyContractKey

data AnyTemplate

Existential template type that can wrap an arbitrary template.

AnyTemplate

Field Type Description

getAnyTemplate Any

instance Eq AnyTemplate

instance Ord AnyTemplate

data TemplateTypeRep

Unique textual representation of a template Id.

TemplateTypeRep

Field Type Description

getTemplateTypeRep TypeRep

instance Eq TemplateTypeRep

instance Ord TemplateTypeRep

data Down a

The Down type can be used for reversing sorting order. For example, sortOn (\x -> Down x.field) would sort by descending field.

Down a

instance Action Down

instance Applicative Down

instance Functor Down

instance Eq a => Eq (Down a)

instance Ord a => Ord (Down a)

instance Show a => Show (Down a)

type Implements t i

= (HasInterfaceTypeRep i, HasToInterface t i, HasFromInterface t i)

(Daml-LF >= 1.15) Constraint that indicates that a template implements an interface.

data AnyException

A wrapper for all exception types.

instance HasFromAnyException AnyException

instance HasMessage AnyException

instance HasToAnyException AnyException

data ContractId a

The ContractId a type represents an ID for a contract created from a template a. You can use the ID to fetch the contract, among other things.

instance Eq (ContractId a)

instance Ord (ContractId a)

instance Show (ContractId a)

data Date

The Date type represents a date, for example date 2007 Apr 5.

instance Eq Date

instance Ord Date

instance Bounded Date

instance Enum Date

instance Show Date

data Map a b

The Map a b type represents an associative array from keys of type a to values of type b. It uses the built-in equality for keys. Import DA.Map to use it.

instance Ord k => Foldable (Map k)

instance Ord k => Monoid (Map k v)

instance Ord k => Semigroup (Map k v)

instance Ord k => Traversable (Map k)

instance Ord k => Functor (Map k)

instance (Ord k, Eq v) => Eq (Map k v)

instance (Ord k, Ord v) => Ord (Map k v)

instance (Show k, Show v) => Show (Map k v)

data Party

The Party type represents a party to a contract.

instance IsParties Party

instance IsParties (Optional Party)

instance IsParties (NonEmpty Party)

instance IsParties (Set Party)

instance IsParties [Party]

instance Eq Party

instance Ord Party

instance Show Party

data Scenario a

The Scenario type is for simulating ledger interactions. The type Scenario a describes a set of actions taken by various parties during the simulated scenario, before returning a value of type a.

instance CanAssert Scenario

instance ActionThrow Scenario

instance CanAbort Scenario

instance HasSubmit Scenario Update

instance HasTime Scenario

instance Action Scenario

instance ActionFail Scenario

instance Applicative Scenario

instance Functor Scenario

data TextMap a

The TextMap a type represents an associative array from keys of type Text to values of type a.

instance Foldable TextMap

instance Monoid (TextMap b)

instance Semigroup (TextMap b)

instance Traversable TextMap

instance Functor TextMap

instance Eq a => Eq (TextMap a)

instance Ord a => Ord (TextMap a)

instance Show a => Show (TextMap a)

data Time

The Time type represents a specific datetime in UTC, for example time (date 2007 Apr 5) 14 30 05.

instance Eq Time

instance Ord Time

instance Show Time

data Update a

The Update a type represents an Action to update or query the ledger, before returning a value of type a. Examples include create and fetch.

instance CanAssert Update

instance ActionCatch Update

instance ActionThrow Update

instance CanAbort Update

instance HasSubmit Scenario Update

instance HasTime Update

instance Action Update

instance ActionFail Update

instance Applicative Update

instance Functor Update

data Optional a

The Optional type encapsulates an optional value. A value of type Optional a either contains a value of type a (represented as Some a), or it is empty (represented as None). Using Optional is a good way to deal with errors or exceptional cases without resorting to drastic measures such as error.

The Optional type is also an Action. It is a simple kind of error Action, where all errors are represented by None. A richer error Action could be built using the Data.Either.Either type.

None

Some a

instance Foldable Optional

instance Action Optional

instance ActionFail Optional

instance Applicative Optional

instance IsParties (Optional Party)

instance Traversable Optional

instance Functor Optional

instance Eq a => Eq (Optional a)

instance Ord a => Ord (Optional a)

instance Show a => Show (Optional a)

data Archive

The data type corresponding to the implicit Archive choice in every template.

Archive

(no fields)

instance Eq Archive

instance Show Archive

type Choice t c r

= (Template t, HasExercise t c r, HasToAnyChoice t c r, HasFromAnyChoice t c r)

Constraint satisfied by choices.

type Template t: = (HasTemplateTypeRep t, HasToAnyTemplate t, HasFromAnyTemplate t)

type TemplateKey t k

= (Template t, HasKey t k, HasLookupByKey t k, HasFetchByKey t k, HasMaintainer t k, HasToAnyContractKey t k, HasFromAnyContractKey t k)

Constraint satisfied by template keys.

data Either a b

The Either type represents values with two possibilities: a value of type Either a b is either Left a or Right b.

The Either type is sometimes used to represent a value which is either correct or an error; by convention, the Left constructor is used to hold an error value and the Right constructor is used to hold a correct value (mnemonic: "right" also means "correct").

Left a

Right b

instance (Eq a, Eq b) => Eq (Either a b)

instance (Ord a, Ord b) => Ord (Either a b)

instance (Show a, Show b) => Show (Either a b)

type ShowS

= Text -> Text

showS should represent some text, and applying it to some argument should prepend the argument to the represented text.

data BigNumeric

A big numeric type, capable of holding large decimal values with many digits.

BigNumeric represents any positive or negative decimal number with up to 2^15 digits before the decimal point, and up to 2^15 digits after the decimal point.

BigNumeric is not serializable, it is only intended for intermediate computation. You must round and convert BigNumeric to a fixed-width numeric (Numeric n) in order to store it in a template. The rounding operations are round and div from the DA.BigNumeric module. The casting operations are fromNumeric and fromBigNumeric from the IsNumeric typeclass.

instance Eq BigNumeric

instance IsNumeric BigNumeric

instance Ord BigNumeric

instance Additive BigNumeric

instance Multiplicative BigNumeric

instance Number BigNumeric

instance Signed BigNumeric

instance Show BigNumeric

data Bool

A type for Boolean values, ie True and False.

False

True

instance Eq Bool

instance Ord Bool

instance Bounded Bool

instance Enum Bool

instance Show Bool

type Decimal: = Numeric 10

data Int

A type representing a 64-bit integer.

instance Eq Int

instance Ord Int

instance Bounded Int

instance Enum Int

instance Additive Int

instance Divisible Int

instance Multiplicative Int

instance Number Int

instance Signed Int

instance Show Int

data Nat

(Kind) This is the kind of type-level naturals.

data Numeric n

A type for fixed-point decimal numbers, with the scale being passed as part of the type.

Numeric n represents a fixed-point decimal number with a fixed precision of 38 (i.e. 38 digits not including a leading zero) and a scale of n, i.e., n digits after the decimal point.

n must be between 0 and 37 (bounds inclusive).

Examples:
0.01 : Numeric 2
0.0001 : Numeric 4
instance Eq (Numeric n)

instance NumericScale n => IsNumeric (Numeric n)

instance Ord (Numeric n)

instance Additive (Numeric n)

instance Divisible (Numeric n)

instance Fractional (Numeric n)

instance Multiplicative (Numeric n)

instance Number (Numeric n)

instance Signed (Numeric n)

instance Show (Numeric n)

data Ordering

A type for giving information about ordering: being less than (LT), equal to (EQ), or greater than (GT) something.

LT

EQ

GT

instance Eq Ordering

instance Ord Ordering

instance Show Ordering

data RoundingMode

Rounding modes for BigNumeric operations like div and round from DA.BigNumeric.

RoundingUp

Round away from zero.

RoundingDown

Round towards zero.

RoundingCeiling

Round towards positive infinity.

RoundingFloor

Round towards negative infinity.

RoundingHalfUp

Round towards the nearest neighbor unless both neighbors are equidistant, in which case round away from zero.

RoundingHalfDown

Round towards the nearest neighbor unless both neighbors are equidistant, in which case round towards zero.

RoundingHalfEven

Round towards the nearest neighbor unless both neighbors are equidistant, in which case round towards the even neighbor.

RoundingUnnecessary

Do not round. Raises an error if the result cannot be represented without rounding at the targeted scale.

instance Eq RoundingMode

instance Ord RoundingMode

instance Show RoundingMode

data Text

A type for text strings, that can represent any unicode code point. For example "Hello, world".

instance Eq Text

instance Ord Text

instance Show Text

data [] a

A type for lists, for example [1,2,3].

([])

(:) _ _

Functions¶

assert

: CanAssert m => Bool -> m ()

Check whether a condition is true. If it’s not, abort the transaction.

assertMsg

: CanAssert m => Text -> Bool -> m ()

Check whether a condition is true. If it’s not, abort the transaction with a message.

assertAfter

: (CanAssert m, HasTime m) => Time -> m ()

Check whether the given time is in the future. If it’s not, abort the transaction.

assertBefore

: (CanAssert m, HasTime m) => Time -> m ()

Check whether the given time is in the past. If it’s not, abort the transaction.

daysSinceEpochToDate

: Int -> Date

Convert from number of days since epoch (i.e. the number of days since January 1, 1970) to a date.

dateToDaysSinceEpoch

: Date -> Int

Convert from a date to number of days from epoch (i.e. the number of days since January 1, 1970).

interfaceTypeRep

: HasInterfaceTypeRep i => i -> TemplateTypeRep

(Daml-LF >= 1.15) Obtain the TemplateTypeRep for the template given in the interface value.

toInterface

: HasToInterface t i => t -> i

(Daml-LF >= 1.15) Convert a template value into an interface value. For example toInterface @MyInterface value converts a template value into a MyInterface type.

toInterfaceContractId

: HasToInterface t i => ContractId t -> ContractId i

(Daml-LF >= 1.15) Convert a template contract id into an interface contract id. For example, toInterfaceContractId @MyInterface cid.

fromInterfaceContractId

: HasFromInterface t i => ContractId i -> ContractId t

(Daml-LF >= 1.15) Convert an interface contract id into a template contract id. For example, fromInterfaceContractId @MyTemplate cid.

Can also be used to convert an interface contract id into a contract id of one of its requiring interfaces.

This function does not verify that the interface contract id actually points to a template of the given type. This means that a subsequent fetch, exercise, or archive may fail, if, for example, the contract id points to a contract that implements the interface but is of a different template type than expected.

Therefore, you should only use fromInterfaceContractId in situations where you already know that the contract id points to a contract of the right template type. You can also use it in situations where you will fetch, exercise, or archive the contract right away, when a transaction failure is the appropriate response to the contract having the wrong template type.

In all other cases, consider using fetchFromInterface instead.

coerceInterfaceContractId

: (HasInterfaceTypeRep i, HasInterfaceTypeRep j) => ContractId i -> ContractId j

(Daml-LF >= 1.15) Convert an interface contract id into a contract id of a different interface. For example, given two interfaces Source and Target, and cid : ContractId Source, coerceInterfaceContractId @Target @Source cid : ContractId Target.

This function does not verify that the contract id actually points to a contract that implements either interface. This means that a subsequent fetch, exercise, or archive may fail, if, for example, the contract id points to a contract of template A but it was coerced into a ContractId B where B is an interface and there’s no interface instance B for A.

Therefore, you should only use coerceInterfaceContractId in situations where you already know that the contract id points to a contract of the right type. You can also use it in situations where you will fetch, exercise, or archive the contract right away, when a transaction failure is the appropriate response to the contract having the wrong type.

fetchFromInterface

: (HasFromInterface t i, HasFetch i) => ContractId i -> Update (Optional (ContractId t, t))

(Daml-LF >= 1.15) Fetch an interface and convert it to a specific template type. If conversion is succesful, this function returns the converted contract and its converted contract id. Otherwise, this function returns None.

Can also be used to fetch and convert an interface contract id into a contract and contract id of one of its requiring interfaces.

Example:

do
  fetchResult <- fetchFromInterface @MyTemplate ifaceCid
  case fetchResult of
    None -> abort "Failed to convert interface to appropriate template type"
    Some (tplCid, tpl) -> do
       ... do something with tpl and tplCid ...

_exerciseInterfaceGuard: : a -> b -> c -> Bool

view: : HasInterfaceView i v => i -> v

partyToText

: Party -> Text

Convert the Party to Text, giving back what you passed to getParty. In most cases, you should use show instead. show wraps the party in 'ticks' making it clear it was a Party originally.

partyFromText

: Text -> Optional Party

Converts a Text to Party. It returns None if the provided text contains any forbidden characters. See Daml-LF spec for a specification on which characters are allowed in parties. Note that this function accepts text without single quotes.

This function does not check on whether the provided text corresponds to a party that "exists" on a given ledger: it merely converts the given Text to a Party. The only way to guarantee that a given Party exists on a given ledger is to involve it in a contract.

This function, together with partyToText, forms an isomorphism between valid party strings and parties. In other words, the following equations hold:

∀ p. partyFromText (partyToText p) = Some p
∀ txt p. partyFromText txt = Some p ==> partyToText p = txt

This function will crash at runtime if you compile Daml to Daml-LF < 1.2.

getParty

: Text -> Scenario Party

Get the party with the given name. Party names must be non-empty and only contain alphanumeric charaters, space, - (dash) or _ (underscore).

scenario

: Scenario a -> Scenario a

Declare you are building a scenario.

curry

: ((a, b) -> c) -> a -> b -> c

Turn a function that takes a pair into a function that takes two arguments.

uncurry

: (a -> b -> c) -> (a, b) -> c

Turn a function that takes two arguments into a function that takes a pair.

(>>)

: Action m => m a -> m b -> m b

Sequentially compose two actions, discarding any value produced by the first. This is like sequencing operators (such as the semicolon) in imperative languages.

ap

: Applicative f => f (a -> b) -> f a -> f b

Synonym for <*>.

return

: Applicative m => a -> m a

Inject a value into the monadic type. For example, for Update and a value of type a, return would give you an Update a.

join

: Action m => m (m a) -> m a

Collapses nested actions into a single action.

identity

: a -> a

The identity function.

guard: : ActionFail m => Bool -> m ()

foldl

: (b -> a -> b) -> b -> [a] -> b

This function is a left fold, which you can use to inspect/analyse/consume lists. foldl f i xs performs a left fold over the list xs using the function f, using the starting value i.

Examples:

>>> foldl (+) 0 [1,2,3]
6

>>> foldl (^) 10 [2,3]
1000000

Note that foldl works from left-to-right over the list arguments.

find

: (a -> Bool) -> [a] -> Optional a

find p xs finds the first element of the list xs where the predicate p is true. There might not be such an element, which is why this function returns an Optional a.

length

: [a] -> Int

Gives the length of the list.

any

: (a -> Bool) -> [a] -> Bool

Are there any elements in the list where the predicate is true? any p xs is True if p holds for at least one element of xs.

all

: (a -> Bool) -> [a] -> Bool

Is the predicate true for all of the elements in the list? all p xs is True if p holds for every element of xs.

or

: [Bool] -> Bool

Is at least one of elements in a list of Bool true? or bs is True if at least one element of bs is True.

and

: [Bool] -> Bool

Is every element in a list of Bool true? and bs is True if every element of bs is True.

elem

: Eq a => a -> [a] -> Bool

Does this value exist in this list? elem x xs is True if x is an element of the list xs.

notElem

: Eq a => a -> [a] -> Bool

Negation of elem: elem x xs is True if x is not an element of the list xs.

(<$>)

: Functor f => (a -> b) -> f a -> f b

Synonym for fmap.

optional

: b -> (a -> b) -> Optional a -> b

The optional function takes a default value, a function, and a Optional value. If the Optional value is None, the function returns the default value. Otherwise, it applies the function to the value inside the Some and returns the result.

Basic usage examples:

>>> optional False (> 2) (Some 3)
True

>>> optional False (> 2) None
False

>>> optional 0 (*2) (Some 5)
10
>>> optional 0 (*2) None
0

This example applies show to a Optional Int. If you have Some n, this shows the underlying Int, n. But if you have None, this returns the empty string instead of (for example) None:

>>> optional "" show (Some 5)
"5"
>>> optional "" show (None : Optional Int)
""

either

: (a -> c) -> (b -> c) -> Either a b -> c

The either function provides case analysis for the Either type. If the value is Left a, it applies the first function to a; if it is Right b, it applies the second function to b.

Examples:

This example has two values of type Either [Int] Int, one using the Left constructor and another using the Right constructor. Then it applies either the length function (if it has a [Int]) or the "times-two" function (if it has an Int):

>>> let s = Left [1,2,3] : Either [Int] Int in either length (*2) s
3
>>> let n = Right 3 : Either [Int] Int in either length (*2) n
6

concat

: [[a]] -> [a]

Take a list of lists and concatenate those lists into one list.

(++)

: [a] -> [a] -> [a]

Concatenate two lists.

flip

: (a -> b -> c) -> b -> a -> c

Flip the order of the arguments of a two argument function.

reverse

: [a] -> [a]

Reverse a list.

mapA

: Applicative m => (a -> m b) -> [a] -> m [b]

Apply an applicative function to each element of a list.

forA

: Applicative m => [a] -> (a -> m b) -> m [b]

forA is mapA with its arguments flipped.

sequence

: Applicative m => [m a] -> m [a]

Perform a list of actions in sequence and collect the results.

(=<<)

: Action m => (a -> m b) -> m a -> m b

=<< is >>= with its arguments flipped.

concatMap

: (a -> [b]) -> [a] -> [b]

Map a function over each element of a list, and concatenate all the results.

replicate

: Int -> a -> [a]

replicate i x gives the list [x, x, x, ..., x] with i copies of x.

take

: Int -> [a] -> [a]

Take the first n elements of a list.

drop

: Int -> [a] -> [a]

Drop the first n elements of a list.

splitAt

: Int -> [a] -> ([a], [a])

Split a list at a given index.

takeWhile

: (a -> Bool) -> [a] -> [a]

Take elements from a list while the predicate holds.

dropWhile

: (a -> Bool) -> [a] -> [a]

Drop elements from a list while the predicate holds.

span

: (a -> Bool) -> [a] -> ([a], [a])

span p xs is equivalent to (takeWhile p xs, dropWhile p xs).

partition

: (a -> Bool) -> [a] -> ([a], [a])

The partition function takes a predicate, a list and returns the pair of lists of elements which do and do not satisfy the predicate, respectively; i.e.,

> partition p xs == (filter p xs, filter (not . p) xs)

>>> partition (<0) [1, -2, -3, 4, -5, 6]
([-2, -3, -5], [1, 4, 6])

break

: (a -> Bool) -> [a] -> ([a], [a])

Break a list into two, just before the first element where the predicate holds. break p xs is equivalent to span (not . p) xs.

lookup

: Eq a => a -> [(a, b)] -> Optional b

Look up the first element with a matching key.

enumerate

: (Enum a, Bounded a) => [a]

Generate a list containing all values of a given enumeration.

zip

: [a] -> [b] -> [(a, b)]

zip takes two lists and returns a list of corresponding pairs. If one list is shorter, the excess elements of the longer list are discarded.

zip3

: [a] -> [b] -> [c] -> [(a, b, c)]

zip3 takes three lists and returns a list of triples, analogous to zip.

zipWith

: (a -> b -> c) -> [a] -> [b] -> [c]

zipWith takes a function and two lists. It generalises zip by combining elements using the function, instead of forming pairs. If one list is shorter, the excess elements of the longer list are discarded.

zipWith3

: (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d]

zipWith3 generalises zip3 by combining elements using the function, instead of forming triples.

unzip

: [(a, b)] -> ([a], [b])

Turn a list of pairs into a pair of lists.

unzip3

: [(a, b, c)] -> ([a], [b], [c])

Turn a list of triples into a triple of lists.

traceRaw

: Text -> a -> a

traceRaw msg a prints msg and returns a, for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

trace

: Show b => b -> a -> a

trace b a prints b and returns a, for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

traceId

: Show b => b -> b

traceId a prints a and returns a, for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

debug

: (Show b, Action m) => b -> m ()

debug x prints x for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

debugRaw

: Action m => Text -> m ()

debugRaw msg prints msg for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

fst

: (a, b) -> a

Return the first element of a tuple.

snd

: (a, b) -> b

Return the second element of a tuple.

truncate

: Numeric n -> Int

truncate x rounds x toward zero.

intToNumeric

: Int -> Numeric n

Convert an Int to a Numeric.

intToDecimal

: Int -> Decimal

Convert an Int to a Decimal.

roundBankers

: Int -> Numeric n -> Numeric n

Bankers’ Rounding: roundBankers dp x rounds x to dp decimal places, where a .5 is rounded to the nearest even digit.

roundCommercial

: NumericScale n => Int -> Numeric n -> Numeric n

Commercial Rounding: roundCommercial dp x rounds x to dp decimal places, where a .5 is rounded away from zero.

round

: Numeric n -> Int

Round a Decimal to the nearest integer, where a .5 is rounded away from zero.

floor

: Numeric n -> Int

Round a Decimal down to the nearest integer.

ceiling

: Numeric n -> Int

Round a Decimal up to the nearest integer.

null

: [a] -> Bool

Is the list empty? null xs is true if xs is the empty list.

filter

: (a -> Bool) -> [a] -> [a]

Filters the list using the function: keep only the elements where the predicate holds.

sum

: Additive a => [a] -> a

Add together all the elements in the list.

product

: Multiplicative a => [a] -> a

Multiply all the elements in the list together.

undefined

: a

A convenience function that can be used to mark something not implemented. Always throws an error with "Not implemented."

stakeholder

: (HasSignatory t, HasObserver t) => t -> [Party]

The stakeholders of a contract: its signatories and observers.

maintainer

: HasMaintainer t k => k -> [Party]

The list of maintainers of a contract key.

exerciseByKey

: HasExerciseByKey t k c r => k -> c -> Update r

Exercise a choice on the contract associated with the given key.

You must pass the t using an explicit type application. For instance, if you want to exercise a choice Withdraw on a contract of template Account given by its key k, you must call exerciseByKey @Account k Withdraw.

createAndExercise

: (HasCreate t, HasExercise t c r) => t -> c -> Update r

Create a contract and exercise the choice on the newly created contract.

templateTypeRep

: HasTemplateTypeRep t => TemplateTypeRep

Generate a unique textual representation of the template id.

toAnyTemplate

: HasToAnyTemplate t => t -> AnyTemplate

Wrap the template in AnyTemplate.