JuliaCon Local Paris 2025

The primary aim of this talk is to motivate embedding formalized meaning into a Julia file's comments by exhibiting a range of assorted examples. The same principles are easily extended to other programming languages or project data in general.

For the purpose of illustration a new package will be introduced: GoLiterate. It is an extended adaptation of the well established Literate by Fredrik Ekre et al. Thanks 🌷 The handling of metadata is left to a purpose built back end named GoMeta. Later it will be shown how prospective contributors may take advantage of its modular design concept in order to easily and fully integrate their own extensions. It is hoped that this approach will eventually yield a pure Julia App serving an audience which extends beyond the Julia community.

But first, what can actually be gained from embedding formalized metadata within comments? Let's consider four, seemingly unrelated use cases which together ought to resonate with the vast majority of JuliaCon's attendees:

1. Over time a large number of Julia files can accumulate. Wouldn't it be wonderful to speedily retrieve any desired, long forgotten poignant example, powerful code snippet, insightful explanatory statement or laboriously tweaked plot related to some task at hand? Adding meaning to content can change the game. On top of that, an instrument solving this problem might prove even more invaluable when collaborating in a group sharing a repository of documents and it is also not restricted to Julia files only.

2. One might want to (inter)link a certain fragment of one file with another fragment, possibly contained in some other file. E.g.: linking an intricate piece of code to an enlightening explanation or a clarifying toy example. Occasionally it could also be handy to swap entire sections of text / code of one file with alternate versions or update them centrally if used in multiple places, depending on the circumstances.

3. Would you like to harness the power of Documenter, enjoying simplified control while sticking to pure Julia files rather than having to deal with additional markdown documents? More generally, a Julia file can serve as a source for all kinds of outputs.

4. Being able to control how individual chunks of code / text are being executed, respectively rendered, can be beneficial. E.g.: certain passages of a file might be intended for personal usage only. Marking them as such would allow automated removal before sharing. Another example is the ability to restrict execution to code blocks pertaining to a particular group only.

The defining concept of Literate consists of storing chunks of code and text together in pure Julia files. These serve as source files which can subsequently be converted into a variety of formats such as notebooks, standard markdown or even documenter markdown files. A suitable system for metadata allows exerting precise control over these format's wide ranging capabilities from within the Julia source file and provides the means to generalize Literate's core idea and more. The concept extends well beyond Julia and can be applied not only to other programming languages but to all sorts of text documents such as lectures notes or any number of scripts concerning a project, research or otherwise.

So what does the proposed schema for metadata look like?

Any line starting with #~ is considered to be a metaline i.e.: it will be processed as metadata. Contiguous metalines constitute a coherent block of metadata separating it from others. By positioning such a block just above a chunk of code or text [no vertical spacing in between] the former gets attached to the latter – similar to how docstrings get associated with Julia structures following them. For the purpose of inheritance, a hierarchy of blocks of metadata can be defined by prepending one or more # to the first metaline of a given block which works analogously to markdown's syntax for titles.

The current implementation of GoLiterate accepts standard metalines [more below] with its content consisting of key-value pairs where the keys are restricted to one word and the values may include general strings or vectors. Like this a name or title can be provided and labels can be applied. A UID is automatically generated and assigned to each block of metadata. This way a targeted search for particular sections of code or text becomes possible as well as interlinking various sections.

The execution of some tasks may be so common that they are deserving of a simplified syntax to facilitate their usage. Others may benefit or even necessitate custom tailored metadata to enable full functionality, as is the case for instructions passed to Documenter. The current schema resolves this by introducing specialized metalines. E.g.: a leading #~d instructs the parser to process the subsequent content for the usage with Documenter. Appending a ! to a metaline declaration, #~!, causes its content to be retained but not processed.

All this is readily exemplified:

# Start file.jl

#~  [Metadata Block 1]
#~

 ... code/text

##~ [Metadata Block 2]
#~!
#~
"""
    addone(x)
This is a docstring for addone().
"""
function addone(x)
    x += 1
end

 ... code/text

#~   [Metadata Block 3]
#~d jldoctest; output = false
addone(2)

# output

3

# End file.jl

Above three distinct blocks of metadata are presented. The second of which can inherit attributes from the first. While the second block is attached to a chunk and thus gets applied to it, the first block has no direct effect on any code or text chunk. Its attributes are only passed on indirectly through inheritance.

Block 3 does not inherit anything from the blocks before since it is not a sub-block / sub-section of them. However, since it contains a specialized metaline meant for Documenter, the chunk of code following it will be fenced by ```jldoctest; output = false … ``` when the output format corresponds to Documenter's markdown.

Which metadata gets invoked and how, can also be finely adjusted via function call [user input], default settings, init file etc. These methods of passing instructions can be used to conveniently and efficiently inhibit any arbitrary directives issued by the metadata expressed in the file or override them altogether; e.g.: effortlessly controlling which metadata gets displayed to prevent visual overload without editing the source file. This is achieved by permuting the precedences: ignore particular metadata and adhere to user input instead. This ability to prioritize and the hierarchical dependence between meta blocks reduces the need of lengthy, explicit written statements in the source file itself.

The modular design of GoMeta enables future contributors to easily and fully integrate their own modules by means of PAnG!: Firstly, the facilities for costume defined metadata get initiated [Plug]. Next, GoMeta must be able to parse and process [Absorb] that new type of data contained in the file and, finally, act on it [Go!].

Time permitting, this talk's various examples will demonstrate not just the above described features but many more which for the sake of brevity have been omitted from this already dense overview.

In the near future, AI will automate much of the labeling. Crucially, if this black box is confined within a formalized framework of metadata, it can become train- and tunable.