Repository navigation
Releases
v0.6.1
Fixed
- An undefined optional next to one other value keeps that value's type (L376, L636-637):
a = ${?nope}42is the number42,true${?nope}the boolean, where v0.6.0 joined them as text. substitutions/039 and the suite's other single-neighbour rows. - An optional that closes a cycle is the only missing link (L660-661, L714-716):
closedis consumed so an outer optional that already found a value keeps it.b += ${?a},a += ${?b}is one order's result or the other (026, 057), not both lists empty;f = ${?a.t}xbeforea = ${?y}${?f}isf = "1x"(043); 075 is[y, y]when f is written first. When e is written first in 074, a required${e}that still closes the cycle is an error instead of a second missing optional swallowed by the outer${?f.k}(that wasf = [y]). - A self-reference in an include (
+=or a look-back) looks up the fixed-up path only, as typesafe/config does: it does not fall back to the same name at the document root, soa += 2included underkwith a roota = [1]isk.a = [2](include substitution/025, 027, 028). L1047-1050 still says try the original path too; the suite lists that reading inalso_valid. A path that is not a self-reference still falls back when an optional vanished (009, 011, 014), and a self-reference with nothing below still reads the environment variable of the name as written (L767).{ … } ${?x}resolves the object as a layer first so a self-reference inside sees it.
v0.6.0
Changed
- Python:
get_periodgives azig_hocon.Period, a named tuple ofyears,monthsanddays(p.months), where it gave a dict;relativedelta(**p._asdict())gives dateutil's. - Python:
get_durationandparse_durationraise aConfigWrongTypeExceptionnamedOverflowfor a duration past 292 years, the longest an int64 of nanoseconds holds, where they gave 292 years without a word (C'shocon_get_duration_nssaturates there, as before). - Python: the README and the package description no longer call the API pyhocon's. Only
parse_file,parse_string, the typed getters and the exception names carry over; code that uses the tree as a dict, reads lists or calls pyhocon's other methods is rewritten, as MIGRATING.md says. - Optional substitutions on a cycle resolve the same whichever field comes first, as the spec has it, where v0.5.3 dropped or kept them by the order of the lines, and in two cases lost a value:
b.c += ${y},b.c += 2,y = [1, ${?b}]isb.c = [[1], 2]again, andf = x${?a},f = { z = 3 },a = ${?f}keepsa, since text under an object is hidden and never evaluated, as a list is. An include inside an object concatenated with an optional,k = { include "x" } ${?y}, no longer reports a cycle. Found by a bug hunt on v0.5.3. - Four regressions in that change, found by a bug hunt on it, are fixed. A field written twice and reached again from inside a look-back,
d { z = ${?a.k} },d.z += ${?c},a : [],a += ${f},f = ${d}, crashed withreached unreachable codeand resolves again, as typesafe/config has it; an undefined${b}in such a field, a crash already in v0.5.3, is theUnresolvederror.f += ${?b},b = x${?f},b += 1dropped b's text and gaveb = [1], and is the error+=onto text is, whichever line comes first.e = [${?f.k}y],f = ${?e}${e}ande.k : ${?b},b.k { k = ${?e}, k += ${?d} }resolve the same in either order: an optional found to lead back to its own field stays nonexistent when it is met again. Ten new conformance cases, all passing. d.z += 5reached again through a field that copiesd,d { z = ${?a.k} },a : [],a += ${d}, appended 5 twice,[5, 5], whendwas written beforea, while the copy inaheld[5]; it is[5]in every order, as the spec has it.
Added
hocon --env-file=<file>, on every command andcheck --schematoo: theKEY=valuelines of a file over the environment, a later file over an earlier one, over none with--env=none; the lineszig-hocon-migrate --env-filereads.- Python:
zig_hocon.__version__, the version the package was built as. - Python:
zig_hocon.parse_intandzig_hocon.parse_boolread a number and a boolean asget_int,get_booland a Zig struct do, for a model's validator: a lax pydantic model takes"08"as 8 and"True", which the Zig side of the same application refuses. - Python:
zig_hocon.parse_period("3 months")gives whatget_perioddoes, for a model's validator, besideparse_durationandparse_bytes. - The CLI is fuzzed on every pull request and branch push (
.github/workflows/fuzz.yml):tools/fuzz/fuzz.py --no-java --fail-on-crash, a crash or a hang fails the run. A pull request's wheels areX.Y.Z+g<commit>, which PyPI refuses; CONTRIBUTING.md says what a patch and a minor release may change. - Python:
pip install zig-hoconputs thehoconcommand line tool of its platform on the path, the same as a release's, withget,diffandcheck; onlycheck --schema, which builds a Zig program and needs zig, is left out. - Python:
zig-hocon-migrate conf/(pip installs it;python -m zig_hocon migrateis the same) reads each config with pyhocon and with zig-hocon, with the same environment, and shows where they differ as the config's tree: another type a getter reads the same, another value, or one of them failing. A directory is its entry points; it exits 1 when anything differs, for CI, and--jsongives the tree as JSON.--fallback reference.confreads each config over a reference asconf.with_fallback(reference)in a loader does,--gettersmakes a value a getter reads the same no difference,--accept PATHmarks a reviewed difference as no difference,--resolve-eachreads as a loader that resolves each file before the merge, and--before mainhas pyhocon read the configs as they are onmainand zig-hocon as they are now, so the run can gate CI. - Python: MIGRATING.md says that
x += [3, 4]appends the list as one element, by the spec, where pyhocon extends the list; it said+=reads the same.
Fixed
- Python:
parse_duration,parse_bytesand the otherparse_*helpers given no text or number (True, a list) raise an error that is aValueErroras well as theTypeErrorit was, so a pydantic validator reports it as the field's error instead of letting a bareTypeErrorthrough; anOverflowsays what it was given, notv. Diagnostics.rendernames the file when the file a parse was given cannot be read,prod.conf: error: FileNotFound, where it printederror: FileNotFoundalone; the new fieldDiagnostics.fileholds it.d { z = ${?a.k} },d.z += 5,a += ${d}was aSubstitutionCyclewhendcame beforea, and{d: {z: [5]}, a: [{z: [5]}]}in the other orders: the${?a.k}that leads back tod.zis nonexistent (spec L716) in every order now, as typesafe/config reads it. v0.5.3 had it too; two conformance cases more, 588 in all.- Python: a getter that cannot read a value notes what it read, which a traceback prints under the message (Python 3.11+):
found '08', where a${…}from the environment showed only its name. - Python:
copy.copyandcopy.deepcopyof aConfigTreefailed with aTypeErroron the library's handle, and an error from the handle's cleanup; a tree is read only, so a copy is now the tree itself. - Python:
help(), pydoc and an IDE showed the whole process environment, secrets too, in the signature ofConfigFactory.parse_fileandparse_string, whose defaultenvwasos.environitself. The default is now namedos.environand reads it at the call, as before. - A NUL or another control character in unquoted text was written back by
to_hocon/hocon --hoconas it was, and a NUL ended the text for C and Python:motd = hello<NUL>worldlost every key after it. Such text is written quoted now, the character escaped ("hello\u0000world"). - A parse through libhocon (C, Python) sets SIGIO and SIGPIPE only while it fetches an
http(s)include, which needs them, and puts back the handlers from before when the last such parse ends: a handler the program set, Python'ssignal.signal(SIGIO, …)among them, stays its own. - A deep document on a thread with little stack, a Python thread or one of musl's 128 KiB, ended the process with SIGBUS or SIGSEGV before the limit of 500 levels: libhocon parses and writes on a thread of its own with 16 MiB of stack, so a deeper document is
TooDeepon any thread, and one below the limit is read. - An include whose file cannot be read reports why:
include url("http://…")with a host past 255 bytes no longer aborts the process (NameTooLong),HTTP://is fetched likehttp://, a path through a file (x.conf/y.conf) is a missing include and so ignored, and a symlink to itself isSymLinkLoop, not an include cycle that is not there. - A value concatenating many substitutions,
a = ${x} ${x} …, resolves in memory linear in its length: 16 000 one-element lists took 3.9 GB and now take 18 MB, 32 000 strings 2.95 GB and now 24 MB.
v0.5.3
Changed
- A value that begins with a digit but is no number is text again, as the spec has it:
host = 127.0.0.1,1.2.3, a UUID and01are the strings they were written as, no longer aBadNumbererror, so an IP address needs no quotes. The number JSON reads at the start is followed by text, as10.0baris; the spec's own1.2.3, a path in a key, is written the same way in a value. So is a value that begins with-and no number:-foo,-Xmx2g,--verbose, and the-inMonty Python - Holy Grail, no longer aHyphenIsNotAJsonNumbererror. So are-.5and-.33e1, which JSON has no number for, as.5already was. A+outside a number,1+2or-.33e+1, stays an error. Seven new conformance cases, eight rows rewritten, all 476 pass.
Added
- Twelve conformance cases from bug reports in lightbend/config and ekrich/sconfig where the spec has the answer: typesafe/config fails inside
${a} { … }, turns integers past 2^63 into strings and accepts\u+041; pyhocon loses+=across an include and the text of a substituted number. zig-hocon passes all 469. - Eight conformance cases found by fuzzing zig-hocon against typesafe/config, where the spec has the answer: typesafe/config rejects
a { m = 2 } { n = 1 }and3+=[], loses the first+=afterc = nulland keeps the number in[${?x}10]. zig-hocon passes all 490. - The conformance suite has 552 cases: 22 more from fuzzing that zig-hocon already passed, and its harness no longer takes
truefor1or splits an answer at U+0085. docs/resolver.md draws how substitutions resolve.
Fixed
- An object after a substitution,
top = ${x} { … }, is a merge, the same astop = ${x}andtop { … }written as two fields. A+=inside it appends to the list${x}gives (top = ${x} { arr += four }was[four], is[one, four]), a self-reference looks back at it, and${top.n}inside it sees the merged object instead of reporting a cycle. Eight new conformance cases pin it. - Layers of a key are merged before they are resolved, as the spec has it: in
p : { a : ${y} },p : ${x}withx.aset,${y}is hidden and no longer evaluated (it was an error), and a reference in the earlier object sees the final value. Three more conformance cases, all 457 pass. - A field that refers to itself with nothing before it reads the environment variable of its own name, as the spec has it:
HOME : ${HOME}is the variableHOME, where it wasUnresolved, andHOME : ${?HOME}creates the field instead of dropping it, as pyhocon does. A value set earlier still wins, andHOME += xwithHOMEset is now an error:+=isHOME = ${?HOME} [x], text and a list. Two new conformance cases, all 478 pass. - A NUL byte inside a file is a character, as the spec has it, no longer the end of the file. In a comment it dropped everything below without a word:
a = 1 # note<NUL>, thenb = 2, read as{a: 1}, and a file saved as UTF-16 without a byte order mark read as{}, where it is now an error. In unquoted and triple-quoted text the NUL is kept (a = x<NUL>ywas an error); in a quoted string it is an error, as any control character is. Four new conformance cases, all 482 pass. - A comma after a braced root,
{ a = 1 },or[1, 2],, is an error now, as the spec and typesafe/config have it; it was accepted. Two new conformance cases, all 492 pass. a = nullthena { … }clears whataheld before also when the file is included or the object merges with an earlier one:a { x = 1 }and theninclude "over.conf"with those two lines give{a: {…}}withoutx, as typesafe/config has it; thexwas kept. Four new conformance cases, all 496 pass.- An optional substitution on a cycle finds nothing also when the cycle runs on through other fields:
v { x = ${?r} }withr = ${v}givesv = {}andr = {}, as typesafe/config has it; it was a SubstitutionCycle. - A substitution path through an alias resolves only what it reaches:
a = ${p}withp = { r = ${a.q} }readsp.q, as typesafe/config does; it was a SubstitutionCycle. a = ${p},p = 1,p = ${a}xresolves toa = 1,p = "1x"in any order of the lines, as typesafe/config has it: the cycle breaks wherepcan look back. Withafirst it was a SubstitutionCycle.- A field that looks back and refers to the object it is in sees that object with the field at its earlier value:
o { a = [], a += ${o} }iso = {a: [{a: []}]}, as typesafe/config has it; it was a SubstitutionCycle. Four new conformance cases, all 500 pass. - A word that begins with a number holding a
+in its exponent and goes on as text is that text, as10.0baris:1e+5.xis"1e+5.x"and1e+5.5 = 1is the path1e+5,5, where both were aBadNumbererror. A+after that number,1e+5e+5, is still an error. HOCON written out quotes such a word, for typesafe/config and pyhocon, which reject it bare. Six new conformance cases, all 506 pass. - An optional substitution that leads back to the field it stands in is nonexistent, whichever field is resolved first, as the spec has it:
f = ${?a.t}x,a = ${?y}${?f}givesf = "x"in either order of the lines, ando = ${a.n}witha { n = { h = 0 } ${?a} }givesothe one valuea.nhas, where it was{h: 0, n: {h: 0}}.d = yes${?c},c = ${d}ande += ${?c},c = ${e}resolve instead of reporting a cycle whendorecomes first.o = ${a.n}witha { n = ${?a} }is now an error:a.nis never created, whereowas{}. - Cycles typesafe/config breaks are broken: a path into a field that refers back to itself looks back (
d { a = ${i.b} },i.b = 7,i = ${d}), and so does an alias in a list (a = [${p}],p = 1,p = ${a}) or written twice, and a look-back inside a list element (a = [{ c = 2, c = ${a} }]). What an object or a list resolves to inside such a look-back is its value. A field that refers to the object it is in,v { x = ${v} }, stays an error, as the spec names it unbreakable. - A concatenation with a list in it under an object is hidden and never evaluated, as the spec has it:
c = [1] ${x},c = { a = 1 }is{a: 1}, where it was an error. Seventeen new conformance cases, all 523 pass. +=and an include inside an object in a list work from that object, as the spec has it:a = [{ b = [1], b += 2 }]is[{b: [1, 2]}], where the earlierbwas not seen and it was[{b: [2]}], and+=onto a value there that is no list is an error, as anywhere. A file included into a list element looks its substitutions up in that element first, then at the document root (a = [{ include "child.conf" }], childx = ${y},y = 1, was an error or took a rooty). Five new conformance cases, all 528 pass.include url("file:///…/inc")loads exactly that file, as the spec has it for every URL: with onlyinc.confbeside it, it foundinc.conf, as a basename does. The conformance suite can now name an absolutefile:URL in a case (@CASE_DIR@), and has its first two. All 530 pass.
v0.5.2
The conformance suite has no open question left: the spec settles the last one, url() without a scheme, as an error (lightbend/config#887), and zig-hocon passes all 446 tests.
Added
- A conformance case for a value that begins with a digit but is no number,
a = 1.2.3: an error by the spec.python/MIGRATING.mdsays what it means for a pyhocon user: an IP address needs quotes.
v0.5.1
The conformance suite settles two of its three open questions: 444 of the 445 tests pass, up from 442. The last one, url() without a scheme, waits for the spec (lightbend/config#887).
Added
python/BENCHMARK.md: every Python HOCON library measured against the spec and timed on 1 KB, 1 MB and 10 MB files, with the best Rust crate and typesafe/config beside them. zig-hocon is the fastest Python library, from 2× the next one at 1 KB to 17× at 10 MB.- The conformance report measures py.hocon, hocon2, pulse-pyhocon and rs.hocon beside typesafe/config and pyhocon;
conformance/README.mdlists the parsers left out and why. - A conformance case can accept more than one output,
also_validin its sidecar, where the spec allows several answers. The first is two fields that substitute each other: both 1, both 2 or an error.
Changed
include url("x.conf"), a URL with no scheme, fails withInvalidUrlinstead ofUnsupportedInclude, which stays for a scheme zig-hocon cannot follow, such asftp:. In C it is stillHOCON_ERR_PARSE, in Python still aConfigParseException; only the name changes.- A newline between a key and its
{is an ordinary conformance case, no longer an open question: every parser in the report accepts it.
Fixed
conformance/run.sh --textlists open questions apart from failures. They showed as failing, with the expected and the actual output the same.- The conformance report page shows its scores and verdicts without JavaScript, so they show on a phone too.
v0.5.0
A timeout for http(s) includes from C and Python.
Added
- An http(s) include from C and Python gives up after 30 s, or the time you give:
http_timeout_msinhocon_options,http_timeout=(atimedeltaor seconds) onparse_fileandparse_string. It fails withIncludeTimeout; until now a server that never answered held the parse for ever.
Changed
hocon_optionsstarts withsize_t size, which you set tosizeof(hocon_options): the library reads the fields that fit in it and takes the defaults for the rest, so a program built against this header keeps working with a later library that adds fields. Options filled in order,{HOCON_ENV_MAP, vars, true, NULL}, become{sizeof(hocon_options), HOCON_ENV_MAP, vars, true, NULL, 0}; a size of 0 isHOCON_ERR_OTHER. Rebuild against the newhocon.h.- A parse in libhocon sets SIGIO and SIGPIPE to a handler that does nothing, and leaves them so: it wakes its own fetch thread with SIGIO when the time is up.
v0.4.0
HOCON from C and Python, on Linux, macOS and Windows.
Added
- libhocon, the C API in
include/hocon.h: parse a file or a string, typed getters by path, a subtree as JSON or HOCON, errors with file, line, column and caret. A zip per platform on the release. - The
zig-hoconPython package on libhocon: pyhocon's API, typed, safe to share between threads. Wheels for macOS, Linux (glibc and musl) and Windows on every Python from 3.10. ParseOptions.resolve = falsekeeps every${…}in the tree, forhocon.stringifyto write back.ParseOptions.ignore_unknown_fields = falsemakes a key the struct has no field forerror.UnknownField.hocon.parseFromSliceInDirLeakyreads text whose includes are relative to a directory;hocon.parseFromValueconverts ahocon.Valueyou already have into your struct.
Fixed
- A number read from text into a struct follows the JSON rules:
0x10,1_000andnanare errors, as in the spec and typesafe/config.
How much of the code in src/ is written by hand, the rest with AI, counted with git blame over the lines that are not empty, by who wrote the commit each line comes from; moved code stays its author's. The tests are left out: most of them are written with AI.
| share | |
|---|---|
| Tokenizer | 73 % |
| AST | 51 % |
| Value | 15 % |
| Config | 19 % |
| API and CLI | 2 % |
all of src/ |
22 % of 7545 lines |
| conformance to the spec | 99 % (442 of 445 tests) |
v0.3.0
The rest of the spec, durations and sizes, and three new commands.
Added
hocon.Duration,hocon.Periodandhocon.Size, read from30s,3 months,512MiBin any unit the spec lists.- Objects with numeric keys (
{ "0": a, "1": b }) read as lists, into a slice or an array. hocon getprints one value,hocon checkreads files, with--schemainto your own struct, andhocon diffcompares two files as they resolve.
Changed
- Nesting deeper than 500, or a chain of 500 substitutions, is
error.TooDeepinstead of a stack overflow. - An included
.propertiesfile has to be UTF-8.
Fixed
442 of the 445 tests in the conformance suite pass, up from 437.
- The file
--env=keepwrites reads back to the same result when a substitution comes from an include inside a block, and a+=still waiting on the environment is written as+=. - A lone surrogate in a quoted string (
"\ud83d") is kept and written back as it was read. - A
+in a run that is no number is an error. - An optional substitution that closes a cycle finds nothing.
- A key written many times merges in linear time.
How much of the code in src/ is written by hand, the rest with AI, counted with git blame over the lines that are not empty, by who wrote the commit each line comes from; moved code stays its author's. The tests are left out: most of them are written with AI.
| share | |
|---|---|
| Tokenizer | 73 % |
| AST | 51 % |
| Value | 15 % |
| Config | 20 % |
| API and CLI | 3 % |
all of src/ |
24 % of 6880 lines |
| conformance to the spec | 99 % (442 of 445 tests) |
v0.2.0
Includes, errors with a place, environment variables and HOCON out.
Added
- Includes: files,
file(),required()and http(s) URLs, as.conf,.jsonor.properties, read throughhocon.parseFromFileandparseFromFileLeaky. A slow server iserror.IncludeTimeoutafterParseOptions.http_timeout(30 s). - Errors with a place:
ParseOptions.diagnosticsgets the file, line, column and the line itself, andrenderprints it with a caret, as the zig compiler does. A value of the wrong type names its path, what the type wanted and where the value is written. - A key written again over a substitution of itself (
path = ${path} ":/opt"), and+=. - Environment variables: a
${…}the document does not answer reads the variable of the same name,${X[]}a list fromX_0,X_1, … (ParseOptions.env)..keepleaves them for later. hocon.stringifyandstringifyAllocwrite any value as HOCON, an unresolved one too, which is the one file to deploy.hocon.parsePathturns a path given as text into keys.--env=process|none|keepon the command line.
Changed
parseFromSliceandparseFromSliceLeakytakeParseOptionsas their last argument;.{}does what they did before.hocon <file>prints HOCON;--jsongives the JSON it printed before.- A value that starts like a number has to be a JSON number:
01and-alone are errors, as in JSON. - Input over 64 MiB is
error.StreamTooLong, a file that is not UTF-8error.InvalidUtf8at the first bad byte.
Fixed
437 of the 445 tests in the conformance suite pass, up from 307.
- Every whitespace character the spec lists separates, a lone
\rincluded;//right after unquoted text starts a comment. - A comma separates once; array elements on one line concatenate; a document that starts with
[is a list. - Unquoted text may start with
_,%or a letter outside ASCII;1e+5is a number; an escaped backslash before the closing quote ends the string. ${.a}is an error, as the key.ais.
How much of the code in src/ is written by hand, the rest with AI, counted with git blame over the lines that are not empty, by who wrote the commit each line comes from; moved code stays its author's. The tests are left out: most of them are written with AI.
| share | |
|---|---|
| Tokenizer | 74 % |
| AST | 58 % |
| Value | 19 % |
| Config | 54 % |
| API and CLI | 5 % |
all of src/ |
33 % of 5342 lines |
| conformance to the spec | 98 % (437 of 445 tests) |
v0.1.0
The first release that works end to end: HOCON text into your own Zig struct, shaped after std.json.
Added
hocon.parseFromSlice(T, gpa, source)returnsParsed(T), an arena that owns the value and is freed by onedeinit;parseFromSliceLeakytakes your arena and returns the plain value.- Into structs with nested structs, slices, optionals, enums and field defaults; a value converts as the spec's automatic type conversions say.
hocon.Value, the tree itself, whichstd.json.Stringifyprints as JSON.- The syntax: JSON as it is, comments (
#and//), root braces left out,=or:or nothing before{, newlines for commas, unquoted and multi-line strings. - Paths as keys (
a.b.c = 1), a key written again merging objects, and value concatenation of strings, lists and objects. - Substitutions
${a.b}and${?a.b}, resolved against the whole document. - The
hoconcommand prints a file as JSON and exits 1 with the reason when it does not parse or resolve.
307 of the 445 tests in the conformance suite pass. Not yet: includes, +=, and a key that refers to its own earlier value.
How much of the code in src/ is written by hand, the rest with AI, counted with git blame over the lines that are not empty, by who wrote the commit each line comes from; moved code stays its author's. The tests are left out: most of them are written with AI.
| share | |
|---|---|
| Tokenizer | 100 % |
| AST | 99 % |
| Value | 80 % |
| Config | 100 % |
| API and CLI | 66 % |
all of src/ |
92 % of 2206 lines |
| conformance to the spec | 69 % (307 of 445 tests) |