npm package: @latinfor/org-mode
Description: A parser for the Emacs org-mode package. Lightweight fork from https://github.com/daitangio/org-mode-parser.git
Latest version: 0.0.1

#+TITLE:README.org
* A Nodejs org mode parser module
** "So What?"
   This node.js module implements an [[http://orgmode.org/][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:
   #+BEGIN_SRC shell :tangle fast-install.sh
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
   #+END_SRC
   or launch fast-install.sh
** Usage example:
   # Look at
   # http://orgmode.org/manual/Code-block-specific-header-arguments.html
   # for the syntax of BEGIN_SRC :tangle. Anyway, org-babel-tangle
   # will export this source
   #+BEGIN_SRC js -n -r  :tangle examples/basic-example.js
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]);
});
   #+END_SRC
* 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:

  #+BEGIN_SRC javascript -n -r :tangle examples/org-query-example.js
  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());
  });
  #+END_SRC

  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. [[https://github.com/daitangio/org-mode-parser/tree/master][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?
#+BEGIN_SRC javascript  -n -r :tangle examples/org-query-example2.js
  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);
  });
#+END_SRC
** 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:

#+BEGIN_SRC shell :tangle ./bin/run-test-suite.sh
npm install -g vows@0.7.0
NODE_PATH=$(dirname $(which node))/../lib/node_modules:. ./bin/testme
#+END_SRC
* Release command sequence / Kitchensink 		  :kitchensink:
  At the time of writing, the github repository is the master code
  repository  
  1. Check the package.json version
  2. Issue the following commands:
  #+BEGIN_SRC shell
./bin/releaseVersion.sh ORG_MODE_PARSER_0.0.6
  #+END_SRC


** Known bugs in progress
Fixing a known bug on vows which is creating false positive on tests
https://github.com/vowsjs/vows/issues/187

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

Fixes #11 nodelist does not include headers with no text