Skip to content

Release History

This page mirrors the project CHANGELOG.md. The format follows Keep a Changelog, and the project adheres to Semantic Versioning. kBars has not yet cut a 0.1.0 release; everything below is unreleased, in-development history.

Unreleased

Added

  • Conformance manifest, machine-readable error codes, and a versioned distribution. A generated conformance/manifest.json lists every fixture file with its version and case count so a runner can detect a truncated or edited suite. conformance/error-codes.json is the machine-readable companion to ERROR-CODES.md, in the same envelope shape as a fixture file. The suite's schema $ids resolve live on the Bars specification site, and the whole suite ships as a downloadable, checksummed ZIP per version. See Porting, Error Codes, and Distribution.
  • Number rendering is now ECMA-262 Number::toString canonical. {{ n }} (and any numeric interpolation) renders the shortest round-trip decimal string, using ECMA-262's fixed/exponential notation rules — the same algorithm a browser console uses — instead of each Kotlin target's native Double.toString(). See Number Rendering.
  • {{#each}} struct iteration is documented as normative insertion order. No behavior change, but now specified and tested — see Blocks.
  • kbars render --json. A machine-readable output mode restricted to a single render, emitting one sealed JSON envelope (output, error, or invalid-context) to stdout. See CLI Reference.
  • kbars conformance runs the full six-shape fixture suite, dispatched by each fixture's declared schema field, and gained --full-report[=PATH] with a documented exit-code contract. See CLI Reference.
  • Handlebars-style partials ({{> key }}). Renders a separately-loaded template in place, via a KbPartialLoader registered on the environment. See Partials.
  • Source locations on exceptions. KbParseException and KbRenderException carry a KbSourceLocation (line, column, verbatim source text, and — for partials — the full templateStack), folded into the exception message.
  • Soft-fail event listener. A KbEventListener observes soft failures during rendering — TypeMismatch, DegenerateValue, UnparseableInput, ComparisonMismatch, UnresolvedReference, and NoMatch — each carrying a source location. Custom transforms can report their own via KbTransformScope.softFail(…).
  • Environment properties (@env) and scoped variables ({{= }}). Environments carry a Map<String, KbTransformable> of properties, read via {{ @env/name }}; every environment includes a default now property. {{= @env/name = … }} and {{= @local/name = … }} bind render-global and frame-scoped variables respectively. See Environment Properties and Scoped Variables.
  • First-class date-time support. A KbTransformable.DateTime subtype plus as_date_time, parse_date_time, and format_date_time transforms, and date-time-aware overloads of plus, minus, at_least, and at_most. See Date/Time Transforms.
  • 40+ Liquid-equivalent transforms across math (abs, at_least, at_most, ceil, divided_by, floor, minus, modulo, plus, round, times), lists (compact, concat, find, find_index, first, has, join, last, map, reject, reverse, size, sort, sum, uniq, where), and strings (replace_first, replace_last, rstrip, slice, split, strip, strip_html, strip_newlines, truncate, url_decode, url_encode, url_escape, url_param_escape, and more), plus a default transform. See Transforms and its family pages.
  • New modules kbars-kxs, kbars-yamlkt, and kbars-conformance. kbars-kxs and kbars-yamlkt add KbEnvironment.from(json) / .fromYaml(yaml) convenience factories; kbars-conformance hosts the conformance fixture runners and Gradle codegen. See Usage.
  • The core template language: {{ }}/{{{ }}} interpolation with HTML escaping, comments, raw blocks, whitespace trimming; {{#if}}/{{else if}}/{{else}}, {{#unless}}, {{#each}} (list and struct, @index/@key), and {{#with}} blocks; this/./dot-notation/RFC 6901 pointer/../ identifier forms; binary expressions (||, &&, ==, !=, <, <=, >, >=) with documented equality/ordering/truthiness rules; a pipe-and-argument transform pipeline. See Usage.
  • The kbars CLI (render and conformance subcommands) and its shadowJar distribution.

Changed

  • Templates are reusable across renders, and documented as not thread-safe: a compiled KbTemplate caches its parsed AST and identifier classification, so re-rendering against a new KbEnvironment re-parses nothing.
  • CLI --context accepts YAML as a JSON fallback: JSON is tried first; YAML is attempted only when JSON parsing itself fails.
  • :kbars context model migrated to kpointer-adapter. KbEnvironment.create now accepts a KpaStruct? instead of a JsonObject?, and transforms consume KpaElement? rather than JsonElement? — the engine is no longer tied to kotlinx-serialization.

Breaking

  • Exception hierarchy: KbParseException and KbRenderException now extend KbException. Template.render throws KbRenderException (not KbParseException) for render-time hard failures. Catch KbException to handle both, or add a separate KbRenderException clause.
  • Transform builder methods renamed add/override/remove → addTransform/overrideTransform/ removeTransform (to make room for the parallel addProperty/overrideProperty/removeProperty methods), and KbEnvironment.create/fromJson/fromYaml gained a clock parameter.

Removed

  • KbEnvironment.from(json: String) removed from :kbars. Add a kbars-kxs dependency and import com.commonsware.kbars.kxs.from to keep using it.
  • RenderFixture/RenderConformanceRunner/RenderExpect/RenderConformanceResult moved out of :kbars into :kbars-conformance (package paths unchanged).
  • asInt and requireNumber removed from the public API in favor of asIntOrNull and asNumberOrNull, which don't throw on type mismatch.

See the full CHANGELOG.md for the complete, unabridged history, including internal-only entries.