GitHub

API Reference

Complete API documentation for TokenOrientedObjectNotation.jl.

Main Functions

encode

encode(value; options::EncodeOptions=EncodeOptions()) -> String

Encode a Julia value to TOON format string.

Arguments:

  • value: Any Julia value (will be normalized to JSON model)
  • options: Optional encoding configuration

Returns: TOON formatted string

Example:

data = Dict("name" => "Alice", "age" => 30)
toon_str = TOON.encode(data)

decode

decode(input::String; options::DecodeOptions=DecodeOptions()) -> JsonValue

Decode a TOON format string to a Julia value.

Arguments:

  • input: TOON formatted string
  • options: Optional decoding configuration

Returns: Parsed Julia value (Dict, Array, or primitive)

Example:

input = "name: Alice\nage: 30"
data = TOON.decode(input)

Configuration Types

EncodeOptions

EncodeOptions(;
    indent::Int = 2,
    delimiter::Delimiter = COMMA,
    keyFolding::String = "off",
    flattenDepth::Int = typemax(Int)
)

Configuration for encoding behavior.

Fields:

  • indent::Int: Number of spaces per indentation level (default: 2)
  • delimiter::Delimiter: Delimiter for arrays - COMMA, TAB, or PIPE (default: COMMA)
  • keyFolding::String: Key folding mode - "off" or "safe" (default: "off")
  • flattenDepth::Int: Maximum folding depth (default: unlimited)

Example:

options = TOON.EncodeOptions(
    indent = 4,
    delimiter = TOON.TAB,
    keyFolding = "safe",
    flattenDepth = 2
)

DecodeOptions

DecodeOptions(;
    indent::Int = 2,
    strict::Bool = true,
    expandPaths::String = "off"
)

Configuration for decoding behavior.

Fields:

  • indent::Int: Expected spaces per indentation level (default: 2)
  • strict::Bool: Enable strict validation (default: true)
  • expandPaths::String: Path expansion mode - "off" or "safe" (default: "off")

Example:

options = TOON.DecodeOptions(
    indent = 4,
    strict = true,
    expandPaths = "safe"
)

Constants

Delimiters

COMMA::Delimiter    # ","
TAB::Delimiter      # "\t"
PIPE::Delimiter     # "|"

Delimiter constants for array encoding.

Example:

options = TOON.EncodeOptions(delimiter=TOON.TAB)

Escape Sequences

BACKSLASH = "\\\\"   # \\
DOUBLE_QUOTE = "\\"" # \"
NEWLINE = "\\n"      # \n
CARRIAGE_RETURN = "\\r"  # \r
TAB_ESCAPE = "\\t"   # \t

Valid escape sequences in TOON strings.

Type Aliases

JsonValue

JsonValue = Union{JsonObject, JsonArray, JsonPrimitive}

Any valid JSON value type.

JsonObject

JsonObject = Dict{String, JsonValue}

JSON object (dictionary with string keys).

JsonArray

JsonArray = Vector{JsonValue}

JSON array (vector of values).

JsonPrimitive

JsonPrimitive = Union{String, Number, Bool, Nothing}

JSON primitive types (string, number, boolean, null).

Internal Types

These types are used internally but may be useful for advanced usage.

LineWriter

mutable struct LineWriter
    lines::Vector{String}
end

Helper for building multi-line output during encoding.

Methods:

  • push!(writer, depth, content): Add a line at specified depth

LineCursor

mutable struct LineCursor
    lines::Vector{ParsedLine}
    position::Int
    blankLines::Vector{BlankLine}
end

Helper for parsing multi-line input during decoding.

Methods:

  • peek(cursor): Look at current line without advancing
  • advance!(cursor): Move to next line
  • has_more(cursor): Check if more lines available

ParsedLine

struct ParsedLine
    content::String
    depth::Int
    lineNumber::Int
end

Represents a parsed line with indentation information.

ArrayHeader

struct ArrayHeader
    length::Int
    delimiter::Delimiter
    fields::Union{Vector{String}, Nothing}
end

Parsed array header information.

Fields:

  • length: Declared array length
  • delimiter: Active delimiter for this array
  • fields: Field names for tabular arrays (or nothing)

Utility Functions

normalize

normalize(value) -> JsonValue

Normalize a Julia value to the JSON data model.

Transformations:

  • NaN, Inf, -Inf → nothing (null)
  • -0.0 → 0.0
  • Dictionaries → JsonObject
  • Arrays → JsonArray
  • Other types → primitives

Example:

TOON.normalize(NaN)  # nothing
TOON.normalize(-0.0)  # 0.0

istabulararray

is_tabular_array(arr::Vector) -> Bool

Check if an array can be encoded in tabular format.

Requirements:

  • All elements are objects (dictionaries)
  • All objects have the same keys
  • All keys are strings

Example:

arr = [Dict("a" => 1, "b" => 2), Dict("a" => 3, "b" => 4)]
TOON.is_tabular_array(arr)  # true

needs_quoting

needs_quoting(s::String, delimiter::Delimiter) -> Bool

Check if a string needs to be quoted.

Quoting required for:

  • Empty strings
  • Strings with whitespace
  • Reserved literals (true, false, null)
  • Numeric-like strings
  • Strings with special characters
  • Strings containing the active delimiter

Example:

TOON.needs_quoting("hello", TOON.COMMA)  # false
TOON.needs_quoting("hello world", TOON.COMMA)  # true
TOON.needs_quoting("true", TOON.COMMA)  # true

Error Types

TokenOrientedObjectNotation.jl throws ErrorException with descriptive messages for various error conditions:

  • Array count mismatch: "Array length mismatch: expected X, got Y"
  • Row width mismatch: "Row width mismatch at line X: expected Y fields, got Z"
  • Missing colon: "Missing colon after key at line X"
  • Invalid escape: "Invalid escape sequence: \X"
  • Unterminated string: "Unterminated string at line X"
  • Indentation error: "Indentation must be a multiple of X spaces (line Y)"
  • Tab in indentation: "Tabs are not allowed in indentation (line X)"
  • Blank line error: "Blank lines are not allowed inside arrays (line X)"
  • Path conflict: "Cannot expand path 'X': segment 'Y' already exists as non-object"

Version Information

TOON.version  # Package version

Get the current version of TokenOrientedObjectNotation.jl.

Next Steps