Repository navigation
Releases
stury 0.2.1
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 sturyto 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
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) andcbor(RFC 8949, with
preferred, deterministic and length-first specs). Each has the samevalidate,build,find,scan,query,
unmarshal,marshaland edit calls asjsonanddsv, 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/modelloads 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/schemacompiles 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/difftells the changes between two values, with keys, sets and facts.core/cssmatches CSS selectors
over XML and HTML.core/regexis an Oniguruma and ECMA regex engine with Unicode 17 tables.- Every call that fails returns
core.Error, one union thatcore.renderwrites. 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, asjson.format(src, .Json5), and forwardscomment,end_record,
reorderandset_facts. The edit list's setter iswrite.set_nodein every format. core/recordsreads and writes records of every format, into documents or typed values, including CSV and TSV
throughrecords.WriterwithWrite_Options.grow_header, and reads the records under a path of keys with.Entries.- A repeated key follows one
dupsfield 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
vpcompressbon an
Intel CPU with AVX512-VBMI2, and a map of 1024 keys or more is written sorted by a radix sort. unmarshalof TOML, and of YAML whose members read from their tokens alone, builds no document. A TOML path read
understop_earlyparses 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, unlessrespell_stringsorasciiis 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.validatereads 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,notorifarms read only member names and those members' own values is
judged with no branch run for them, andunevaluatedPropertiesbeside 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.
--fromand--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. fmtconverts 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.editapplies a jq filter to a text and keeps every byte the filter does not change, in every format.--difftells
the changes, per document for a YAML stream..@comment,.@comment_inline,.@comment_foot,.@style,.@tag,.@directivesand.&NAMEread 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.--attributesreads each attribute of an XML or HTML element as its member@NAME, and writes such a member back
as an attribute.check --schema FILEjudges 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-draftnames the draft of a schema with no$schema.difftells what differs between two inputs, two schemas (--compat) or a schema and data.schema infer,schema sampleandschema genwrite a JSON Schema from inputs, values that pass a schema, and the
Odin types a model reads its values with.--streamreads every format, and--seqreads JSONC and JSON5 records.--to json5is accepted, andfmt
reads and writes JSON5 with--checkand--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
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.
csvis nowdsv, and readsCsv,TsvandPlaindelimited text.jsonanddsvtake the format as an
argument:json.Specis.Json,.Jsoncor.Json5(it replacesDialect), anddsv.Specis.Csv,.Tsvor
.Plain. A call readsjson.unmarshal(src, .Json, &v)anddsv.unmarshal(src, .Csv, &rows). The walk settings
are oneOptionsstruct per package:max_depthandtoleratefor JSON, andno_header,delimiter,comment,
tolerate,crlfandinferfor dsv.- Everything a caller uses across formats lives in
core: documents, readers, paths, edits,Write_Optionsand
errors.jsonanddsvgive each format'svalidate,build,find,scan,set,commit,unmarshal,
marshalandas.json.formatformats a text. - Errors are values with a
kind, not optional enums or strings.core.Faultis a text that breaks the grammar,
core.Document_Error,core.Path_Error,core.Path_Edit_Errorandcore.Typed_Errorthe others. One
core.renderwrites any of them asline:col: message, with the path for a typed error, so
json.render_errorandcsv.render_errorare gone. findandscanreturn acore.Documentandcore.Answerrecords, andcore.querycollects the values a path
reaches from a built document. They replaceRequest, its kinds andanswers. A path is parsed with
core.parse_pathorcore.parse_pointeronce, owns its steps and is freed withcore.path_destroy.- Records are in
core/records:check,open,open_stream,next,eachand a record writer
(writer_init,write,write_text,write_cells,writer_end). They replacerecords,each_record,
validate_records,Record_Reader,Record_Readandrecords_from. Framings are.Lines,.Seq,
.Concatenatedand.Entries. A stream reads through a window. - Threads are
host.Pool, started withhost.pool_initand lent torecords.eachthroughpool.runner. It
replaceshost.Batch_Pool. - Edits are an
Edit_Listmade withcore.edit_list_init, recorded withcore.set,core.set_member,
core.insertandcore.remove, each checked as it is recorded, and applied withjson.commit,dsv.commitor
core.commit.json.setanddsv.setstill 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_makeordsv.plan_make. A plan belongs to the caller and there
is no global plan cache, soplan_cache_clearis gone.typed.Read_Optionsholdsdups,refuse_duplicates,
unknown,borrow_stringsandcollect, andtyped.Plan_Optionsholdsenums,union_tag,tag_names,
hooksandrename. Theunknowntag flag captures unnamed members into amap[string]typed.Raw. core.Duplicatesis.Firstor.Last. Refusing a repeated key is therefuse_duplicatesargument ofbuild,
find,setand the typed read, andevery_keyis a path read option that answers every matching key..LazyandStrictnessare gone: a value that is read is always judged by the format's grammar.
Options.toleratenames the rules a text may break,Invalid_Utf8andLone_Surrogate.- Comments are facts on a node with a
core.RoleofComment,Comment_InlineorComment_Foot. Read them with
core.facts_ofand edit them withcore.set_factandcore.remove_fact. core.Write_Optionssetspretty,indent,tab,ascii,escape_html,escape_del,sort_keysand
respell_stringsformarshal,format,core.writeand 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_ofandcore.element_ofread a partial document, where a miss is
.Missingor.Wrong_Kind. - The
stury:core,stury:json,stury:dsv,stury:core/records,stury:core/typedandstury:hostimports
replacestury:json,stury:csvandstury:hostas they were.
Command line
- A number keeps any exponent:
1e2147483648prints as written, and a computation that overflows gives the largest
double. The "exponent out of range" error and--strict-limitsare gone. --followanswers each record of one named file as it is appended.--max-depthtakes up to 1048576.--to json5is refused, andfmt --in-placeandfmt --checkare refused for JSON5 input.--to jsoncwrites the
values and their comments.--explainwrites 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 json5reads JSON5 in filters,fmtandcheck. Error lines andinput_line_numbercount the text's
own lines.checkvalidates a large root array, or the array of a root object, on the thread pool.--streamgives the events of a faulty text before its fault, as jq does, andinput_line_numberand the error
positions under--streamcount jq's lines.--stream-errorsgives 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%kand%lpad the hour with a space, as jq does, not a zero. - Regex
\Rno 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,checkandfmt. - The differences from jq recorded in
docs/cli.mdare unchanged. - The command line and the library give the same answer on every format.
stury 0.0.3
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_recordslists every refused record, asjson.validate_recordsdoes (core.Record_Fault).csv.query,findandfind_columnanswer paths like JSON's (core.Answer), honouringduplicates.- One
Read_Optsper format (dialect,strictness,duplicates,limits, and CSV'sno_header, which
replacesheader) is taken before the allocator. The JSON edits takedialectbefore the allocator. - One read error:
scan,find,request_initandbuildreturnMaybe(Error);parse_pathandquery
returnMaybe(Path_Error).Scan_Error,Request_Error,Capacity,Parse_Error,Preparedand the
publicrender_error_to_writerare removed. - Renamed:
Encode_Error/Encode_OptstoMarshal_Error/Marshal_Opts; the csv destroy procedures are one
csv.destroy.core/bitsandcore/pathare folded intocore.json.records_fromand
json.Record_Readerare removed. - Refused instead of misread: an unknown tag flag or unspellable tag (
.Bad_Tag), an unsorted or overlapping
edit list (.Bad_Edit), aNumberwith no finite value inmarshal(.Non_Finite), a CSV cell that
underflows inget_float, and an edit of a CSV column name two columns share.
Command line
stury fmtformats or transcodes files, keeping every number, string, key and comment as written
(--check,--in-place).--csv,--tsv,--ndjsonand--jsoncare removed: use--fromand--to.- Parse errors at the end of the input name jq's column;
--seqreads its files as one stream;debugand
stderrlines flush in order with the output. - Windows: filter arguments are read as UTF-8,
-Ltakes an absolute path, andstrftimegives%s,%kand%l.
stury 0.0.2
Adds the CSV and TSV codec (stury:csv), the shared stury:core package, and the CLI's --from and --to.
-
stury:coreholds 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/spellspells integers and floats for every format's writer (spell_i64,spell_u64,spell_f64,
shortest_digits,is_non_finite), moved fromstury:json/encode;stury:core/bitsholds the shared bit
and UTF-8 kernels. -
coredeclaresUnknown_Fields,Unmarshal_Hook,Type_Hook(W)andHooked_Plan(W)(with
hooked_plan_initandhooked_plan_destroy);jsonandcsvalias them,
so theirType_HookandType_Planarecore.Type_Hook(Marshal_Hook)andcore.Hooked_Plan(Marshal_Hook)
with the same fields.core.Value_Classnames the classes a union's arm is picked by. -
CLI:
--from FORMATand--to FORMAT(json,jsonc,ndjson,csv,tsv) choose how the input is read
and the output written.--ndjson,--jsonc,--csvand--tsvset both halves, and an explicit--from
or--toreplaces its half, in either order. Behaviour change:--ndjsonnow prints compact, one value per
line (it left the layout alone), so--ndjson --indent Nand--ndjson --tab, which printed indented JSON, are
now a usage error (exit 2);--to ndjsonis-c. -
CLI:
--to csvand--to tsvwrite 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-headerholds 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,nullis an empty cell, and an array or object in a cell ends the run.
-r,-j,-a,-C,-c,--indent,--tab,--seqand--raw-output0are a usage error with it. A
filter that is only columns is printed in pieces, with the same output as the interpreter. -
CLI:
@tsv,@csvand@shwrite a NUL as\0, and@csv,@tsvand--to csvwrite NaN as an empty
cell, as jq does. They wrote the raw byte andnull. -
CLI: reading CSV, an empty cell with no quotes is
nulland a quoted""is""; every empty TSV cell is
null.stury --csv .writes back what it read, up to normalisation. TSV cannot tellnull
from"". -
CLI:
stury checktakes--fromand the aliases; CSV and TSV go throughcsv.validate, and a fault is reported
as in a filter run. -
CLI:
--csvand--tsvread CSV (RFC 4180) and TSV (jq's@tsvescapes). 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 asFILE:LINE:COLUMN: faultwith exit 5. A file up to 64 MiB is read whole. A larger file, a pipe
and a file under-nare 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,., andselect(F)of columns)
is printed from the cells, in pieces on every core for a whole file. Not with-R,--seq,--ndjson,--jsonc,--streamor each other. -
stury:csv, a CSV codec.validateand therecordsiterator check every byte of RFC 4180 text (quote
placement, CR before LF, UTF-8, one field count throughout).field_textreads 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.marshalwrites such a list as text thatunmarshal
reads back into equal values. -
CSV dialects.
validate,records,field_text,unmarshalandmarshaltake aDialect(delimiter,
Quoting.Nonewhere a quote is text,Escapes.Backslash, a comment byte, ragged records).TSVis
tab-separated values with backslash escapes (\t,\n,\r,\0,\\). They also take aStrictness
(.Structuralskips the UTF-8 check;unmarshalunder.Lazyjudges only the cells it reads) and
Limits.max_fields.marshalrefuses with.Unwritablea cell its dialect cannot spell so that it reads
back, and a record that would be a blank line. Thedelimiteroptions are nowdialect.delimiter. -
CSV documents and edits:
buildkeeps the field spans of a text as aDocument(row_count,column,
get_string,get_int,get_float,get_bool,get_name),findandfind_columnread one cell or one
column by path (.[3].name,.[3][1],.[].name) off the front of the text, andset,insert,remove
andsplicereturn the text with a cell, a column, a record or a span changed and every other byte kept. A
refusal is aPath_Error; the edits spell values asmarshaldoes and refuse what would not read back as the
same table. -
CSV
Plan_Opts.hooks: aType_Hookgives a type aMarshal_Hook(appends the cell's text, whichmarshal
quotes) and anUnmarshal_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, andunmarshal_check, which judges a text exactly asunmarshalwould and keeps nothing. -
CSV
marshal_append(appends to a buffer, which a refusal leaves as it was) andmarshal_to_writer(streams
in bounded chunks; addsMarshal_Error.Write_Failed).marshalis a wrapper over the same writer. -
CSV
write_recordappends one record of text cells ([]Maybe(string), nil an empty cell that reads back absent)
to a buffer in a dialect, spelling each cell asmarshaldoes. A blank line, which reads back as no record, is
.Unwritable. -
error_position,render_errorandrender_error_to_writerfor CSV, sharing JSON's implementation through
core; JSON's names and outputs are unchanged. -
Path_ErrorandPath_Error_Kind: one refusal type for the path procedures of every format, with each
format's docs listing the kinds it reports.json.Edit_Errorandjson.Edit_Error_Kindare now
json.Path_Errorandjson.Path_Error_Kind, whose kinds are renumbered and gain CSV'sUnsupported_Path,
Bad_OptionandBad_Row. -
Marshal_Error: one marshal refusal for every format;json.Encode_Errorandcsv.Marshal_Errorare its
aliases.json.Encode_Errorgains CSV'sBad_OptionandUnwritable, which JSON never reports. A path
refusal'sencodefield is aMarshal_Error.render_errorandrender_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.Defaultis the
format's default (JSON.Last, CSV.Refuse), so a zero-valued option reads as before.json.Duplicates
andcsv.Duplicatesare its aliases. JSON's is now au8. -
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 thanLimits.max_fields. JSON never reports them. -
CSV streaming and threads:
csv.records_fromreads the records of anio.Readera chunk at a time, with the
same records, offsets and fault asrecordson the whole text.csv.each_recordruns a task on pieces of a
text on aBatch_Runner's threads.csv.validatetakes a runner too and gives the same answer as without one.
Limits.max_record_bytescaps a record (Error_Kind.Limit_Record) and so bounds the windowrecords_fromholds. A
Recordcarries thesrcits fields index.Batch_Runneris defined instury:core;json.Batch_Runner
names it. -
RequestandPreparedname their type parameter$KINDS(was$Q), as the generic procedures that take
them do. Callers that writeRequest({.Path})are unaffected. -
marshalwrites an emptyjson.Digitsasnull, as it writes an emptyjson.Raw, instead of failing with
.Bad_Raw. -
render_errorof anUnmarshal_Errorends with its path (1:11: Wrong_Kind at .a.b), with…when the path
was truncated. -
unmarshal's.Unsupportedfor a,stringfield, or for two fields writing one key, names that field in the
error path. -
scanat.Structuralchecks the UTF-8 of values no path reads, asvalidatedoes: invalid UTF-8 anywhere
in the document now fails the scan. -
CLI:
halt_error/1with 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
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 (
findfor one
path's first answer, aRequestfor 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
unmarshalandmarshal: read JSON into Odin structs, slices, maps, unions andany, and write Odin
values back as JSON. - Byte-preserving edits:
set,insert,removeandsplicechange 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,fromjsonand
option JSON, where jq caps at 10000) and thestury checksubcommand (--strict-limitsholds the library's
digit and scale limits). --jsoncoutput keeps the comments of values taken unchanged from the input and drops them on values the
filter made. Use.@comment,.@comment_inlineand.@comment_footto read them as a list of texts or
null.- Large inputs are read and printed on several threads (see
host.Batch_Poolinstury:host). - Filters that recurse in tail position use constant memory, and recursion can go about a million levels deep.