Skip to content
org-mode parser rewrite in Rust
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
rust Add SPDX license identifier to Cargo.toml (#12) Apr 15, 2019
.gitignore going public Apr 14, 2019
CODE_OF_CONDUCT.md Add Contributor Covenant Code of Conduct (#19) Apr 17, 2019
CONTRIBUTING.org going public Apr 14, 2019
LICENSE
README.md Add gitter link to readme (#13) Apr 15, 2019

README.md

Org Mode parser re-write in Rust

! Warning, this project is in early development !

Motivation

Org is probably the best and most complete plain text organizational system known to mankind. It has countless applications like authoring, publishing, task and time tracking, journal, blog, agenda, wiki etc...

Unfortunately Org was originally developed for Emacs and therefore available only inside Emacs. It is a huge limiting factor for Org's development and popularization. Because of that it is not as popular outside of Emacs community as it should be.

Many attempts were made to fix this. It all starts with a parser. But because Org's syntax is not trivial and in fact most of it is context-sensitive with only a few context-free elements, it is quite easy to get it wrong. Some Org parsers have chosen to focus on a restricted subset of Org's syntax like org-ruby or pandoc. More ambitious projects try to cover all features but since Org does not have a formal specification1 they rely on observed Org's behavior in Emacs or author's intuition. As a result they rarely get finished.

But the absence of a good a spec and the complexity of the grammar are not show stoppers. Why reinventing the wheel when we can just copy it! This project takes the only surefire way to get it right - use the original elisp parser implementation as a blueprint!

Goals

  • Be fast. Speed matters. Period.
  • Be feature-complete, compliant with original implementation. Nobody wants Nth competing standard.
  • Be standalone, embeddable and reusable. User must not be locked into one particular editor or ecosystem. Integrations with language servers, editors and plugins should be encouraged.

Design decisions

These are the choices that were made to achieve the goals:

  • Rust. Because it is fast, memory safe and provides C FFI. And most importantly it is cool.

  • Rope as underlying data structure that provides O(log n) updates. xi-rope is an awesome implementation from xi-editor project.

  • Original elisp algorithm. While using the original elisp source as a guideline might result in less idiomatic Rust code it has its advantages:

    • Scope of work is well-defined and finish line is visible. This should encourage contributions even from people who want to get started with Rust.

    • Getting "feature-complete" is just a matter of getting to the finish line.

Roadmap

element - parser crate is currently the main and only focus. It should perform just 2 tasks. Generate concrete syntax tree and serialize it back to canonical Org representation.

The rest of the roadmap is not fully flashed out. Feature-complete parser opens a lot of possibilities, here are just a few of my ideas:

  • Parse tree manipulation tools (like exporting to other formats).

  • Language server - a way to solve "the matrix" problem. Enabling other editors to have their own org-mode would be a logical next step.

  • CLI tools. I'd love to get integration with TaskWarrior and maybe even use Org as TaskWarrior's DOM.

Contribution

Any contributions are welcome. If you want to help check out contribution guide.

Got a question? Stop by for a chat at gitter

Similar projects

More about Org Mode

Footnote

  1. Some attempts were made to formalize the syntax. This project uses them as supplementary materials. See contribution guide for details.
You can’t perform that action at this time.