zf

extension.ex (4440B)

---

 defmodule Postgrex.Extension do
   @moduledoc """
   An extension knows how to encode and decode PostgreSQL types to and
   from Elixir values.
 
   Custom extensions can be enabled via `Postgrex.Types.define/3`.
   `Postgrex.Types.define/3` must be called on its own file, outside of
   any module and function, as it only needs to be defined once during
   compilation.
 
   For example to support label trees using the text encoding format:
 
       defmodule MyApp.LTree do
         @behaviour Postgrex.Extension
 
         # It can be memory efficient to copy the decoded binary because a
         # reference counted binary that points to a larger binary will be passed
         # to the decode/4 callback. Copying the binary can allow the larger
         # binary to be garbage collected sooner if the copy is going to be kept
         # for a longer period of time. See `:binary.copy/1` for more
         # information.
         def init(opts) do
           Keyword.get(opts, :decode_copy, :copy)
         end
 
         # Use this extension when `type` from %Postgrex.TypeInfo{} is "ltree"
         def matching(_state), do: [type: "ltree"]
 
         # Use the text format, "ltree" does not have a binary format.
         def format(_state), do: :text
 
         # Use quoted expression to encode a string that is the same as
         # postgresql's ltree text format. The quoted expression should contain
         # clauses that match those of a `case` or `fn`. Encoding matches on the
         # value and returns encoded `iodata()`. The first 4 bytes in the
         # `iodata()` must be the byte size of the rest of the encoded data, as a
         # signed 32bit big endian integer.
         def encode(_state) do
           quote do
             bin when is_binary(bin) ->
               [<<byte_size(bin) :: signed-size(32)>> | bin]
           end
         end
 
         # Use quoted expression to decode the data to a string. Decoding matches
         # on an encoded binary with the same signed 32bit big endian integer
         # length header.
         def decode(:reference) do
           quote do
             <<len::signed-size(32), bin::binary-size(len)>> ->
               bin
           end
         end
         def decode(:copy) do
           quote do
             <<len::signed-size(32), bin::binary-size(len)>> ->
               :binary.copy(bin)
           end
         end
       end
 
   This example could be used in a custom types module:
 
       Postgrex.Types.define(MyApp.Types, [MyApp.LTree])
 
   Or pass in opts for the extension that will be passed to the `init/1` callback:
 
       Postgrex.Types.define(MyApp.Types, [{MyApp.LTree, [decode_copy: :copy]}])
 
   """
 
   @type t :: module
   @type state :: term
 
   @doc """
   Should perform any initialization of the extension. The function receives the
   user options. The state returned from this function will be passed to other
   callbacks.
   """
   @callback init(Keyword.t()) :: state
 
   @doc """
   Prelude defines properties and values that are attached to the body of
   the types module.
   """
   @callback prelude(state) :: Macro.t()
 
   @doc """
   Specifies the types the extension matches, see `Postgrex.TypeInfo` for
   specification of the fields.
   """
   @callback matching(state) :: [
               type: String.t(),
               send: String.t(),
               receive: String.t(),
               input: String.t(),
               output: String.t()
             ]
 
   @doc """
   Returns the format the type should be encoded as. See
   http://www.postgresql.org/docs/9.4/static/protocol-overview.html#PROTOCOL-FORMAT-CODES.
   """
   @callback format(state) :: :binary | :text
 
   @doc """
   Returns a quoted list of clauses that encode an Elixir value to iodata.
 
   It must use a signed 32 bit big endian integer byte length header.
 
       def encode(_) do
         quote do
           integer ->
             <<8 :: signed-32, integer :: signed-64>>
         end
       end
 
   """
   @callback encode(state) :: Macro.t()
 
   @doc """
   Returns a quoted list of clauses that decode a binary to an Elixir value.
 
   The pattern must use binary syntax and decode a fixed length using the signed
   32 bit big endian integer byte length header.
 
       def decode(_) do
         quote do
           # length header is in bytes
           <<len :: signed-32, integer :: signed-size(len)-unit(8)>> ->
             integer
         end
       end
   """
   @callback decode(state) :: Macro.t()
 
   @optional_callbacks [prelude: 1]
 end