haskledger
LicenseApache-2.0
Stabilityprovisional
Safe HaskellNone
LanguageHaskell2010

HaskLedger.Internal

Description

Internal helpers for destructuring Plutus Data values. This module is not exported to end users - it provides shared building blocks used by HaskLedger.Combinators to implement the public API.

Plutus Data encoding

On-chain Cardano values are encoded as Data, a sum type with five constructors:

data Data
  = Constr Integer [Data]   -- tagged product (constructor index + fields)
  | Map [(Data, Data)]      -- association list
  | List [Data]             -- homogeneous list
  | I Integer               -- integer
  | B ByteString            -- byte string

The Constr case is most common for ledger types: ScriptContext, TxInfo, Interval, LowerBound, Extended, etc. are all encoded as Constr tag fields.

Builtin operations

All functions here map directly to Plutus builtins:

UnConstrData
Deconstructs Constr tag fields into a Pair Integer [Data].
FstPair
Extracts the first element of a Pair.
SndPair
Extracts the second element of a Pair.
HeadList
Extracts the first element of a list.
TailList
Returns all but the first element of a list.

Hash-consing

Covenant's ASG automatically deduplicates shared subexpressions via hash-consing. If multiple combinators call unconstrFields on the same node, the underlying UnConstrData and SndPair are computed only once in the generated UPLC.

Synopsis

Constructor destructuring

unconstrData :: Ref -> ASGBuilder Id #

Apply UnConstrData to a Data value, yielding a Pair Integer [Data] - the constructor tag and its fields.

This is the fundamental operation for destructuring any constructor-encoded ledger type (ScriptContext, TxInfo, Interval, etc.).

Compiled output

UnConstrData x

unconstrTag :: Ref -> ASGBuilder Ref #

Extract the constructor tag (an Integer) from a Data value.

Composes FstPair and UnConstrData. Useful for branching on which constructor variant a Data value represents (e.g. Extended has tags 0 = NegInf, 1 = Finite, 2 = PosInf).

Compiled output

FstPair (UnConstrData x)

unconstrFields :: Ref -> ASGBuilder Ref #

Extract the constructor fields (a [Data] list) from a Data value, discarding the constructor tag.

This is the most commonly used destructuring operation. After obtaining the field list, use nthField to access specific fields by index.

Compiled output

SndPair (UnConstrData x)

Pair access

fstPair :: Ref -> ASGBuilder Id #

Extract the first element of a Pair using FstPair.

Compiled output

FstPair x

sndPair :: Ref -> ASGBuilder Id #

Extract the second element of a Pair using SndPair.

Compiled output

SndPair x

List access

headList :: Ref -> ASGBuilder Id #

Extract the first element of a list using HeadList.

Crashes at UPLC runtime if the list is empty. Callers must ensure the list has at least one element.

Compiled output

HeadList x

tailList :: Ref -> ASGBuilder Id #

Return all but the first element of a list using TailList.

Crashes at UPLC runtime if the list is empty. Callers must ensure the list has at least one element.

Compiled output

TailList x

Indexed field extraction

nthField :: Int -> Ref -> ASGBuilder Ref #

Extract the nth field (zero-indexed) from a list of Data values.

nthField 0 is equivalent to HeadList. For n > 0, applies TailList n times followed by HeadList.

Compiled output

nthField 0 xs  =  HeadList xs
nthField 1 xs  =  HeadList (TailList xs)
nthField 2 xs  =  HeadList (TailList (TailList xs))
...

Crashes at UPLC runtime if the list has fewer than n + 1 elements.