CTF

CIHex.pmDocs

BEAM compact term format encoder/decoder.

The compact term format is used in the Code chunk of BEAM files to efficiently encode instruction arguments. This library provides functions to decode these bytes into Elixir terms and encode terms back to bytes.

When to use this library

Use CTF when you need to:

Installation

Add ctf to your list of dependencies in mix.exs:

def deps do
  [
    {:ctf, "~> 0.1.0"}
  ]
end

Usage

Decoding

Decode a single compact term from binary:

# Decode returns {term, remaining_binary}
{{:x, 0}, <<>>} = CTF.decode(<<0x03>>)
{{:x, 5}, rest} = CTF.decode(<<0x53, 0xFF>>)

# Decode all terms from a binary
[{:x, 0}, {:y, 0}, {:f, 0}] = CTF.decode_all(<<0x03, 0x04, 0x05>>)

Encoding

Encode an Elixir term to compact binary format:

<<0x03>> = CTF.encode({:x, 0})
<<0x53>> = CTF.encode({:x, 5})
<<0x0B, 0x64>> = CTF.encode({:x, 100})

Supported term types

Term Description Example
{:x, N} X register {:x, 5}
{:y, N} Y register (stack) {:y, 0}
{:f, N} Label (jump target) {:f, 42}
{:atom, N} Atom table index {:atom, 1}
{:literal, N} Literal table index {:literal, 3}
{:integer, N} Integer value {:integer, -42}
{:char, N} Unicode codepoint {:char, 65}
{:float, F} Float literal {:float, 3.14}
{:fr, N} Float register {:fr, 0}
{:tr, reg, type} Typed register {:tr, {:x, 0}, 5}
{:list, [...]} Argument list {:list, [{:atom, 1}]}
{:alloc, [...]} Allocation list {:alloc, [{{:integer, 0}, {:integer, 5}}]}

References