SMR.Core.Codec

Utilities for working with binary encoded Shimmer trees.

The grammar for the binary format is as follows:

File    ::= '53' '4d' '52' '31' Seq[Decl]       (Shimmer File: "SMR1" in ASCII, then Decls)

Decl    ::= (dmac)    'd0' Name Exp             (Macro declaration)
         |  (dset)    'd1' Name Exp             (Set declaration)

Var     ::= (var)     '8N' Word8^N              (Short Varible,       N <= 15)

Abs     ::= (abs)     '9N' Exp^N                (Short Abstraction,   N <= 15)

App     ::= (app)     'aN' Exp^N                (Packed Application,  N <= 15)

Exp     ::= (ref)     'b0' Ref                  (External reference)
         |  (key)     'b1' Key Exp              (Keyword  application)
         |  (app)     'b2' Exp Seq[Exp]         (Function application)
         |  (var)     'b3' Name Bump            (Variable with bump counter)
         |  (abs)     'b4' Seq[Param] Exp       (Function abstraction)
         |  (sub)     'b5' Seq[Car] Exp         (Substitution train)
         |            Var                       (Short circuit to Var)
         |            Abs                       (Short circuit to Abs)
         |            App                       (Short circuit to App)
         |            Ref                       (Short circuit to Ref)

Key     ::= (box)     'b6'                      (Box keyword)
         |  (run)     'b7'                      (Run keyword)

Param   ::= (pval)    'b8' Name                 (call-by-value parameter)
         |  (pnam)    'b9' Name                 (call-by-name  parameter)

Car     ::= (csim)    'ba' Seq[SnvBind]         (Simultaneous substitution)
         |  (crec)    'bb' Seq[SnvBind]         (Recursive substitution)
         |  (cups)    'bc' Seq[UpsBump]         (Lifting specifiers)

SnvBind ::= (svar)    'bd' Name Bump Exp        (Substitute for variable)
         |  (snom)    'be' Nom Exp              (Substitute for nominal reference)

UpsBump ::= (ups)     'bf' Name Bump Bump       (Lifting specifier)

Ref     ::= (sym)     'c0' Seq[Word8]           (Symbol reference)
         |  (prm)     'c1' Seq[Word8]           (Primitive reference)
         |  (txt)     'c2' Seq[Word8]           (Text reference)
         |  (mac)     'c3' Seq[Word8]           (Macro reference)
         |  (set)     'c4' Seq[Word8]           (Set reference)
         |  (nom)     'c5' Nom                  (Nominal reference)
         |            Name                      (Short circuit to Sym Name)

Prim    ::= (unit)    'e0'                      (Unit value)
         |  (list)    'e1'                      (List constructor tag)
         |  (true)    'e2'                      (True value)
         |  (false)   'e3'                      (False value)

         |  (word8)   'e4' Word8                ( 8-bit word value)
         |  (word16)  'e5' Word16               (16-bit word value)
         |  (word32)  'e6' Word32               (32-bit word value)
         |  (word64)  'e7' Word64               (64-bit word value)

         |  (int8)    'e8' Int8                 ( 8-bit  int value)
         |  (int16)   'e9' Int16                (16-bit  int value)
         |  (int32)   'ea' Int32                (32-bit  int value)
         |  (int64)   'eb' Int64                (64-bit  int value)

         |  (float32) 'ec' Float32              (32-bit float value)
         |  (float64) 'ed' Float64              (64-bit float value)

         |  (named)   'ee' Name                 (Named primitive)
         |  (words)   'ef' Name Seq[Word8]      (Packed raw words with type name)

Seq[A]  ::= (seqN)    'fN' A*                   (N-count then sequence of A things, N <= 13)
         |  (seq8)    'fd' Word8  A*            ( 8-bit count then sequence of A things)
         |  (seq16)   'fe' Word16 A*            (16-bit count then sequence of A things)
         |  (seq32)   'ff' Word32 A*            (32-bit count then sequence of A things)

Name    ::= Seq[Word8]                          (Name)

Bump    ::= Word16                              (Bump counter)

Nom     ::= Word32                              (Nominal constant)

Pack

packFileDecls :: [Decl Text Prim] -> ByteString

Pack a list of Decl into a ByteString, including the file header.

packDecl :: Decl Text Prim -> ByteString

Pack a Decl into a ByteString.

packExp :: Exp Text Prim -> ByteString

Pack an Exp into a ByteString.

packRef :: Ref Text Prim -> ByteString

Pack a Ref into a ByteString.

Unpack

unpackFileDecls :: ByteString -> [Decl Text Prim]

Unpack a list of Decl into a ByteString, including the file header.

If the packed data is malformed then error.

unpackDecl :: ByteString -> Decl Text Prim

Unpack a Decl from a ByteString.

If the packed data is malformed then error.

unpackExp :: ByteString -> Exp Text Prim

Unpack an Exp into a ByteString.

If the packed data is malformed then error.

unpackRef :: ByteString -> Ref Text Prim

Unpack a Ref from a ByteString.

If the packed data is malformed then error.

Raw Size

sizeOfFileDecls :: [Decl Text Prim] -> Int

Compute the serialized size of a shimmer file containing the given decls.

sizeOfDecl :: Decl Text Prim -> Int

Compute the serialized size of a given declaration.

sizeOfExp :: Exp Text Prim -> Int

Compute the serialized size of the given expression.

sizeOfRef :: Ref Text Prim -> Int

Compute the serialized size of the given reference.

Raw Poke

type Poke a = a -> Ptr Word8 -> IO (Ptr Word8)

Type of a function that pokes an a thing into memory.

It takes a pointer to the next byte to use, and returns an updated pointer.

pokeFileDecls :: Poke [Decl Text Prim]

Poke a list of Decl into memory, including the SMR file header.

pokeDecl :: Poke (Decl Text Prim)

Poke a Decl into memory.

pokeExp :: Poke (Exp Text Prim)

Poke an Exp into memory.

pokeRef :: Poke (Ref Text Prim)

Poke a Ref into memory.

Raw Peek

type Peek a = Ptr Word8 -> Int -> IO (a, Ptr Word8, Int)

Type of a function that peeks an a thing from memory.

It takes the current pointer and count of remaining bytes in the buffer, returns new pointer and remaining bytes.

peekFileDecls :: Peek [Decl Text Prim]

Peek a list of Decl from memory, including the SMR file header.

If the packed data is malformed then error.

peekDecl :: Peek (Decl Text Prim)

Peek a Decl from memory.

If the packed data is malformed then error.

peekExp :: Peek (Exp Text Prim)

Peek an Exp from memory.

If the packed data is malformed then error.

peekRef :: Peek (Ref Text Prim)

Peek a Ref from memory.

If the packed data is malformed then error.