Skip to content

Releases

stury 0.2.1

Choose a tag to compare

@filip-41 filip-41 released this 18 Nov 18:08
Immutable release. Only release title and notes can be modified.

Install

  • Each release carries a Windows amd64 build, stury-VERSION-windows-amd64.zip.
  • The command line installs from PyPI on macOS, Linux and Windows (uv tool install stury, pipx install stury, or
    uvx stury to run it once).
  • The command line installs from a Homebrew tap on macOS and Linux (brew install filip-41/tap/stury), with its
    manual page.

Command line

  • On Windows the command line maps the files it reads, as on darwin and linux, and takes its process heap from the
    segment heap.

stury 0.2.0

Choose a tag to compare

@github-actions github-actions released this 18 Nov 11:19
Immutable release. Only release title and notes can be modified.

Library

  • New format packages toml (TOML 1.0 and 1.1), yaml (YAML 1.2, core schema), xml (XML 1.0 with namespaces and the
    internal subset), html (the WHATWG tokenizer, tree builder and serializer) and cbor (RFC 8949, with
    preferred, deterministic and length-first specs). Each has the same validate, build, find, scan, query,
    unmarshal, marshal and edit calls as json and dsv, and edits keep every byte they do not target.
  • Facts carry across formats: comments, YAML tags, anchors and styles, TOML datetimes and number forms, XML and HTML
    attributes and namespaces, CBOR tags and byte strings. A conversion writes a fact where the output holds it, and a
    comment keeps one place in every format.
  • core/model loads and dumps Odin structs under a registry of rules (tags, defaults, validators, hooks, unions,
    patch), judged with the same error kinds as a JSON Schema. core/schema compiles and binds JSON Schema drafts 4, 6,
    7, 2019-09 and 2020-12, and infers, samples, compares and converts through a schema and writes a description as
    Odin types (schema.write_odin).
  • core/diff tells the changes between two values, with keys, sets and facts. core/css matches CSS selectors
    over XML and HTML. core/regex is an Oniguruma and ECMA regex engine with Unicode 17 tables.
  • Every call that fails returns core.Error, one union that core.render writes. A refusal names the type wanted and the
    value found, and a writer's refusal names its reason in the format's words.
  • A format package takes its spec in format, as json.format(src, .Json5), and forwards comment, end_record,
    reorder and set_facts. The edit list's setter is write.set_node in every format.
  • core/records reads and writes records of every format, into documents or typed values, including CSV and TSV
    through records.Writer with Write_Options.grow_header, and reads the records under a path of keys with .Entries.
  • A repeated key follows one dups field of the read's options in every format.
  • A hex, octal or binary integer, or one with underscores, compares equal to its decimal.
  • JSON's walk passes its state in registers between states, a compact write drops blanks with vpcompressb on an
    Intel CPU with AVX512-VBMI2, and a map of 1024 keys or more is written sorted by a radix sort.
  • unmarshal of TOML, and of YAML whose members read from their tokens alone, builds no document. A TOML path read
    under stop_early parses only the statements its answer needs.
  • A TOML or XML build walks its text once. A TOML table tree keeps its comments apart, and an HTML tree grows in chunks
    that are never copied, so both builds hold less memory.
  • A typed TOML write lays out its tables in one pass and writes a bare key bare, and a typed XML write writes its
    elements with no value built in between.
  • A document read from CBOR, YAML, XML or TOML is written without examining again what its read already judged: a CBOR
    string or small integer, a YAML plain or single-quoted scalar and a TOML basic string are copied as they were read.
    A TOML basic string keeps its escapes, as a JSON string does, unless respell_strings or ascii is set.
  • An HTML write and an HTML edit check what they wrote by comparing the tree it reads back, with no second write.
  • A query over a built document stops reading an array once the element or the first key its step picks has passed.
  • records.validate reads a YAML stream or a CBOR sequence in pieces on threads, and a CBOR sequence's items are
    judged by the walk that frames them.
  • A JSON Schema whose anyOf, oneOf, not or if arms read only member names and those members' own values is
    judged with no branch run for them, and unevaluatedProperties beside such arms is settled when the schema compiles.
  • A buffer output starts at 1 KiB, and a compact write reserves no room for line breaks, so many small writes into one
    arena hold less memory.

Command line

  • Reads and writes TOML, YAML, XML, HTML, CBOR and JSON5 as well as JSON, JSONC, NDJSON, CSV and TSV. --from and --to
    take a spec after a colon (toml:1.0, html:fragment, cbor:deterministic). Without --from, the extension of the
    named files picks the format.
  • fmt converts between formats and keeps comments, number spellings, tags, directives and layout where the output has
    them. It refuses with exit 5 a value its output cannot hold and says why.
  • edit applies a jq filter to a text and keeps every byte the filter does not change, in every format. --diff tells
    the changes, per document for a YAML stream.
  • .@comment, .@comment_inline, .@comment_foot, .@style, .@tag, .@directives and .&NAME read and write
    facts and attributes, and .@(name) and .&[name] take a computed name. A step that names an unknown fact is an
    error.
  • css(selector) selects the elements of an XML or HTML input.
  • --attributes reads each attribute of an XML or HTML element as its member @NAME, and writes such a member back
    as an attribute.
  • check --schema FILE judges each input against a JSON Schema and tells every failure. check --filter F --schema S
    types a filter against the schema of its inputs. --schema-draft names the draft of a schema with no $schema.
  • diff tells what differs between two inputs, two schemas (--compat) or a schema and data.
  • schema infer, schema sample and schema gen write a JSON Schema from inputs, values that pass a schema, and the
    Odin types a model reads its values with.
  • --stream reads every format, and --seq reads JSONC and JSON5 records. --to json5 is accepted, and fmt
    reads and writes JSON5 with --check and --in-place.
  • A YAML integer past 64 bits, a TOML number with underscores and a JSON5 number with a sign or a lone point read and
    convert by their value and keep their spelling where the output has it.

stury 0.1.1

Choose a tag to compare

@github-actions github-actions released this 05 Nov 11:14
Immutable release. Only release title and notes can be modified.

The first published release. The v0.1.0 tag built no artifacts: the release workflow ran the smoke script directly,
and it fails the cases cmd/stury/test/smoke.floor records as known failures, where make test-cli runs
smoke_floor.py and holds only the cases outside the floor. The release now uses the same floor, and this archive
carries the figures in docs/benchmarks.md. The rebuilt API described below is unchanged from 0.1.0.

The rebuilt tree, and the first release of the stury:core, stury:json and stury:dsv packages. It builds with
Odin dev-2026-11 or later and targets 64-bit little-endian systems (darwin and linux, on amd64 and arm64; the
command line also builds on Windows).

The rebuilt library

The library and the command line are rebuilt on one interface for every format. Code written against the earlier names
changes as follows.

  • csv is now dsv, and reads Csv, Tsv and Plain delimited text. json and dsv take the format as an
    argument: json.Spec is .Json, .Jsonc or .Json5 (it replaces Dialect), and dsv.Spec is .Csv, .Tsv or
    .Plain. A call reads json.unmarshal(src, .Json, &v) and dsv.unmarshal(src, .Csv, &rows). The walk settings
    are one Options struct per package: max_depth and tolerate for JSON, and no_header, delimiter, comment,
    tolerate, crlf and infer for dsv.
  • Everything a caller uses across formats lives in core: documents, readers, paths, edits, Write_Options and
    errors. json and dsv give each format's validate, build, find, scan, set, commit, unmarshal,
    marshal and as. json.format formats a text.
  • Errors are values with a kind, not optional enums or strings. core.Fault is a text that breaks the grammar,
    core.Document_Error, core.Path_Error, core.Path_Edit_Error and core.Typed_Error the others. One
    core.render writes any of them as line:col: message, with the path for a typed error, so
    json.render_error and csv.render_error are gone.
  • find and scan return a core.Document and core.Answer records, and core.query collects the values a path
    reaches from a built document. They replace Request, its kinds and answers. A path is parsed with
    core.parse_path or core.parse_pointer once, owns its steps and is freed with core.path_destroy.
  • Records are in core/records: check, open, open_stream, next, each and a record writer
    (writer_init, write, write_text, write_cells, writer_end). They replace records, each_record,
    validate_records, Record_Reader, Record_Read and records_from. Framings are .Lines, .Seq,
    .Concatenated and .Entries. A stream reads through a window.
  • Threads are host.Pool, started with host.pool_init and lent to records.each through pool.runner. It
    replaces host.Batch_Pool.
  • Edits are an Edit_List made with core.edit_list_init, recorded with core.set, core.set_member,
    core.insert and core.remove, each checked as it is recorded, and applied with json.commit, dsv.commit or
    core.commit. json.set and dsv.set still replace one value at a path. A delimited text commits through the
    list, and removing a cell from every row drops its column.
  • Typed reads take an explicit plan from json.plan_make or dsv.plan_make. A plan belongs to the caller and there
    is no global plan cache, so plan_cache_clear is gone. typed.Read_Options holds dups, refuse_duplicates,
    unknown, borrow_strings and collect, and typed.Plan_Options holds enums, union_tag, tag_names,
    hooks and rename. The unknown tag flag captures unnamed members into a map[string]typed.Raw.
  • core.Duplicates is .First or .Last. Refusing a repeated key is the refuse_duplicates argument of build,
    find, set and the typed read, and every_key is a path read option that answers every matching key.
  • .Lazy and Strictness are gone: a value that is read is always judged by the format's grammar.
    Options.tolerate names the rules a text may break, Invalid_Utf8 and Lone_Surrogate.
  • Comments are facts on a node with a core.Role of Comment, Comment_Inline or Comment_Foot. Read them with
    core.facts_of and edit them with core.set_fact and core.remove_fact.
  • core.Write_Options sets pretty, indent, tab, ascii, escape_html, escape_del, sort_keys and
    respell_strings for marshal, format, core.write and the record writer, whichever the format.
  • A document keeps its buffers whole, and a build that runs out of memory counts the text and builds again at the
    exact size. core.length_exact, core.member_of and core.element_of read a partial document, where a miss is
    .Missing or .Wrong_Kind.
  • The stury:core, stury:json, stury:dsv, stury:core/records, stury:core/typed and stury:host imports
    replace stury:json, stury:csv and stury:host as they were.

Command line

  • A number keeps any exponent: 1e2147483648 prints as written, and a computation that overflows gives the largest
    double. The "exponent out of range" error and --strict-limits are gone.
  • --follow answers each record of one named file as it is appended. --max-depth takes up to 1048576.
  • --to json5 is refused, and fmt --in-place and fmt --check are refused for JSON5 input. --to jsonc writes the
    values and their comments.
  • --explain writes the filter's plan (route, path or columns, engine, refusals) and what the run did to stderr,
    and runs the filter as without it.
  • --from json5 reads JSON5 in filters, fmt and check. Error lines and input_line_number count the text's
    own lines.
  • check validates a large root array, or the array of a root object, on the thread pool.
  • --stream gives the events of a faulty text before its fault, as jq does, and input_line_number and the error
    positions under --stream count jq's lines. --stream-errors gives a faulty text's events as it reads them, not
    all before the first.
  • A JSONC or JSON5 input of only comments and whitespace is no input, as a whitespace-only one is.
  • Windows: strftime's %k and %l pad the hour with a space, as jq does, not a zero.
  • Regex \R no longer matches the trailing byte of a multibyte character that a global match steps into.
  • macOS: a pipe named as a path (/dev/stdin, <(...)) is read wherever a file is: inputs, --slurpfile,
    --rawfile, -f, check and fmt.
  • The differences from jq recorded in docs/cli.md are unchanged.
  • The command line and the library give the same answer on every format.

stury 0.0.3

Choose a tag to compare

@github-actions github-actions released this 26 Oct 12:45
Immutable release. Only release title and notes can be modified.

Library

  • Record_Read (json and csv) reads each record of one type; CSV can now decode a stream one record at a time.
  • csv.validate_records lists every refused record, as json.validate_records does (core.Record_Fault).
  • csv.query, find and find_column answer paths like JSON's (core.Answer), honouring duplicates.
  • One Read_Opts per format (dialect, strictness, duplicates, limits, and CSV's no_header, which
    replaces header) is taken before the allocator. The JSON edits take dialect before the allocator.
  • One read error: scan, find, request_init and build return Maybe(Error); parse_path and query
    return Maybe(Path_Error). Scan_Error, Request_Error, Capacity, Parse_Error, Prepared and the
    public render_error_to_writer are removed.
  • Renamed: Encode_Error/Encode_Opts to Marshal_Error/Marshal_Opts; the csv destroy procedures are one
    csv.destroy. core/bits and core/path are folded into core. json.records_from and
    json.Record_Reader are removed.
  • Refused instead of misread: an unknown tag flag or unspellable tag (.Bad_Tag), an unsorted or overlapping
    edit list (.Bad_Edit), a Number with no finite value in marshal (.Non_Finite), a CSV cell that
    underflows in get_float, and an edit of a CSV column name two columns share.

Command line

  • stury fmt formats or transcodes files, keeping every number, string, key and comment as written
    (--check, --in-place).
  • --csv, --tsv, --ndjson and --jsonc are removed: use --from and --to.
  • Parse errors at the end of the input name jq's column; --seq reads its files as one stream; debug and
    stderr lines flush in order with the output.
  • Windows: filter arguments are read as UTF-8, -L takes an absolute path, and strftime gives %s, %k and %l.

stury 0.0.2

Choose a tag to compare

@github-actions github-actions released this 24 Oct 07:30

Adds the CSV and TSV codec (stury:csv), the shared stury:core package, and the CLI's --from and --to.

  • stury:core holds what the formats share. JSON's walk substrate moved from it to
    stury:json/scan/walk: the rows and their stores (Node, Capacity, Number_Spelling), the caps (Limits,
    MAX_DEPTH, MAX_SCALAR_DIGITS), the scan cursor, the query context and its matchers, and the typed walk's
    state (Shape_Run, Shape_Frame). json's names for them are unchanged.

  • stury:core/spell spells integers and floats for every format's writer (spell_i64, spell_u64, spell_f64,
    shortest_digits, is_non_finite), moved from stury:json/encode; stury:core/bits holds the shared bit
    and UTF-8 kernels.

  • core declares Unknown_Fields, Unmarshal_Hook, Type_Hook(W) and Hooked_Plan(W) (with
    hooked_plan_init and hooked_plan_destroy); json and csv alias them,
    so their Type_Hook and Type_Plan are core.Type_Hook(Marshal_Hook) and core.Hooked_Plan(Marshal_Hook)
    with the same fields. core.Value_Class names the classes a union's arm is picked by.

  • CLI: --from FORMAT and --to FORMAT (json, jsonc, ndjson, csv, tsv) choose how the input is read
    and the output written. --ndjson, --jsonc, --csv and --tsv set both halves, and an explicit --from
    or --to replaces its half, in either order. Behaviour change: --ndjson now prints compact, one value per
    line (it left the layout alone), so --ndjson --indent N and --ndjson --tab, which printed indented JSON, are
    now a usage error (exit 2); --to ndjson is -c.

  • CLI: --to csv and --to tsv write each output as one record. An object is a row under a header of the first
    object's keys (sorted under -S); a missing key is an empty cell and an extra key ends the run with exit 5.
    --grow-header holds the output and writes a header of every key in the order first seen, or in byte order
    under -S (memory holds all the output). An array or scalar is a row with no header, and the two kinds do not mix. A string is its text, a
    number is spelled as jq spells it, null is an empty cell, and an array or object in a cell ends the run.
    -r, -j, -a, -C, -c, --indent, --tab, --seq and --raw-output0 are a usage error with it. A
    filter that is only columns is printed in pieces, with the same output as the interpreter.

  • CLI: @tsv, @csv and @sh write a NUL as \0, and @csv, @tsv and --to csv write NaN as an empty
    cell, as jq does. They wrote the raw byte and null.

  • CLI: reading CSV, an empty cell with no quotes is null and a quoted "" is ""; every empty TSV cell is
    null. stury --csv . writes back what it read, up to normalisation. TSV cannot tell null
    from "".

  • CLI: stury check takes --from and the aliases; CSV and TSV go through csv.validate, and a fault is reported
    as in a filter run.

  • CLI: --csv and --tsv read CSV (RFC 4180) and TSV (jq's @tsv escapes). The first record of each file names
    the fields, and each later record is one input, an object of strings (stury --from csv -r '[.a, .b] | @csv'
    writes back what it read). A repeated header name, a record of another width and a fault in the text end the
    file, reported as FILE:LINE:COLUMN: fault with exit 5. A file up to 64 MiB is read whole. A larger file, a pipe
    and a file under -n are read in windows, so memory holds a window and the longest record. A filter that is only
    columns (.name, .a, .b, [.a, .b] under --from csv -c, an object of columns, ., and select(F) of columns)
    is printed from the cells, in pieces on every core for a whole file. Not with -R, --seq, --ndjson, --jsonc, --stream or each other.

  • stury:csv, a CSV codec. validate and the records iterator check every byte of RFC 4180 text (quote
    placement, CR before LF, UTF-8, one field count throughout). field_text reads a field's text. unmarshal
    reads records into a list of structs on the shared type plan, with columns named by a header or taken in
    order, and judges each cell against its field's type. marshal writes such a list as text that unmarshal
    reads back into equal values.

  • CSV dialects. validate, records, field_text, unmarshal and marshal take a Dialect (delimiter,
    Quoting.None where a quote is text, Escapes.Backslash, a comment byte, ragged records). TSV is
    tab-separated values with backslash escapes (\t, \n, \r, \0, \\). They also take a Strictness
    (.Structural skips the UTF-8 check; unmarshal under .Lazy judges only the cells it reads) and
    Limits.max_fields. marshal refuses with .Unwritable a cell its dialect cannot spell so that it reads
    back, and a record that would be a blank line. The delimiter options are now dialect.delimiter.

  • CSV documents and edits: build keeps the field spans of a text as a Document (row_count, column,
    get_string, get_int, get_float, get_bool, get_name), find and find_column read one cell or one
    column by path (.[3].name, .[3][1], .[].name) off the front of the text, and set, insert, remove
    and splice return the text with a cell, a column, a record or a span changed and every other byte kept. A
    refusal is a Path_Error; the edits spell values as marshal does and refuse what would not read back as the
    same table.

  • CSV Plan_Opts.hooks: a Type_Hook gives a type a Marshal_Hook (appends the cell's text, which marshal
    quotes) and an Unmarshal_Hook (gets the decoded cell text, never an absent cell, and may refuse it); a field
    of a hooked type is a cell whatever its type.

  • CSV Unmarshal_Opts.duplicates (Duplicates: Refuse, First, Last, All) for a header that names a column
    twice, and unmarshal_check, which judges a text exactly as unmarshal would and keeps nothing.

  • CSV marshal_append (appends to a buffer, which a refusal leaves as it was) and marshal_to_writer (streams
    in bounded chunks; adds Marshal_Error.Write_Failed). marshal is a wrapper over the same writer.

  • CSV write_record appends one record of text cells ([]Maybe(string), nil an empty cell that reads back absent)
    to a buffer in a dialect, spelling each cell as marshal does. A blank line, which reads back as no record, is
    .Unwritable.

  • error_position, render_error and render_error_to_writer for CSV, sharing JSON's implementation through
    core; JSON's names and outputs are unchanged.

  • Path_Error and Path_Error_Kind: one refusal type for the path procedures of every format, with each
    format's docs listing the kinds it reports. json.Edit_Error and json.Edit_Error_Kind are now
    json.Path_Error and json.Path_Error_Kind, whose kinds are renumbered and gain CSV's Unsupported_Path,
    Bad_Option and Bad_Row.

  • Marshal_Error: one marshal refusal for every format; json.Encode_Error and csv.Marshal_Error are its
    aliases. json.Encode_Error gains CSV's Bad_Option and Unwritable, which JSON never reports. A path
    refusal's encode field is a Marshal_Error. render_error and render_error_to_writer
    write it for CSV as for JSON.

  • Duplicates: one policy for repeated keys in every format, in core. Its new zero value .Default is the
    format's default (JSON .Last, CSV .Refuse), so a zero-valued option reads as before. json.Duplicates
    and csv.Duplicates are its aliases. JSON's is now a u8.

  • Error_Kind.Field_Count, the CSV fault of a record whose field count is not the first record's, and
    Error_Kind.Limit_Fields, of a record with more fields than Limits.max_fields. JSON never reports them.

  • CSV streaming and threads: csv.records_from reads the records of an io.Reader a chunk at a time, with the
    same records, offsets and fault as records on the whole text. csv.each_record runs a task on pieces of a
    text on a Batch_Runner's threads. csv.validate takes a runner too and gives the same answer as without one.
    Limits.max_record_bytes caps a record (Error_Kind.Limit_Record) and so bounds the window records_from holds. A
    Record carries the src its fields index. Batch_Runner is defined in stury:core; json.Batch_Runner
    names it.

  • Request and Prepared name their type parameter $KINDS (was $Q), as the generic procedures that take
    them do. Callers that write Request({.Path}) are unaffected.

  • marshal writes an empty json.Digits as null, as it writes an empty json.Raw, instead of failing with
    .Bad_Raw.

  • render_error of an Unmarshal_Error ends with its path (1:11: Wrong_Kind at .a.b), with … when the path
    was truncated.

  • unmarshal's .Unsupported for a ,string field, or for two fields writing one key, names that field in the
    error path.

  • scan at .Structural checks the UTF-8 of values no path reads, as validate does: invalid UTF-8 anywhere
    in the document now fails the scan.

  • CLI: halt_error/1 with a non-number argument names its input as jq does (number (1) halt_error/1: number required).

  • CLI: select(PATH OP literal) on a large single document reads only its path, and prints the text only when it
    keeps it, instead of building the whole document.

stury 0.0.1

Choose a tag to compare

@github-actions github-actions released this 22 Oct 15:31

The first release. It builds with Odin dev-2026-10 and targets 64-bit little-endian systems (darwin and
linux, on amd64 and arm64).

Library (stury:json, stury:host)

  • Validation: check a text against RFC 8259 without allocating, with the line and column of the first fault.
  • Path queries: read the values at one or more paths without parsing the rest of the text (find for one
    path's first answer, a Request for more).
  • Parsed documents: build a document once and query it, numbers are checked when it is built and decoded when
    read, so the input must outlive the document.
  • Typed unmarshal and marshal: read JSON into Odin structs, slices, maps, unions and any, and write Odin
    values back as JSON.
  • Byte-preserving edits: set, insert, remove and splice change only the bytes they target.
  • NDJSON and RFC 7464 records: iterate the values of a line-delimited or record-separated stream.
  • JSONC: read comments and trailing commas, and write the comments back.
  • Parallel validation and per-record work take threads from stury:host (Batch_Pool), and the library starts no
    thread of its own.
  • One error convention and fixed limits throughout. Each public name's doc comment describes it. A
    procedure whose result is its only output carries @(require_results), so a dropped result is a compile
    error.
  • On amd64 the floor is x86-64-v2, long strings are scanned 64 bytes at a time where the processor has
    AVX-512BW.

Command line (stury)

  • jq 1.8.2's language, answers and exit codes. Its messages start with stury: and are worded its own way;
    where stury answers differently, docs/cli.md lists it. Modules (import, include, -L,
    ~/.jq), every jq option except --run-tests (a test-file runner stury does not have), --seq,
    --stream, colours, and regular expressions in Oniguruma syntax (with their own engine, so there is no
    dependency on the Oniguruma library).
  • New options: --ndjson, --jsonc, --max-depth N (allow nesting past 1024 for every input, fromjson and
    option JSON, where jq caps at 10000) and the stury check subcommand (--strict-limits holds the library's
    digit and scale limits).
  • --jsonc output keeps the comments of values taken unchanged from the input and drops them on values the
    filter made. Use .@comment, .@comment_inline and .@comment_foot to read them as a list of texts or
    null.
  • Large inputs are read and printed on several threads (see host.Batch_Pool in stury:host).
  • Filters that recurse in tail position use constant memory, and recursion can go about a million levels deep.