Append an item to the list at a key path, creating the list if the key does not exist yet.

let assert Ok(doc) = ccl.parse("ports =\n  = 80\n")
let assert Ok(updated) =
  ccl.append_list_item(doc, ["ports"], ccl.StringValue("443"))
ccl.to_string(updated)
// -> "ports =\n  = 80\n  = 443\n"

Read a boolean from a Value, accepting only true and false.

Use as_bool_with to apply a document’s Booleans option. See as_string for the error convention.

Read a boolean from a Value using the given options.

Read a float from a Value. See as_string for the error convention.

Read an integer from a Value. See as_string for the error convention.

Read a list of terminal strings from a Value, without list coercion.

Use as_list_with to apply a document’s ListCoercion option. See as_string for the error convention.

Read a list of terminal strings from a Value using the given options.

Read a block’s entries from a Value, in source order.

See as_string for the error convention.

Read a string from a Value.

Mirrors get_string, but operates on a Value already obtained from get. On a type mismatch the error reports an empty key path, since a bare Value has no path context.

Read a list of values from a Value, without list coercion.

Read a list of values from a Value using the given options.

A decoder for CCL’s boolean text, accepting only true and false.

See int_decoder for why decode.bool does not work here.

Parse CCL text and run a gleam/dynamic/decode decoder against it.

This is a convenience wrapper around parse_dynamic and decode.run.

import gleam/dynamic/decode

let server_decoder = {
  use host <- decode.field("host", decode.string)
  use port <- decode.field("port", decode.string)
  decode.success(#(host, port))
}

ccl.decode("host = localhost\nport = 8080\n", server_decoder)
// -> Ok(#("localhost", "8080"))

Every CCL terminal value is text, so decode.int, decode.bool, and decode.float do not match. Use int_decoder, bool_decoder, and float_decoder for those fields.

Parse CCL text with the given options and run a dynamic decoder against it.

The default options: CRLF normalised to LF, tabs as whitespace, a stripped top-level indent, spaced-delimiter preference, strict booleans, no list coercion, and insertion-ordered lists.

Read a document’s flat entries, in source order and before any nesting is expanded.

This is CCL’s first parsing pass: every top-level key = value pair, with nested blocks left as the raw multi-line text of their value. Use to_value for the expanded tree.

let assert Ok(doc) = ccl.parse("server =\n  host = localhost\n")
ccl.entries(doc)
// -> [ccl.Entry("server", "\n  host = localhost")]

A decoder for CCL’s float text. An integer literal decodes as a float.

See int_decoder for why decode.float does not work here.

Read a CCL value at a key path.

An empty path returns the whole document as an ObjectValue. Use get instead of the typed get_* helpers when you need to inspect nested blocks or lists.

A path segment that is a non-negative decimal indexes into a list, either a ListValue directly or the list held under an enclosing block’s empty key, so get(doc, ["ports", "0"]) reads the first item of ports =\n = 80.

let assert Ok(doc) = ccl.parse("server =\n  host = localhost\n")
ccl.get(doc, ["server"])
// -> Ok(ccl.ObjectValue([#("host", ccl.StringValue("localhost"))]))

Read a terminal value at a key path and parse it as a boolean.

The document’s Booleans option controls which strings match; BooleanStrict (the default) accepts only true and false, case-insensitively.

Read a terminal value at a key path and parse it as a float.

An integer literal reads as a float, so 2 yields 2.0.

Read a terminal value at a key path and parse it as an integer.

Read a list of terminal strings at a key path.

This reads both a bare list and CCL’s usual named-list shape, where the items live under the empty key of a nested block:

let assert Ok(doc) = ccl.parse("ports =\n  = 80\n  = 443\n")
ccl.get_list(doc, ["ports"])
// -> Ok(["80", "443"])

A non-list value is a WrongType error unless the document was parsed with with_list_coercion(CoercionEnabled), which reads it as a single item.

Read a terminal string value at a key path.

Read a list of values at a key path, keeping nested items intact.

This accepts the same list shapes as get_list.

Insert a comment line immediately before the entry at a key path.

CCL writes comments as /= text. The text may not contain a newline; call this once per line for a multi-line comment.

let assert Ok(doc) = ccl.parse("port = 8080\n")
let assert Ok(updated) =
  ccl.insert_comment_before(doc, ["port"], "the listening port")
ccl.to_string(updated)
// -> "/= the listening port\nport = 8080\n"

A decoder for CCL’s integer text.

Every CCL terminal value is text, so decode.int never matches a parsed document. This reads the same lexical form get_int accepts, and is what belongs in a decoder for an Int field.

import gleam/dynamic/decode

let decoder = {
  use port <- decode.field("port", ccl.int_decoder())
  decode.success(port)
}

ccl.decode("port = 8080\n", decoder)
// -> Ok(8080)

Read the keys of the block at a key path, in source order.

An empty path returns the document’s top-level keys.

let assert Ok(doc) = ccl.parse("server =\n  host = localhost\n  port = 8080\n")
ccl.keys(doc, ["server"])
// -> Ok(["host", "port"])

Convert a byte offset into a one-based line and column.

Offsets beyond the end of the input return the position just after the last character. CRLF counts as a single line break.

Create an empty CCL document.

Equivalent to parse("") for downstream callers. The only observable difference: a document from parse("") records that its source had no trailing newline, so its edits emit none, while a document from new always ends its output with one.

Return the options a document was parsed with.

Parse CCL text into a document using the default options.

The returned Document preserves the source text, key order, comments, and indentation for round-tripping.

let assert Ok(doc) = ccl.parse("answer = 42\n")
let assert Ok(42) = ccl.get_int(doc, ["answer"])

Parse CCL bytes into a document.

This validates that the input is UTF-8 before parsing.

let assert Ok(doc) = ccl.parse_bytes(<<"answer = 42\n":utf8>>)

ccl.parse_bytes(<<110, 97, 109, 101, 32, 61, 32, 255, 10>>)
// -> Error(ccl.InvalidEncoding)

Parse CCL bytes into a document with the given options.

Parse CCL text into decoder-friendly dynamic data.

See to_dynamic for the shape of the result.

Parse CCL text into decoder-friendly dynamic data with the given options.

Parse pre-indented CCL text, detecting the baseline indentation from the first content line rather than assuming column 0.

Use this for a CCL fragment lifted out of a larger document, where every line still has the enclosing block’s indentation.

let assert Ok(doc) = ccl.parse_indented("    host = localhost\n")
let assert Ok("localhost") = ccl.get_string(doc, ["host"])

Parse pre-indented CCL text with the given options.

Parse a standalone CCL value, as it would appear on the right-hand side of an =.

A single-line input is always a terminal StringValue, even when it contains an = — that = is content, not a delimiter. A multi-line input expands into an ObjectValue or ListValue.

ccl.parse_value("localhost")
// -> Ok(ccl.StringValue("localhost"))

ccl.parse_value("\n  host = localhost\n")
// -> Ok(ccl.ObjectValue([#("host", ccl.StringValue("localhost"))]))

Parse a standalone CCL value with the given options.

Parse CCL text into a document with the given options.

Return the one-based column number for a source position.

Return the one-based line number for a source position.

Emit a flat entry list as CCL text.

This is CCL’s structure-preserving print, the inverse of the parse pass: print(entries(doc)) reproduces the document’s source for standard-format input, without a trailing newline. Use to_string to emit a whole document with its original trailing newline restored.

Remove the value at a key path.

Removing a key that appears more than once removes every occurrence. Removing the last entry of a nested block leaves the block’s key in place with an empty value.

Set a boolean value at a key path, written as true or false.

Set a float value at a key path.

Set an integer value at a key path.

Set a list of terminal strings at a key path, written as CCL’s named-list shape.

let assert Ok(doc) = ccl.set_list(ccl.new(), ["ports"], ["80", "443"])
ccl.to_string(doc)
// -> "ports =\n  = 80\n  = 443\n"

Set a nested block at a key path from an ordered list of entries.

Set a terminal string value at a key path, creating intermediate blocks as needed.

The value may not contain a newline; use set_value with an ObjectValue or ListValue for multi-line data.

let assert Ok(doc) = ccl.parse("server =\n  host = localhost\n")
let assert Ok(updated) = ccl.set_string(doc, ["server", "host"], "example.com")
ccl.to_string(updated)
// -> "server =\n  host = example.com\n"

Set any Value at a key path, creating intermediate blocks as needed.

This writes nested values with two-space indentation relative to their parent. It replaces an existing key in place, so the key keeps its position and the comments around it.

Emit a document in CCL’s canonical form: normalised two-space indentation, keys sorted lexicographically, and duplicate keys merged.

This preserves meaning rather than layout, so comments and source order do not survive.

Convert a document to decoder-friendly dynamic data.

The shape is intentionally JSON-like: nested blocks become property maps, repeated empty-key entries become lists, and terminal values become strings. A block that holds only a list — CCL’s key =\n = a\n = b — becomes the list itself rather than a map with an empty-string key.

Read a document as CCL’s canonical recursive Model.

Emit a document as CCL text.

Unedited parsed documents round-trip to their original source text. An edited document re-emits from its entries and keeps key order, comments, and the indentation of untouched blocks.

Read a document as a single ObjectValue, in source order.

Equivalent to get(doc, []).

Read a value nested inside a Value.

Mirrors get, but operates on a Value already obtained from get, so nested data can be read without re-walking from the document root. Errors report the path relative to the supplied value.

Set the indentation baseline used for top-level entries.

Set which strings get_bool and as_bool accept.

Set how the parser locates the = delimiter.

Set how the parser treats CRLF line endings.

Set whether a terminal value reads as a one-element list.

Set the order in which repeated empty-key entries are collected.

Set how the parser treats tab characters.