Braq is one of two spin-offs of Jesth (https://news.ycombinator.com/item?id=35991018) which is an unorthodox data format for which I struggled to design a library with a very simple programming interface.

Jesth was supposed to divide a text document into sections, each consisting of a header and a body. A subformat was available to formally represent structured data in a section. This subformat was optional, allowing for an eclectic set of sections within the same document.

I extracted and improved the subformat in a new spin-off project named Paradict (https://news.ycombinator.com/item?id=38684724).

Braq is the other spin-off project that focuses on Jesth's main idea: just section a document and let the programmer decide what to do with each section. So a section can be a JSON string, a prompt for a chatbot, ASCII art, a note, etc.

On top of the Braq data format, we could build something else, such as a docstring format which will be consumed by a documentation generator.

This is an example of a Python function with its docstring written in a format designed on top of Braq:

  def sum(a, b):
      """
      This function returns the sum of two integers
      
      [params]
      - a: integer
      - b: integer
      
      [return]
      Sum of a and b
      
      [errors]
      - OverflowError: raised when either a or b is too big
      - IntegerError: raised when a and b aren't integers
      """
      pass

Braq is also used by Paradict for config files. This is what a config file in Paradict format might look like:

  [user]
  # no comment
  id = 42
  name = 'alex'
  birthday = 2042-12-25T16:20:59Z
  books = (dict)
        romance = (list)
            'Happy Place'
            'Romantic Comedy'
        sci_fi = (list)
            'Dune'
            'Neuromancer'

Let me know what you think about all this !