thrifty

-module(thrifty).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/thrifty.gleam").
-export([main/0, from_bit_array/1, with_options/2, read_string/1, read_i32/1, read_bool_element/1, skip_value/2, default_reader_options/0, new_struct_writer/0]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

-file("src/thrifty.gleam", 35).
?DOC(
    " Convenience top-level API for small projects that `import thrifty`\n"
    "\n"
    " This module exposes a tiny, curated surface so consumers that import\n"
    " `thrifty` have quick access to common reader/writer helpers without\n"
    " importing internal submodules. For advanced usage prefer importing\n"
    " `thrifty/reader` or `thrifty/writer` directly.\n"
    " CLI entry used for quick manual checks during development.\n"
    "\n"
    " This module is primarily a library: consumers should `import thrifty`\n"
    " and use the provided helpers (for example `from_bit_array`,\n"
    " `with_options`, `new_struct_writer`). The `main` here is a small,\n"
    " non-invasive convenience that prints a short message when the package\n"
    " is run directly. It is intentionally minimal and not a replacement for\n"
    " a proper CLI or integration in a production project.\n"
).
-spec main() -> nil.
main() ->
    gleam_stdlib:println(
        <<"thrifty: library — import `thrifty` and use the helpers (this main is a tiny smoke-test, not a production CLI)"/utf8>>
    ).

-file("src/thrifty.gleam", 57).
?DOC(
    " Construct a reader from a low-level BitArray containing a compact-encoded\n"
    " Thrift payload.\n"
    "\n"
    " Inputs\n"
    " - `data`: the `BitArray` which contains the bytes of a compact-encoded\n"
    "   Thrift message. The function does not copy `data`; the returned reader\n"
    "   references it immutably.\n"
    "\n"
    " Outputs\n"
    " - Returns a `types.Reader` positioned at the start of `data` suitable for\n"
    "   subsequent `read_*` operations.\n"
    "\n"
    " Error modes / guarantees\n"
    " - This constructor does not perform parsing or validation beyond creating\n"
    "   the reader. Errors from malformed payloads appear when read operations\n"
    "   are invoked (for example `read_i32` or `read_string`).\n"
).
-spec from_bit_array(bitstring()) -> thrifty@types:reader().
from_bit_array(Data) ->
    thrifty@reader:from_bit_array(Data).

-file("src/thrifty.gleam", 77).
?DOC(
    " Construct a reader with explicit runtime limits and decoding options.\n"
    "\n"
    " Inputs\n"
    " - `data`: the `BitArray` containing the compact-encoded payload.\n"
    " - `options`: a `types.ReaderOptions` record controlling limits such as\n"
    "   maximum container items, maximum recursion depth, maximum string bytes,\n"
    "   and the boolean element policy.\n"
    "\n"
    " Outputs\n"
    " - Returns a `types.Reader` configured with the provided `options`.\n"
    "\n"
    " Semantics and safety\n"
    " - Options are enforced during subsequent read operations; when a limit is\n"
    "   exceeded the reader will return a `types.DecodeError` rather than crash.\n"
    " - Use this constructor when parsing untrusted data or when you need to\n"
    "   enforce resource bounds in library consumers.\n"
).
-spec with_options(bitstring(), thrifty@types:reader_options()) -> thrifty@types:reader().
with_options(Data, Options) ->
    thrifty@reader:with_options(Data, Options).

-file("src/thrifty.gleam", 95).
?DOC(
    " Read a compact-encoded string from the provided reader.\n"
    "\n"
    " Inputs\n"
    " - `r`: the `types.Reader` positioned at the start of a string field.\n"
    "\n"
    " Outputs\n"
    " - On success returns `Ok((value, reader'))` where `value` is the decoded\n"
    "   UTF-8 string and `reader'` is the reader advanced past the string bytes.\n"
    " - On failure returns `Error(types.DecodeError)` describing the problem\n"
    "   (for example truncated data, invalid UTF-8, or exceeding configured\n"
    "   `max_string_bytes`).\n"
).
-spec read_string(thrifty@types:reader()) -> {ok,
        {binary(), thrifty@types:reader()}} |
    {error, thrifty@types:decode_error()}.
read_string(R) ->
    thrifty@reader:read_string(R).

-file("src/thrifty.gleam", 112).
?DOC(
    " Read a 32-bit signed integer encoded with Thrift compact varint/zigzag\n"
    " encoding.\n"
    "\n"
    " Inputs\n"
    " - `r`: a `types.Reader` positioned at an integer field.\n"
    "\n"
    " Outputs\n"
    " - On success returns `Ok((value, reader'))` where `value` is the decoded\n"
    "   integer and `reader'` is the reader advanced past the integer encoding.\n"
    " - On failure returns `Error(types.DecodeError)`, typically for truncated\n"
    "   varint encodings or if the encoded value would cause an overflow.\n"
).
-spec read_i32(thrifty@types:reader()) -> {ok,
        {integer(), thrifty@types:reader()}} |
    {error, thrifty@types:decode_error()}.
read_i32(R) ->
    thrifty@reader:read_i32(R).

-file("src/thrifty.gleam", 136).
?DOC(
    " Read a boolean value when encoded as a field element in the compact\n"
    " protocol.\n"
    "\n"
    " Background\n"
    " - In Thrift Compact, boolean fields may be encoded either inline in the\n"
    "   field header (canonical) or as a separate byte depending on the writer\n"
    "   and field position. The reader's behavior may be controlled by the\n"
    "   `bool_element_policy` option in `types.ReaderOptions`.\n"
    "\n"
    " Inputs\n"
    " - `r`: the `types.Reader` positioned at a boolean field.\n"
    "\n"
    " Outputs\n"
    " - Returns `Ok((value, reader'))` with the boolean `value` and an advanced\n"
    "   reader on success.\n"
    " - Returns `Error(types.DecodeError)` for malformed encodings or when the\n"
    "   reader policy rejects non-canonical boolean encodings if the policy\n"
    "   requires canonical-only booleans.\n"
).
-spec read_bool_element(thrifty@types:reader()) -> {ok,
        {boolean(), thrifty@types:reader()}} |
    {error, thrifty@types:decode_error()}.
read_bool_element(R) ->
    thrifty@reader:read_bool_element(R).

-file("src/thrifty.gleam", 157).
?DOC(
    " Skip over a value of the specified Thrift `FieldType`.\n"
    "\n"
    " Inputs\n"
    " - `r`: the `types.Reader` positioned at the start of a value.\n"
    " - `t`: the `types.FieldType` describing the encoded type to skip.\n"
    "\n"
    " Outputs\n"
    " - Returns `Ok(reader')` with `reader'` advanced past the encoded value on\n"
    "   success.\n"
    " - Returns `Error(types.DecodeError)` when the encoded value is truncated,\n"
    "   when a container exceeds configured limits, or on other decoding errors.\n"
    "\n"
    " Notes\n"
    " - This helper is useful when the caller is only interested in selected\n"
    "   fields and wants to ignore others while still enforcing resource bounds.\n"
).
-spec skip_value(thrifty@types:reader(), thrifty@types:field_type()) -> {ok,
        thrifty@types:reader()} |
    {error, thrifty@types:decode_error()}.
skip_value(R, T) ->
    thrifty@reader:skip_value(R, T).

-file("src/thrifty.gleam", 172).
?DOC(
    " Return the default `types.ReaderOptions` used by convenience constructors.\n"
    "\n"
    " Outputs\n"
    " - A `types.ReaderOptions` record populated with conservative defaults for\n"
    "   maximum recursion depth, maximum container items, maximum string\n"
    "   length, and the boolean element policy. These defaults are chosen to be\n"
    "   safe for typical server workloads but can be overridden with\n"
    "   `with_options` for more restrictive or permissive policies.\n"
).
-spec default_reader_options() -> thrifty@types:reader_options().
default_reader_options() ->
    {reader_options, 64, 65536, 8388608, accept_canonical_only}.

-file("src/thrifty.gleam", 188).
?DOC(
    " Create a new high-level struct writer for building compact-encoded\n"
    " Thrift messages.\n"
    "\n"
    " Outputs\n"
    " - Returns a `high_writer.StructWriter` initially empty. The writer exposes\n"
    "   composable helpers to append fields and then produce a compact-encoded\n"
    "   `BitArray`.\n"
    "\n"
    " Semantics\n"
    " - The high-level writer is intended for small-to-medium sized payloads and\n"
    "   convenience usage. For maximum performance consider using a lower-level\n"
    "   writer if micro-optimizations are required.\n"
).
-spec new_struct_writer() -> thrifty@writer_highlevel:struct_writer().
new_struct_writer() ->
    thrifty@writer_highlevel:new().