-module(molt@ops).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/molt/ops.gleam").
-export_type([operation/0, form/0, conflict_strategy/0, comments/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.

?MODULEDOC(
    " molt/ops: Operation types for document manipulation.\n"
    "\n"
    " The types declared in this module offer document manipulation options for\n"
    " use in `molt.run` batches.\n"
    "\n"
    " ## Path Resolution Targets\n"
    "\n"
    " The `path` string provided to operations resolves against a logical version\n"
    " of the document's concrete syntax tree so that implicit nodes and value\n"
    " nodes may be modified. The shape of the targeted document node determines\n"
    " which operations are legal and what side-effects occur.\n"
    "\n"
    " - Concrete tables: tables defined by explicit headers, such as `[header]`\n"
    "   or `[database.connection]`.\n"
    "\n"
    " - Implicit tables: tables whose existence are implied by dotted key or\n"
    "   sub-header references. In `[database.connection]`, `database` is an\n"
    "   implicit table, as is `package` for a dotted key definition of:\n"
    "   `package.type = \"gleam\"`.\n"
    "\n"
    " - Array of tables: a collection of tables identified by `[[name]]` headers.\n"
    "   Paths may resolve to the collection by omitting index references\n"
    "   (`custom.plugins` referencing `[[custom.plugins]]`) and individual table\n"
    "   entries within the collection with index references (`custom.plugins[1]`\n"
    "   resolving to the second table in the collection).\n"
    "\n"
    " - Key/value nodes: a leaf assignment (`key = value`). The value may be\n"
    "   a scalar value (integer, float, string, etc.), an inline table, or an\n"
    "   array.\n"
    "\n"
    " - Inline table nodes: a table written using the inline table syntax\n"
    "   (`key = { … }`) that is part of a key/value node. Path strings may\n"
    "   extend into the inline table.\n"
    "\n"
    " - Arrays: a value node that may represent heterogenous TOML values. Path\n"
    "   strings allow resolution to the array or elements within an array using\n"
    "   the same syntax as array of table references.\n"
    "\n"
    " If an operation indicates that it works on a table-like path, it means that\n"
    " it may operate on concrete tables, implicit tables, or an array of tables\n"
    " entry.\n"
    "\n"
    " ## Operation Values\n"
    "\n"
    " Many operations work with `Value`s from `molt/value`, a comprehensive\n"
    " representation of TOML values that does not preserve comments or\n"
    " formatting.\n"
    "\n"
    " If an operation indicates that it works with a table-like value, it means\n"
    " that it will work with a Value representing an inline table or a concrete\n"
    " table's values.\n"
).

-type operation() :: {append, binary(), molt@value:value()} |
    {concat, binary(), list(molt@value:value())} |
    {ensure_exists, binary(), molt@types:toml_kind()} |
    {insert, binary(), integer(), molt@value:value()} |
    {insert_key, binary(), binary(), binary(), molt@value:value()} |
    {merge_values,
        binary(),
        list({binary(), molt@value:value()}),
        conflict_strategy()} |
    {move, binary(), binary()} |
    {move_comments, binary(), binary()} |
    {move_keys, binary(), binary(), list(binary()), conflict_strategy()} |
    {place, binary(), molt@value:value()} |
    {remove, binary()} |
    {rename, binary(), binary()} |
    {representation, binary(), form()} |
    {set, binary(), molt@value:value()} |
    {set_comments, binary(), comments()} |
    {transfer, binary(), binary(), conflict_strategy()} |
    {update,
        binary(),
        fun((molt@value:value()) -> {ok, molt@value:value()} |
            {error, molt@error:molt_error()})}.

-type form() :: block | inline.

-type conflict_strategy() :: on_conflict_error |
    on_conflict_overwrite |
    on_conflict_skip.

-type comments() :: {comments, list(binary()), gleam@option:option(binary())}.