Hi HN! I'm Alex, a tech enthusiast. I'm excited to show you Jesth, a next-level human-readable data serialization format.
This project started out as a markup language for writing the docstrings of functions that would ultimately be consumed by a documentation generator. Basically the idea was to split a docstring into sections like Description and Parameters. Each section would consist of a header in square brackets and a body (lines of text between two headers).
Here's what a docstring for a sum function would look like:
This function takes in two integers a and b and returns their sum.
[parameters]
- a: First integer
- b: Second integer
[return]
Sum of a and b
The Description section in the example above is actually an anonymous section, i.e., a section with an empty header.
Meanwhile, I was thinking of a way to automate part of my dev workflow by storing in a file commands grouped into tasks such as project creation, build, testing, release, et cetera. Similarly with the markup language for my documentation generator, I would use square brackets to define the tasks. Thus, a task would consist of a header and a body which would be a list of commands to be executed sequentially.
I built this project and named it Backstage. Here is a hypothetical backstage.tasks file:
[release]
& test
& generate_doc
& git_stuff
& build
# upload to PyPI
$ twine upload --skip-existing dist/*
[git_stuff]
$ git add .
$ git commit -m {message}
$ git push origin master
The example above is illustrative only and would not work. It contains 2 sections "release" and "git_stuff". Running the "release" task from the command line is equivalent to sequentially executing the commands in the "release" section.
The documentation generator and the scripting language, despite the obvious similarity in their formats, did not share any parsing code. So, to stop repeating myself, I created a file format and its library named Jesth which stands for "Just Extract Sections Then Hack".
The library acts as an incomplete INI file parser that only hands the programmer the sections (as headers and their associated bodies which are lists of strings). No further interpretation of the data is done by the parser, allowing the programmer to unleash their creativity through useful hacks.
In its latest iteration, Jesth has matured and also includes a proper and extensively tested hack to convert a compatible section into a dictionary data structure, making Jesth my de facto preferred format for config files. I find Jesth more readable than TOML, YAML, and JSON.
Here, encoding a dictionary data structure in its own section with another section containing a prompt for ChatGPT:
[prompt]
I want you to act as a detective story writer. I will provide you with
two dictionary data structures representing the profiles of two people.
Your goal is to write a thrilling neo-noir story. My first request is:
"guess who the killer and victim is from the profiles, then build a story
that includes every detail of the profiles".
[profile]
# This section can be converted into a dictionary data structure
name = 'Jane Doe'
birthday = 2000-12-23Z10:17:37Z
photo_jpg = (bin)
VGhpcyBpcyBub3QgYSBwaG90by4uLiBCdXQgdGhhbmsgeW91
IGZvciB5b3VyIGludGVsbGVjdHVhbCBjdXJpb3NpdHkgOyk=
---
books = (dict)
romance = (list)
'Happy Place'
'Romantic Comedy'
sci-fi = (list)
'Dune'
'Neuromancer'
epitaph = (text)
According to the law of conservation of energy,
no a bit of you is gone;
you are just less orderly.
---
[profile]
name = 'John Doe'
birthday = null
books = (list)
'American Predator'
'Mindhunter: Inside the FBI's Elite Serial Crime Unit'
You can learn more by reading the project's README and playing with the demo.
Let me know what you think of this project.
Am I understanding correctly that this basically adds a type system to TOML? Have you considered calling it TypeTOML and making it a superset of TOML? (Maybe this is covered in the readme which I only skimmed.)
It would be cool if I could rename `config.toml` to `config.ttoml` and add types as I need them, similarly to how I can rename `script.js` to `script.ts` for iterative adoption of TypeScript. Although obviously this would require the consuming code to implement the Jesth (TypeTOML?:)) parsing, which would maybe defeat the point of iteratively adopting it (why bother with partial compatibility then?). Perhaps you could make it a _compatible_ superset, with types implemented using TOML comments so that existing TOML parsers can parse an (untyped) structure from a Jesth file by ignoring the comments, while Jesth can parse a typed structure from the same file.