📢 v2 is on it's way!

[xiaoxinghu]

I am spending a fair amount of time working on v2 for a while now. It's close to feature complete, so I think it's time to give you some ideas about what's been going on and where this project is heading. TL;DR: it's going to be awesome. 👍

Why v2

As you can see there are some issues queuing up there, for different reasons. Lot's of them are due to the limitation of the current design. We hack around to fix them (thank you all for the contributions), but they are not ideal. I am currently working on an org-mode related iOS app on the side, so I have created a similar parser in swift (several times...). Switching to a very different language provides a much clearer sense of the thing you are trying to build. With the lessons learnt there, I decided to make orgajs great again (it was not bad before).

The Improvements

• Strong Types The project was converted to TypeScript in the cheapest way possible a couple of months back. (e.g. const data: any = {...}). Now it's much closer to a real TypeScript project. This will make collaboration a lot easier.

• Full OAST Spec Taking advantage of the type system, we now have the full spec of OAST (Orga Abstract Syntax Tree).

• Position (line, column) All tokens and nodes will have position info built-in. 🎉

  {
  type: 'headline',
  position: {
  start: { line: 1, column: 0 },
  end: { line: 1, column: 15 },
  }
  ...
  }

• Flexible Parsing Process orgajs use to heavily rely on complicated regex matching in the scope of individual lines of text. Now it's a much more flexible process. The benefits are:

  • easier to implement/modify/reason parsing logic
  • room for performance optimization
  • tokens are not bound to lines

• Better DX Strong types, auto-completion, easy(er) to read codebase.

• Test! Test! Test! We need more tests. You want it to be more badass? write tests! I am also working on optimizing the test writing experience.

Breaking Changes

v2 is breaking compatibility with the current version. The broken parts are:

• token names
• syntax tree structure
• nodes/tokens now have position info

Basically, everything that's important... The bright side is, that with monorepo setup, I can fix everything up pretty easily altogether.

The spec was loosely defined in v1, hopefully, with strongly typed components in v2, the API will have much better resilient against breaking changes in future releases.

Contribution

All contributions are welcome, it's non-trivial to write a parser for something as powerful as org-mode. orgajs need all the helps it can get from org-mode lovers. We need help with documentation, testing, bug fixes, new features ... While the architecture of this project solidifying during the development of v2, I can see a more collaborative future.

[tvooo]

This is amazing; thank you for your hard work @xiaoxinghu and contributors.

I started to use orga in a personal project of mine, and I've been hitting the limitations quite quickly, given I already have a large base of org files that use still only about 30% of the features that org mode offers. In any case, it's great to see there is a vision for the future, and it is actively being worked on. I'm happy to help and contribute as well.

Is there a prerelease I can use to check things out, or a different branch?

[xiaoxinghu]

@tvooo thanks for the kind words. The work is currently being done in branch v2. You can take a look if you are interested in the implementation. 😉