#+title: Laundry: Org mode for Racket
# An organized racket?
# How about money laundering?
# Laundry list!
# laundry-mode

An attempt to specify a formal grammar for [[https://orgmode.org/worg/dev/org-syntax.html][Org syntax]].

The grammars lives in [[file:./laundry/grammar/][laundry/grammar]]. The top level is in [[./laundry/grammar/org.rkt][org.rkt]]. \\
The grammars are implemented using Racket's [[https://docs.racket-lang.org/brag/#%28part._.The_language%29][#lang brag]]. \\
The details of the implementation are in the comments.

For an overview of the approach see [[file:./docs/overview.org]].
* Getting started
Install [[https://download.racket-lang.org/][Racket]] for your platform.

Laundry is available from the Racket package catalog and can be installed via
#+begin_src bash
raco pkg install org laundry
#+end_src

To install the development version you can run the
following from the location of this readme.
#+begin_src bash
raco pkg install laundry/ laundry-test/ org/ org-tools/
#+end_src

Once everything is installed you can run the tests by invoking the
following in the directory of this readme.
#+begin_src bash
raco test laundry laundry-test org org-tools
#+end_src

You can also parse individual Org files using [[file:./laundry-test/cli.rkt]].
#+begin_src bash :results drawer
laundry-test/cli.rkt docs/thoughts.org laundry-test/test.org
#+end_src
* Status
Laundry can parse most of Org syntax, though there are still issues
with the correctness of the parse in a number of cases.

In particular there are a number of edge cases in the interaction
between the syntax for various Org objects that have not been
resolved.
* Objectives
The primary objective of this work is to provide a reference grammar
and implementation that can be used to test other implementations of
org mode. The elisp implementation has inconsistent behavior in a
number of critical areas, such as the parsing of headline tags. A
reference grammar will help to elucidate the issues.

This work was originally inspired by a desire to regularize the
behavior of Org babel, however the lack of a consistent reference for
the grammar of Org as a whole turned out to be a significant stumbling
block due to the fact that Org babel interacts with nearly every
aspect of Org. Therefore work to standardize Org syntax became a
priority.

The long term goal of this work is to provide a reference that can be
used to standardize Org syntax and behavior and to specify various
levels of compliance for an implementation of Org mode.
* Performance
Until recently the performance of the parser was exceptionally bad due
to some hidden quadratic behavior in Racket =parser-tools=. To work
around this issue the tokenizer has been made more complex, so sometimes
you may find that there is an opaque token appearing in the grammar
that obscures some of the details. In most cases the full grammar
is retained, but unless it has been tested with the less complex and
slower tokenizer the full grammar may be incorrect.
* A note on terminology
The current terminology used in the [[file:./laundry/grammar][grammars]] matches the terminology
used in [[https://orgmode.org/worg/dev/org-syntax.html][Org syntax]]. This is expected to change so that, for example
terms such as =headline= will be renamed to =heading=. This has not
been done to simplify comparison to the existing Org syntax document
during early development. As such the names of the elements of the
parse tree should not be considered to be stable.
* Debugging
Change ~[debug #f]~ on line 32 of =br-parser-tools-lib= [[file:~/.racket/8.2/pkgs/br-parser-tools-lib/br-parser-tools/yacc.rkt::32][yacc.rkt]] to
point to a file (e.g. ~[debug "/tmp/parser-debug-output.rktd"]~) and then
when the parser fails you can check that file for a dump of the full
parser state at the time of failure.

Unfortunately for some reason providing that debug value does not
result in the behavior that is articulated in the documentation, and
on error the stack is _not_ printed. You can go in and tamper inside
the parsing loop of the same file and sort of get a view into what is
going on.
* Similar projects
A grammar for org syntax written in Clojure by the Organice team.
https://github.com/200ok-ch/org-parser/blob/master/resources/org.ebnf
https://github.com/200ok-ch/org-parser

https://alphapapa.github.io/org-almanac/#Parsing