Trimming and dependencies

Public selection macroImplementation macroDirect dependencies
XRT_MODULE_XLONL_COREXRT_FEATURE_XLONL_COREcore
XRT_MODULE_XLONL_READXRT_FEATURE_XLONL_READxlonl_core, xlon_read
XRT_MODULE_XLONL_WRITEXRT_FEATURE_XLONL_WRITExlonl_core, xlon_write
XRT_MODULE_XLONL_FILEXRT_FEATURE_XLONL_FILExlonl_read, xlonl_write, file_whole
XRT_MODULE_XLONLXRT_FEATURE_XLONLxlonl_file

The header is <xrt/xlonl.h> and can also be included through the umbrella header <xrt.h>. Selecting only reading or only writing does not pull in the file module.

Stability contract

  • Blank lines are ignored by default: empty lines, and lines containing only ASCII spaces, tabs, or CR. LF, CRLF, and mixed endings are accepted; a lone CR is not a record separator. Unicode whitespace never turns a line into a blank line.
  • Empty input and input consisting entirely of blank lines both return an empty Array. Strict blank-line mode still accepts zero-byte input and a single terminating newline after the last record; extra blank lines are errors.
  • A line must contain exactly one complete value; the final complete record may omit the terminating newline. Multi-line values, multiple root values on one line, a BOM, invalid UTF-8, and a truncated trailing record all fail.
  • An escaped newline inside a string does not split records. Array records preserve nesting; for example the text []\n yields an Array containing one empty array.
  • Deserialization hands over the owned Array only after every record succeeds; on failure it returns C NULL and frees all partial results.
  • The serialization root must be XVALUE_ARRAY; null, the empty string, and empty containers are real records. The SKIP strategy cannot skip a whole record, it only applies to members inside a single root value.
  • Output is compact, one LF appended per record, and an empty Array produces zero bytes. A PRETTY configuration is rejected. The configuration is snapshotted by value; a callback mutating the original configuration does not affect the in-flight call.
  • Valid reuses the DOM-free syntax validation of XLON: blank lines are ignored, the default cumulative budgets and built-in tags are checked, and duplicate-key DOM policy does not participate.
  • File writing completes the in-memory serialization first and then replaces the file atomically; a serialization failure leaves the target untouched. Synchronous callback writing may have committed partial records before failing; those bytes cannot be rolled back.
  • Single-line comments and trailing commas are compatibility extensions enabled only inside Record; they must not continue across physical lines.
  • XLONL supports the bytes, time, set, intmap, and non-finite float tags plus explicit custom codec callbacks; objects and side effects created by custom callbacks are the caller's responsibility, the cumulative value budget counts input syntax values without traversing callback-created objects, and the cumulative decode budget counts only built-in bytes tags.

Threading and ownership: the API carries no implicit locks; each call owns an independent workspace, and the caller synchronizes shared mutable input. Writing iterates a backing snapshot of the outer Array, so Value subtree ownership rules still apply during callbacks. Input text and configuration are borrowed until the call returns; the result Array is released with xrtValueRelease, the result string with xrtFree. The output callback consumes bytes before returning.

Constants

ConstantValueMeaning
XXLONL_READ_REJECT_EMPTY_LINESUINT32_C(0x00000001)Blank lines become errors; off by default.

Configurations must be initialized with Init; all budgets are non-zero. Record defaults come from the existing XLON initialization functions. Overall input/output defaults to 64 MiB; record count and syntax value count default to 1000000. The cumulative decode budget for built-in bytes tags defaults to 64 MiB.

xxlonlerrortype

Errors are obtained via xrtGetError() with format domain xrt.xlonl; argument and underlying OOM failures may also surface as Core errors directly. RECORD/OUTPUT/IO wrappers preserve the Cause Kind. If building the wrapper itself fails to allocate, the original cause error is kept and no location data is promised.

ValueMeaning
XXLONL_ERROR_CONFIGConfiguration not initialized, reserved bits non-zero, a zero budget, or PRETTY enabled.
XXLONL_ERROR_SYNTAXA blank line in strict blank-line mode.
XXLONL_ERROR_LIMITOverall or per-record budget exhausted.
XXLONL_ERROR_RECORDEncoding/decoding a single value or appending it to the Array failed; the Cause keeps the specific reason.
XXLONL_ERROR_TYPEThe serialization root is not an Array.
XXLONL_ERROR_OUTPUTSynchronous output callback failed.
XXLONL_ERROR_IOBudgeted file read or atomic file replacement failed.
XXLONL_ERROR_STATEReserved code for an invalid line-processing state.
typedef enum xxlonlerror { XXLONL_ERROR_CONFIG = 1801, XXLONL_ERROR_SYNTAX, XXLONL_ERROR_LIMIT, XXLONL_ERROR_RECORD, XXLONL_ERROR_TYPE, XXLONL_ERROR_OUTPUT, XXLONL_ERROR_IO, XXLONL_ERROR_STATE } xxlonlerror;

xxlonllocationtype

FieldTypeMeaning
Offsetsize_tZero-based byte offset in the raw input.
Linesize_tOne-based physical line number split on LF; CRLF counts as one line, and ignored blank lines still count.
Columnsize_tOne-based UTF-8 byte column within the current physical line; not counted in Unicode characters.
RecordIndexsize_tZero-based record index; blank lines do not increment it, and a blank-line error points at the next pending record index.
typedef struct xxlonllocation { size_t Offset; size_t Line; size_t Column; size_t RecordIndex; } xxlonllocation;

xxlonlreadflagtype

ValueMeaning
XXLONL_READ_REJECT_EMPTY_LINESTurns the blank lines ignored by default into syntax errors.
typedef enum xxlonlreadflag { XXLONL_READ_REJECT_EMPTY_LINES = UINT32_C(0x00000001)

xxlonlreadconfigtype

FieldTypeMeaning
RecordxxlonreadconfigPer-record configuration; MaxInputBytes/MaxOutputBytes exclude the CRLF/LF separators, and depth counts from each record's root value.
Flagsuint32Defaults to 0; XXLONL_READ_REJECT_EMPTY_LINES enables blank-line errors.
MaxInputBytessize_tCap on the whole raw input, including ignored blank lines and all separators; default 64 MiB.
MaxRecordssize_tCap on non-blank record count, equal to the maximum element count of the result Array; default 1000000.
MaxTotalValuessize_tCumulative cap on syntax values across all records, including values dropped by duplicate-key policy and excluding the synthesized Array; default 1000000.
MaxTotalDecodedBytessize_tCap on cumulative decoded bytes for built-in bytes tags, checked before buffer allocation; default 64 MiB.
Reserveduint32[4]Reserved space; must be all zero.
typedef struct xxlonlreadconfig { xxlonreadconfig Record; uint32 Flags; size_t MaxInputBytes; size_t MaxRecords; size_t MaxTotalValues; size_t MaxTotalDecodedBytes; uint32 Reserved[4]; } xxlonlreadconfig;

xxlonlwriteconfigtype

FieldTypeMeaning
RecordxxlonwriteconfigPer-record configuration; MaxInputBytes/MaxOutputBytes exclude the CRLF/LF separators, and depth counts from each record's root value.
MaxOutputBytessize_tCap on total output bytes, including every LF and excluding the trailing NUL of the result; default 64 MiB.
MaxRecordssize_tCap on non-blank record count, equal to the maximum element count of the result Array; default 1000000.
Reserveduint32[4]Reserved space; must be all zero.
typedef struct xxlonlwriteconfig { xxlonwriteconfig Record; size_t MaxOutputBytes; size_t MaxRecords; uint32 Reserved[4]; } xxlonlwriteconfig;
Text, configuration, and file interfaces

xrtXlonlErrorLocationfunction

Reads the global byte offset, one-based physical line/column, and zero-based record index; leaves the output unchanged when no location is present.

bool xrtXlonlErrorLocation(const xerror* pError, xxlonllocation* pLocation)

Parameters

ParameterDirectionConstraintsDescription
pErrorinputmay be null; read-only borrowReads the location from an error of this format; returns false for no location or a foreign error domain.
pLocationoutputnon-nullFilled with the global location on success; contents unchanged on failure.
Return value
ReturnMeaningState on failure
trueLocation read.—
falseNo location or invalid argument.Location output unchanged; absence of a location does not itself set an error.
Errors
  • XERR_ARGUMENT — the location output is null.

ExampleCompile-verified

xlonl · Call to xrtXlonlErrorLocation in the complete program; failure jumps to unified cleanup.

if ( !xrtXlonlErrorLocation(xrtGetError(), &Location) ) goto done;

xrtXlonlReadConfigInitfunction

Initializes blank-line skipping by default, strict per-record syntax, and bounded cumulative budgets.

void xrtXlonlReadConfigInit(xxlonlreadconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
pConfigoutputnon-nullSets defaults and zeroes the reserved fields.
Return value
ReturnMeaningState on failure
voidInitialization complete.A null pointer sets an argument error.
Errors
  • XERR_ARGUMENT — the configuration output is null.

ExampleCompile-verified

xlonl · Call to xrtXlonlReadConfigInit in the complete program; failure jumps to unified cleanup.

xrtXlonlReadConfigInit(&Read);

xrtXlonlParsefunction

Parses the record sequence with default configuration; returns an owned Array on success, an empty Array for empty input.

xvalue* xrtXlonlParse(xstrview Text)

Parameters

ParameterDirectionConstraintsDescription
Textinputexplicit byte length; NULL Data only at zero lengthThe whole text is borrowed until the call returns; input need not be NUL-terminated.
Return value
ReturnMeaningState on failure
non-nullOwned Array for the caller to release.—
NULLArgument, budget, syntax, or resource error.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlParse in the complete program; failure jumps to unified cleanup.

pArray = xrtXlonlParse(XRT_STR_LITERAL("{\"id\":1}\n\n[2,3]\r\nnull\n"));
if ( pArray == NULL ) goto done;

xrtXlonlReadfunction

Parses all records per configuration; on failure frees partial results and returns NULL. Release the result with xrtValueRelease.

xvalue* xrtXlonlRead(xstrview Text, const xxlonlreadconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
Textinputexplicit byte length; NULL Data only at zero lengthThe whole text is borrowed until the call returns; input need not be NUL-terminated.
pConfiginputnon-null; must be initializedPer-record configuration and cumulative budgets; the source is not modified by this call.
Return value
ReturnMeaningState on failure
non-nullOwned Array for the caller to release.—
NULLArgument, budget, syntax, or resource error.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlRead in the complete program; failure jumps to unified cleanup.

pRead = xrtXlonlRead((xstrview){ Text, Size }, &Read);
if ( pRead == NULL ) goto done;

xrtXlonlValidfunction

Ignores blank lines by default and validates per-line syntax and cumulative budgets without building a Value DOM; duplicate-key policy does not participate.

bool xrtXlonlValid(xstrview Text)

Parameters

ParameterDirectionConstraintsDescription
Textinputexplicit byte length; NULL Data only at zero lengthThe whole text is borrowed until the call returns; input need not be NUL-terminated.
Return value
ReturnMeaningState on failure
trueEvery non-blank line passed the default syntax and budget checks.—
falseOperation failed.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlValid in the complete program; failure jumps to unified cleanup.

if ( !xrtXlonlValid((xstrview){ Text, Size }) ) goto done;

xrtXlonlWriteConfigInitfunction

Initializes compact single-line output, LF separation, and bounded cumulative budgets; a PRETTY configuration is invalid.

void xrtXlonlWriteConfigInit(xxlonlwriteconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
pConfigoutputnon-nullSets defaults and zeroes the reserved fields.
Return value
ReturnMeaningState on failure
voidInitialization complete.A null pointer sets an argument error.
Errors
  • XERR_ARGUMENT — the configuration output is null.

ExampleCompile-verified

xlonl · Call to xrtXlonlWriteConfigInit in the complete program; failure jumps to unified cleanup.

xrtXlonlWriteConfigInit(&Write);

xrtXlonlStringifyfunction

Writes each Array element as one line; returns NUL-terminated text released with xrtFree. On failure the optional pSize is left unchanged.

str xrtXlonlStringify(const xvalue* pArray, size_t* pSize)

Parameters

ParameterDirectionConstraintsDescription
pArrayinputnon-null and of type XVALUE_ARRAYElements to serialize; the call does not consume the caller's owned reference.
pSizeoutputmay be nullOn success receives the byte count including LF and excluding the NUL; unchanged on failure.
Return value
ReturnMeaningState on failure
non-nullOwned NUL-terminated text; empty output still returns a releasable string.—
NULLConfiguration, type, encoding, or resource error.pSize unchanged; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_TYPE — the serialization root is not an Array.
  • XERR_UNSUPPORTED — a single value cannot be encoded by the selected format.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlStringify in the complete program; failure jumps to unified cleanup.

Text = xrtXlonlStringify(pArray, &Size);
if ( Text == NULL ) goto done;

xrtXlonlWritefunction

Writes each record and its LF to a synchronous chunked callback; the callback's borrowed bytes are valid only during the call, and bytes committed before a failure cannot be rolled back.

bool xrtXlonlWrite(const xvalue* pArray, const xxlonlwriteconfig* pConfig, xxlonwriteproc pWrite, ptr pUserData)

Parameters

ParameterDirectionConstraintsDescription
pArrayinputnon-null and of type XVALUE_ARRAYElements to serialize; the call does not consume the caller's owned reference.
pConfiginputnon-null; must be initializedPer-record configuration and cumulative budgets; the source is not modified by this call.
pWriteinputnon-null synchronous callbackConsumes borrowed bytes in chunks; returning false aborts output.
pUserDatainputmay be nullPassed through to the synchronous output callback.
Return value
ReturnMeaningState on failure
trueAll output completed.—
falseOperation failed.Input references stay with the caller; committed bytes cannot be rolled back, and the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_TYPE — the serialization root is not an Array.
  • XERR_UNSUPPORTED — a single value cannot be encoded by the selected format.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlWrite in the complete program; failure jumps to unified cleanup.

if ( !xrtXlonlWrite(pArray, &Write, discard, NULL) ) goto done;

xrtXlonlParseFilefunction

Reads the file under the default budget and returns an owned Array.

xvalue* xrtXlonlParseFile(cstr sPath)

Parameters

ParameterDirectionConstraintsDescription
sPathinputnon-null NUL-terminated pathFile to read, or target file for atomic replacement.
Return value
ReturnMeaningState on failure
non-nullOwned Array for the caller to release.—
NULLArgument, budget, syntax, or resource error.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlParseFile in the complete program; failure jumps to unified cleanup.

pRead = xrtXlonlParseFile(Path);
if ( pRead == NULL ) goto done;

xrtXlonlReadFilefunction

Reads the file under the overall input cap and parses it line by line; on failure no partial Array is returned.

xvalue* xrtXlonlReadFile(cstr sPath, const xxlonlreadconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
sPathinputnon-null NUL-terminated pathFile to read, or target file for atomic replacement.
pConfiginputnon-null; must be initializedPer-record configuration and cumulative budgets; the source is not modified by this call.
Return value
ReturnMeaningState on failure
non-nullOwned Array for the caller to release.—
NULLArgument, budget, syntax, or resource error.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlReadFile in the complete program; failure jumps to unified cleanup.

pRead = xrtXlonlReadFile(Path, &Read);
if ( pRead == NULL ) goto done;

xrtXlonlStringifyFilefunction

Fully serializes the Array with default configuration and then replaces the file atomically.

bool xrtXlonlStringifyFile(cstr sPath, const xvalue* pArray)

Parameters

ParameterDirectionConstraintsDescription
sPathinputnon-null NUL-terminated pathFile to read, or target file for atomic replacement.
pArrayinputnon-null and of type XVALUE_ARRAYElements to serialize; the call does not consume the caller's owned reference.
Return value
ReturnMeaningState on failure
trueAll output completed.—
falseOperation failed.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_TYPE — the serialization root is not an Array.
  • XERR_UNSUPPORTED — a single value cannot be encoded by the selected format.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlStringifyFile in the complete program; failure jumps to unified cleanup.

if ( !xrtXlonlStringifyFile(Path, pArray) ) goto done;

xrtXlonlWriteFilefunction

Fully serializes with the advanced configuration and then replaces the file atomically; a serialization failure keeps the original file.

bool xrtXlonlWriteFile(cstr sPath, const xvalue* pArray, const xxlonlwriteconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
sPathinputnon-null NUL-terminated pathFile to read, or target file for atomic replacement.
pArrayinputnon-null and of type XVALUE_ARRAYElements to serialize; the call does not consume the caller's owned reference.
pConfiginputnon-null; must be initializedPer-record configuration and cumulative budgets; the source is not modified by this call.
Return value
ReturnMeaningState on failure
trueAll output completed.—
falseOperation failed.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_TYPE — the serialization root is not an Array.
  • XERR_UNSUPPORTED — a single value cannot be encoded by the selected format.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

xlonl · Call to xrtXlonlWriteFile in the complete program; failure jumps to unified cleanup.

if ( !xrtXlonlWriteFile(Path, pArray, &Write) ) goto done;

Constant indexconstant

The following constants are defined in this page's header; semantics are documented in the public header comments.

ConstantDescription
XXLONL_ERROR_CONFIGSee header comments
XXLONL_ERROR_IOSee header comments
XXLONL_ERROR_LIMITSee header comments
XXLONL_ERROR_OUTPUTSee header comments
XXLONL_ERROR_RECORDSee header comments
XXLONL_ERROR_STATESee header comments
XXLONL_ERROR_SYNTAXSee header comments
XXLONL_ERROR_TYPESee header comments
XXLONL_READ_REJECT_EMPTY_LINESSee header comments