Backend.hs

{- | Identifier for a serialization backend.

A 'Backend' is a textual tag attached to per-backend modifier overrides
(e.g. @forBackend backendProto (rename "n")@) and consulted by each
per-format deriver to decide which modifiers apply.

New backends can be defined by downstream packages: just construct a
'Backend' with a fresh identifier. The set of \"standard\" backends
defined here is open-ended and exists only as a convenience so that
common cases compose cleanly.
-}
module Wireform.Derive.Backend (
  Backend (..),

  -- * Standard backends
  backendProto,
  backendCBOR,
  backendMsgPack,
  backendThrift,
  backendJSON,
  backendEDN,
  backendTOML,
  backendYAML,
  backendXML,
  backendHTML,
  backendCSV,
  backendNDJSON,
  backendBinary,
  backendTextFormat,

  -- * Schema-driven backends
  backendASN1,
  backendAvro,
  backendBond,
  backendFlatBuffers,
  backendCapnProto,

  -- * Document / object stores
  backendBSON,
  backendBencode,
  backendION,

  -- * Cross-language object serialization
  backendFory,

  -- * Columnar / tabular
  backendArrow,
  backendParquet,
  backendOrc,
  backendIceberg,
) where

import Control.DeepSeq (NFData)
import Data.Data (Data)
import Data.Hashable (Hashable)
import Data.String (IsString)
import Data.Text (Text)
import GHC.Generics (Generic)


{- | Open identifier for a serialization backend.

'Backend' has an 'IsString' instance, so backends can be written
inline as string literals, e.g. @forBackend "proto" (rename "n")@.
Prefer the named constants below where they exist so that typos are
caught at compile time.
-}
newtype Backend = Backend {unBackend :: Text}
  deriving stock (Eq, Ord, Show, Data, Generic)
  deriving newtype (IsString, Hashable, NFData)


-- | Protocol Buffers wire encoding.
backendProto :: Backend
backendProto = Backend "proto"


-- | RFC 8949 CBOR.
backendCBOR :: Backend
backendCBOR = Backend "cbor"


-- | MessagePack.
backendMsgPack :: Backend
backendMsgPack = Backend "msgpack"


-- | Apache Thrift binary protocol.
backendThrift :: Backend
backendThrift = Backend "thrift"


{- | JSON (used by both Aeson-style and Proto3 JSON mappings;
Proto-JSON-specific overrides should additionally tag with
'backendProto').
-}
backendJSON :: Backend
backendJSON = Backend "json"


-- | Extensible Data Notation (Clojure / EDN).
backendEDN :: Backend
backendEDN = Backend "edn"


-- | TOML.
backendTOML :: Backend
backendTOML = Backend "toml"


-- | YAML.
backendYAML :: Backend
backendYAML = Backend "yaml"


-- | XML.
backendXML :: Backend
backendXML = Backend "xml"


-- | CSV / TSV header rows.
backendCSV :: Backend
backendCSV = Backend "csv"


-- | HTML serialization (sub-vocabulary of XML; element/attribute split).
backendHTML :: Backend
backendHTML = Backend "html"


-- | Newline-delimited JSON. One record per line.
backendNDJSON :: Backend
backendNDJSON = Backend "ndjson"


{- | Catch-all for hand-rolled binary formats that do not fit one of the
standard backends above.
-}
backendBinary :: Backend
backendBinary = Backend "binary"


-- | Protobuf text format (@google.protobuf.TextFormat@ / @pbtxt@).
backendTextFormat :: Backend
backendTextFormat = Backend "textformat"


-- ---------------------------------------------------------------------------
-- Schema-driven binary formats
-- ---------------------------------------------------------------------------

-- | ASN.1 BER / DER / PER family.
backendASN1 :: Backend
backendASN1 = Backend "asn1"


-- | Apache Avro.
backendAvro :: Backend
backendAvro = Backend "avro"


-- | Microsoft Bond.
backendBond :: Backend
backendBond = Backend "bond"


-- | FlatBuffers.
backendFlatBuffers :: Backend
backendFlatBuffers = Backend "flatbuffers"


-- | Cap\'n Proto.
backendCapnProto :: Backend
backendCapnProto = Backend "capnproto"


-- ---------------------------------------------------------------------------
-- Document / object stores
-- ---------------------------------------------------------------------------

-- | BSON (MongoDB binary JSON).
backendBSON :: Backend
backendBSON = Backend "bson"


-- | BitTorrent's Bencode.
backendBencode :: Backend
backendBencode = Backend "bencode"


-- | Amazon ION (rich-typed JSON superset).
backendION :: Backend
backendION = Backend "ion"


-- ---------------------------------------------------------------------------
-- Cross-language object serialization
-- ---------------------------------------------------------------------------

{- | Apache Fory (formerly Fury) xlang serialization. Field names
are converted to @snake_case@ before being written as the
spec\'s meta-string field name.
-}
backendFory :: Backend
backendFory = Backend "fory"


-- ---------------------------------------------------------------------------
-- Columnar / tabular
-- ---------------------------------------------------------------------------

-- | Apache Arrow in-memory columnar layout.
backendArrow :: Backend
backendArrow = Backend "arrow"


-- | Apache Parquet.
backendParquet :: Backend
backendParquet = Backend "parquet"


-- | Apache ORC.
backendOrc :: Backend
backendOrc = Backend "orc"


-- | Apache Iceberg table format.
backendIceberg :: Backend
backendIceberg = Backend "iceberg"