Astrologue-Website/developer/invercargill-json/index.html

<!doctype html>
<html lang="en-nz">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Invercargill-Json — Astrologue Developer</title>
  <meta name="description" content="JSON support for Invercargill: documents become Enumerable collections that query and transform like any other sequence — JsonElement, JsonArray, JsonObject and JSON Lines streams. Free software, LGPL-3.0-or-later.">
  <meta name="color-scheme" content="light dark">
  <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
  <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Ccircle cx='32' cy='32' r='27' fill='none' stroke='%23a8801f' stroke-width='4'/%3E%3Cpath d='M32 8l6 18 18 6-18 6-6 18-6-18-18-6 18-6z' fill='%23a8801f'/%3E%3Ccircle cx='32' cy='32' r='4' fill='%23003078'/%3E%3C/svg%3E">
  <meta property="og:title" content="Invercargill-Json — Astrologue Developer">
  <meta property="og:description" content="JSON support for Invercargill: documents become Enumerable collections that query and transform like any other sequence.">
  <meta property="og:type" content="website">
  <link rel="stylesheet" href="../../assets/css/style.css">
</head>
<body>
  <a class="skip-link" href="#main">Skip to content</a>

  <header class="masthead">
    <div class="container masthead__inner">
      <a class="brand" href="../../">
        <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
        <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
      </a>
      <nav class="site-nav" aria-label="Primary">
        <ul class="site-nav__list">
          <li><a href="../../">Home</a></li>
          <li><a href="../../#news">News</a></li>
          <li><a href="../../#download">Download</a></li>
          <li><a href="../" aria-current="page">Developer</a></li>
          <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
        </ul>
      </nav>
    </div>
  </header>

  <main id="main">

    <nav class="breadcrumb" aria-label="Breadcrumb">
      <div class="container">
        <ol>
          <li><a href="../../">Astrologue</a></li>
          <li><a href="../">Developer</a></li>
          <li aria-current="page">Invercargill-Json</li>
        </ol>
      </div>
    </nav>

    <section class="docs-header">
      <div class="container">
        <p class="kicker"><span>Foundation · Documents as sequences</span></p>
        <h1>Invercargill-Json</h1>
        <p class="lede">JSON support for Invercargill: a document becomes an Enumerable collection that queries and transforms like any other sequence. Json-glib does the parsing; this library gives its nodes the interface the rest of the stack speaks.</p>
        <dl class="docs-facts">
          <div><dt>Version</dt> <dd><code>0.1</code></dd></div>
          <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
          <div><dt>Package</dt> <dd><code>usm&nbsp;install&nbsp;invercargill-json</code></dd></div>
          <div><dt>Language</dt> <dd>Vala</dd></div>
        </dl>
      </div>
    </section>

    <section class="band band--plain" id="docs">
      <div class="container docs-layout">

        <nav class="docs-toc" aria-label="On this page">
          <h2>On this page</h2>
          <ul>
            <li><a href="#overview">Overview</a></li>
            <li><a href="#features">Features</a></li>
            <li><a href="#installation">Installation</a></li>
            <li><a href="#usage">Usage &amp; documentation</a></li>
            <li><a href="#package">Package &amp; source</a></li>
          </ul>
        </nav>

        <div class="docs-prose">

          <header class="section-head" id="overview">
            <p class="kicker"><span>Overview</span></p>
            <h2>A compact companion</h2>
          </header>
          <p>Invercargill-Json provides JSON functionality to Invercargill — that single sentence is the library's whole README, and it is an honest measure of the project's scope. This is a compact companion library, not an exercise in surface area: five small source files that wrap json-glib's nodes in Invercargill types so a JSON document answers the same queries as a database result or a settings file.</p>
          <p>Its worth shows up in the stack above it: Statum's signed state slots serialise through it, and the fixes it carries — integers serialising as JSON numbers rather than boxed strings, large <code>int64</code> values round-tripping without precision loss — were found in exactly that downstream path.</p>

          <header class="section-head" id="features">
            <p class="kicker"><span>Features</span></p>
            <h2>What it hands you</h2>
          </header>
          <ul class="docs-features">
            <li><strong>JsonElement.</strong> One element type for any node, parsed from a string, a file or a stream — including an async stream variant.</li>
            <li><strong>Typed access.</strong> <code>assert_as&lt;T&gt;</code> and <code>try_get_as&lt;T&gt;</code> turn nodes into the Vala types you actually wanted.</li>
            <li><strong>Queryable documents.</strong> Arrays and objects are Enumerable: filter, project, aggregate and order a document with the same calls as any sequence.</li>
            <li><strong>JsonElements promotions.</strong> <code>as_strings()</code>, <code>as_integers()</code>, <code>as_doubles()</code>, <code>as_bools()</code>, <code>as_objects()</code>, <code>as_property_groups()</code> project a node sequence straight onto typed values.</li>
            <li><strong>JSON Lines.</strong> Stream <code>.jsonl</code> in and out through <code>JsonlInputStream</code> and <code>JsonlOutputStream</code>, one element at a time.</li>
            <li><strong>Objects as Properties.</strong> A <code>JsonObject</code> is an associative Enumerable of key-value pairs, so property mapping works on documents too.</li>
          </ul>

          <header class="section-head" id="installation">
            <p class="kicker"><span>Installation</span></p>
            <h2>Getting the library</h2>
          </header>
          <p>Install the foundation first, then this companion:</p>
          <figure class="code-plate">
            <pre><code>usm install invercargill
usm install invercargill-json</code></pre>
            <figcaption>USM resolves the <code>invercargill-1</code> and <code>json-glib</code> dependencies itself.</figcaption>
          </figure>
          <p>From source:</p>
          <figure class="code-plate">
            <pre><code>git clone &lt;the Invercargill-Json repository&gt;
cd Invercargill-Json
meson setup build
ninja -C build
ninja -C build install</code></pre>
            <figcaption>Meson and ninja are the only build tools needed.</figcaption>
          </figure>
          <figure class="code-plate">
            <pre><code>valac --pkg invercargill-json my-program.vala</code></pre>
            <figcaption>The binding pulls in its <code>.deps</code> chain automatically.</figcaption>
          </figure>

          <header class="section-head" id="usage">
            <p class="kicker"><span>Usage &amp; documentation</span></p>
            <h2>Reading documents as sequences</h2>
          </header>
          <p>Parse, assert the shape, project to types — the library's own tests read like documentation:</p>
          <figure class="code-plate">
            <pre><code>using Invercargill;
using InvercargillJson;

var json_str = """[
    "Glengarry",
    "Gladstone",
    "Strathern",
    "Richmond",
    "Georgetown"
]""";

var suburbs = new JsonElement.from_string(json_str)
    .assert_as&lt;JsonArray&gt;()
    .as_strings()
    .to_array();
// suburbs.length == 5, suburbs[0] == "Glengarry"</code></pre>
            <figcaption>From <code>src/tests/Integration/Json.vala</code> — a document becomes a typed Vala array in four calls.</figcaption>
          </figure>
          <p>Objects read by key, with nullable getters that tell you what is actually there:</p>
          <figure class="code-plate">
            <pre><code>var obj = new JsonElement.from_string("""
    { "name": "Aurora", "age": 27, "active": true }
""").assert_as&lt;JsonObject&gt;();

string? name    = obj.get_string("name");
int64?  age     = obj.get_integer("age");
bool?   active  = obj.get_bool("active");
double? height  = obj.get_double("height");   // null — absent keys answer null</code></pre>
            <figcaption>From <code>src/lib/Object.vala</code> — <code>get_array</code>, <code>get_object</code>, <code>try_get</code> and <code>has</code> complete the set.</figcaption>
          </figure>
          <p>Because documents are Enumerables, the whole modifier vocabulary applies. Select the fields you want from every record in an array of objects; filter objects on their contents; hand the result to anything that consumes a sequence.</p>
          <p>Scalars and whole classes map onto the same representation:</p>
          <figure class="code-plate">
            <pre><code>// A GObject property becomes a JSON number, faithfully
var v = Value(typeof(int64));
v.set_int64(99);
var j = new JsonElement.from_element(new ValueElement(v));
assert(j.stringify() == "99");</code></pre>
            <figcaption>From <code>src/tests/Integration/FromElement.vala</code> — the regression tests for scalar dispatch, including <code>int64</code> precision at 2⁵³&nbsp;+&nbsp;1.</figcaption>
          </figure>
          <p>For line-delimited streams — logs, exports, model output — the JSON Lines classes keep memory flat:</p>
          <figure class="code-plate">
            <pre><code>// Reading: one element at a time, or as a lazy Enumerable
var input = new JsonlInputStream.from_file(File.new_for_path("events.jsonl"));
JsonElement? element = input.read_next();

// Writing
var output = new JsonlOutputStream(stream);
output.write(element);
output.write_all(elements);</code></pre>
            <figcaption>From <code>src/lib/Jsonl.vala</code>.</figcaption>
          </figure>

          <header class="section-head" id="package">
            <p class="kicker"><span>Package &amp; source</span></p>
            <h2>The ledger</h2>
          </header>
          <dl class="docs-package">
            <div><dt>Version</dt><dd><code>0.1</code> (from <code>MANIFEST.usm</code>)</dd></div>
            <div><dt>Licence</dt><dd>LGPL-3.0-or-later — free to run, study, share and improve; the LGPL keeps it free to link from any program.</dd></div>
            <div><dt>Package</dt><dd><code>usm install invercargill-json</code></dd></div>
            <div><dt>Provides</dt><dd><code>libinvercargill-json.so</code>, <code>invercargill-json.h</code>, <code>invercargill-json.vapi</code> + <code>.deps</code>, <code>invercargill_json-1.0.gir</code>, <code>invercargill_json-1.0.typelib</code>, <code>invercargill-json.pc</code></dd></div>
            <div><dt>Needs at runtime</dt><dd>GLib, GObject, Gio, json-glib, and <code>libinvercargill-1.so</code> — its reason for being.</dd></div>
            <div><dt>Source</dt><dd>The repository <code>Tilo15/Invercargill-Json</code> on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.</dd></div>
          </dl>

          <nav class="docs-siblings" aria-label="Neighbours in the catalogue">
            <p>Its neighbours:</p>
            <ul>
              <li><a href="../invercargill/">Invercargill</a></li>
              <li><a href="../inversion/">Inversion</a></li>
              <li><a href="../statum/">Statum</a></li>
            </ul>
          </nav>

          <nav class="docs-pager" aria-label="Project pages">
            <a class="docs-pager__link docs-pager__link--prev" href="../invercargill/">
              <span>Previous</span>
              <strong>Invercargill</strong>
            </a>
            <p class="docs-pager__up"><a href="../">All eleven</a></p>
            <a class="docs-pager__link docs-pager__link--next" href="../inversion/">
              <span>Next in the catalogue</span>
              <strong>Inversion</strong>
            </a>
          </nav>

        </div>
      </div>
    </section>

  </main>

  <footer class="site-footer">
    <div class="container">
      <div class="footer-grid">
        <div class="foot-brand">
          <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
          <p>An operating system for change — kept for self sufficiency, resilience, and software freedom, so regular people can hold the power of general purpose computers in their own hands.</p>
        </div>
        <nav aria-label="The four freedoms">
          <p class="foot-title">The Four Freedoms</p>
          <ol class="freedoms">
            <li><strong>Run</strong> the software as you wish, for any purpose.</li>
            <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
            <li><strong>Share</strong> copies so you can help others.</li>
            <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
          </ol>
        </nav>
        <nav aria-label="Site">
          <p class="foot-title">Site</p>
          <ul class="foot-list">
            <li><a href="../../">Home</a></li>
            <li><a href="../../#news">News</a></li>
            <li><a href="../../#download">Download</a></li>
            <li><a href="../">Developer</a></li>
          </ul>
        </nav>
      </div>
      <p class="colophon">Set in Cinzel and EB Garamond (SIL Open Font License). Astrologue is free software, licensed GPL-3.0-or-later: take it, tend it, pass it on. The libraries are LGPL-3.0-or-later, so they remain free to link.</p>
    </div>
  </footer>
</body>
</html>