View Source VelocyPack (VelocyPack v0.2.0)
An Elixir parser and generator for VelocyPack v1.
The implementation is heavily inspired by Jason and borrows some code (specifically the Codegen module).
Examples
iex> {:ok, vpack} = VelocyPack.encode(10.2312514)
{:ok, <<27, 245, 78, 96, 149, 102, 118, 36, 64>>}
iex> VelocyPack.decode(vpack)
{:ok, 10.2312514}
iex> vpack = VelocyPack.encode!(%{a: "a", b: %{bool: true, float: 10.2312514}})
<<11, 37, 2, 65, 97, 65, 97, 65, 98, 11, 26, 2, 68, 98, 111, 111, 108, 26, 69, 102, 108, 111, 97, 116, 27, 245, 78, 96, 149, 102, 118, 36, 64, 3, 9, 3, 7>>
iex> VelocyPack.decode!(vpack)
%{"a" => "a", "b" => %{"bool" => true, "float" => 10.2312514}}
iex> VelocyPack.decode(<<11>>)
{:error, %VelocyPack.Error{message: "unexpected sequence", dump: nil}}
iex> VelocyPack.decode!(<<11>>)
** (VelocyPack.Error) unexpected sequence
iex> VelocyPack.decode(<<11, 823891328731>>)
{:error, %VelocyPack.Error{message: "unexpected byte", dump: "<<0xDB>>"}}
iex> VelocyPack.decode!(<<11, 823891328731>>)
** (VelocyPack.Error) unexpected byte: <<0xDB>>Errors
decode/2 and encode/2 return {:error, reason} for malformed input
instead of raising. Some of decode/2's reasons are plain terms naming where
parsing stopped, rather than VelocyPack.Error exceptions:
iex> VelocyPack.decode(<<>>)
{:error, :unexpected_end}
iex> VelocyPack.decode(<<0x15>>)
{:error, {:unsupported_type, 21}}decode!/2 raises all of them as VelocyPack.Error. encode/2's reasons are
always exceptions, but of two types - Protocol.UndefinedError for a term with
no VelocyPack.Encoder implementation, and VelocyPack.Error for an
out-of-range integer or an invalid key. See the docs for VelocyPack.decode/2
and VelocyPack.encode/2 for the complete set.
Summary
Functions
Parses the the first VelocyPack value from a binary or iodata.
Parses the the first VelocyPack value from a binary or iodata.
Generates a VelocyPack value as a binary corresponding to term.
Generates a VelocyPack value as a binary corresponding to term.
Types
Functions
Parses the the first VelocyPack value from a binary or iodata.
The options parameter is reserved for future use and not used at the moment.
Errors
Malformed input returns {:error, reason}; it never raises. reason is
either a plain term naming where parsing stopped, or a VelocyPack.Error
exception:
:unexpected_end- the input ended where a value was expected{:unsupported_type, byte}- a reserved or unsupported type byte{:invalid_date, milliseconds}- a0x1cdate outside the rangeDateTimerepresents:invalid_length- a compact array or object length/count encoding exceeds the eight bytes VelocyPack v1 permits%VelocyPack.Error{}- any other malformation, such as a truncated value or an inconsistent length
Those are the complete set. Use decode!/2 if you would rather have every
one of them raised as a VelocyPack.Error.
Parses the the first VelocyPack value from a binary or iodata.
Same as decode/2 except it will unwrap the tuple and raise
in case of errors.
Every failure listed under decode/2 raises VelocyPack.Error here - the
plain-term reasons are wrapped, so a single rescue clause catches them all.
Generates a VelocyPack value as a binary corresponding to term.
The generation is controlled by the Velocy.Encoder protocol,
please refer to the module to read more on how to define the protocol
for custom data types.
The options parameter is reserved for future use and not used at the moment.
Errors
A term the encoder cannot represent returns {:error, reason}; it never
raises. reason is one of two exceptions:
%Protocol.UndefinedError{}- the term has noVelocyPack.Encoderimplementation, such as a struct without one or a PID%VelocyPack.Error{}- an integer outside the 64-bit range, or a map key that is neither an atom nor a string
Both are exceptions, so Exception.message/1 renders either. encode!/2
raises the one that occurred, so code rescuing a specific exception type
has to expect both.
Generates a VelocyPack value as a binary corresponding to term.
Same as encode/2 except it will unwrap the tuple and raise
in case of errors.