README.org

A Nodejs org mode parser module

“So What?”

This node.js module implements an org-mode file format parser. Org-mode is a cool Emacs package that lets you structure information in a nice way, and export it in html, latex, pdf and so on.

What does org-mode-parser do that I couldn’t do before?

I was unable to find a JavaScript parser for org-mode. Now we have one. Org-mode is so useful you will start writing in org-mode instead of text files for everything needing a bit of structuring.

It is also XML-free and yes, we like it :)

What are further benefits?

A lot of unit testing (over 100) and a pretty fast parser (see below). Also, it has minimal requirements.

Where can I find more news?

Take a look at http://gioorgi.com/tag/org-mode-parser/ for latest news

Installation

The full installation can be obtained via the npm package repository. On a shell which can run node, try out these lines:

curl http://nodejs.org/dist/v0.10.28/node-v0.10.28.tar.gz | tar xzvf -
(cd node-v0.10.28/ ;  ./configure --prefix=$HOME ; make && make install)
curl --insecure https://www.npmjs.org/install.sh  | bash
npm install org-mode-parser

or launch fast-install.sh

Usage example:

var org=require('../lib/org-mode-parser');
org.makelist("README.org", function (nodelist){
   // Here nodelist is a list of Orgnode objects (ref:putyourcode)
   console.dir(nodelist[0]);
});

API

The parser’s main entry point is the makelist function, which accepts a filename and a callback function. makelist() will pass to the function the list of parsed nodes as first parameter, as described in the opening example.

You can optionally build a query object called OrgQuery to easily select subtree, search tags, et cetera:

var org=require('../lib/org-mode-parser');
org.makelist("./test/treeLevel.org",function(nodes){
    var ofd=new org.OrgQuery(nodes);
    // ofd is a complex object for use in querying and so on
    console.log(ofd.selectTag('complex').first().toOrgString());
});

Supported methods of OrgQuery are:

selectSubtree(node) Extract the nodes hierarchically below the given input
selectTag(tagString)
sortBy
reject(function)
rejectTag(tagName)
toArray()
each(functionToPassEach)
random() Extract a random element
toHtml(options) Generate a fair html rendering. It also support pug (jade) template system. This code is not meant to replace org-mode export functionality, but can be an handy friend. For usage example see test/to-html-test.js

See the unit test section ‘basicLibraries OrgQuery-Complex’ on test/parseTest.js for more usage examples, and do not miss the FAQ

Known Limitations

The input must be a well-formed org-mode file. Parser can detect some corruptions, but it does not provide a complete sanity check.

Every text must have a header. Parser does not support “no-headed” inputs. Anyway, empty headers are supported (see github Issue #11)

Design Goals

API Stability

In general, every API component described in the API section is here to stay. Compatibility will be retained as far as possible in future releases.

Performance

At the time of writing, the parser is pretty fast. On a Linux virtual machine, we get about 20.000 nodes per seconds. We will keep an eye on performance.

You are welcome to help us stress test the parser and find its true limits.

Minimize dependency

Org-mode-parser depends only on two packages, underscore and vows. Vows dependency is used only for regression tests, so the parser really depends only on underscore.

Tests are documentation

Take a look at the examples/ directory for some tiny examples. Please look at test/parserTest.js file for API usage examples. Tests are commented and pretty self-explanatory: they are the primary source for correctness of this module.

FAQ

Where can I find stable packages?

On npm repository. The master branch on GitHub is the development version, so use it at your own risk.

Who is my best friend?

OrgQuery is a very handy object (see below), because it allows you to filter nodes in a structured way. Use it instead of hand-parsing.

How can I get rid of archived nodes?

Use the OrgQuery.rejectArchived() method

Are undeclared drawers parsed?

Yes, but org mode wants them to be declared (see par 2.9 Drawers on documentation). Thus, it is best to not rely on undeclared drawers, because the parser could change in the future to be more stringent. Also, undeclared drawers are not indented!

Querying Questions

How can I find all the subnodes of the node tagged releaseNotes and query it?

var org=require('../lib/org-mode-parser');
org.makelist("./README.org",function(nl){
    var q=new org.OrgQuery(nl);
    var subtree=q.selectSubtree(q.selectTag('releaseNotes').first());
    console.log("Dev version is:"+subtree.selectTag('dev').first().headline);
});

Do you support SETUPFILE and INCLUDE?

No, at least not at the moment.

Github

https://github.com/daitangio/org-mode-parser

Development HOWTO

Globally install vows and try out something like:

npm install -g [email protected]
NODE_PATH=$(dirname $(which node))/../lib/node_modules:. ./bin/testme

Release command sequence / Kitchensink

At the time of writing, the github repository is the master code repository

Check the package.json version
Issue the following commands:

./bin/releaseVersion.sh ORG_MODE_PARSER_0.0.6

Known bugs in progress

Fixing a known bug on vows which is creating false positive on tests vowsjs/vows#187

“vows”:”>=0.5.11” worked, then an incompatibile change was made on vows

Fixes #11 nodelist does not include headers with no text

Colon in the headline mistakenly treated as tag

Hi there!

Thanks a lot for this! This is the best parser I've found so far, for org-mode. Some are too simplistic and others try to do too much and are too complex to be practical out-of-the-box (like orga). org-mode-parser has a great balance of features while being simple and practical to use! Perfect for my use case where I don't really need an AST but a way to make sense of and find org items :) Keep it up!

I've found a small problem, if the headline has a : in it, it will confuse the parser and it will think the headline is actually a tag. Example:

****** Feature: create and register new wordpress-powered (source) jekyll blog :toblog:
       yaya, cool
       markdown here

For this item, org-mode-parser thinks Feature: ... is a tag, besides :toblog:. If I remove the : in Feature, then it correctly detects it as a headline, and :toblog: as the sole tag.

daitangio / org-mode-parser Goto Github PK

org-mode-parser's Introduction