NAME
    Org::Parser - Parse Org documents

VERSION
    version 0.25

SYNOPSIS
     use 5.010;
     use Org::Parser;
     my $orgp = Org::Parser->new();

     # parse a file
     my $doc = $orgp->parse_file("$ENV{HOME}/todo.org");

     # parse a string
     $doc = $orgp->parse(<<EOF);
     #+TODO: TODO | DONE CANCELLED
     <<<radio target>>>
     * heading1a
     ** TODO heading2a
     SCHEDULED: <2011-03-31 Thu>
     [[some][link]]
     ** DONE heading2b
     [2011-03-18 ]
     this will become a link: radio target
     * TODO heading1b *bold*
     - some
     - plain
     - list
     - [ ] with /checkbox/
       * and
       * sublist
     * CANCELLED heading1c
     + definition :: list
     + another :: def
     EOF

     # walk the document tree
     $doc->walk(sub {
         my ($el) = @_;
         return unless $el->isa('Org::Element::Headline');
         say "heading level ", $el->level, ": ", $el->title->as_string;
     });

    will print something like:

     heading level 1: heading1a
     heading level 2: heading2a
     heading level 2: heading2b *bold*
     heading level 1: heading1b
     heading level 1: heading1c

    A command-line utility (in a separate distribution: App::OrgUtils) is
    available for debugging:

     % dump-org-structure ~/todo.org
     Document:
       Setting: "#+TODO: TODO | DONE CANCELLED\n"
       RadioTarget: "<<<radio target>>>"
       Text: "\n"
       Headline: l=1
         (title)
         Text: "heading1a"
         (children)
         Headline: l=2 todo=TODO
           (title)
           Text: "heading2a"
           (children)
           Text: "SCHEDULED: "
     ...

DESCRIPTION
    This module parses Org documents. See http://orgmode.org/ for more
    details on Org documents.

    This module uses Log::Any logging framework.

    This module uses Moo object system.

    See "todo.org" in the distribution for the list of already- and not yet
    implemented stuffs.

ATTRIBUTES
METHODS
  new()
    Create a new parser instance.

  $orgp->parse($str | $arrayref | $coderef | $filehandle, $opts) => $doc
    Parse document (which can be contained in a scalar $str, an array of
    lines $arrayref, a subroutine which will be called for chunks until it
    returns undef, or a filehandle).

    Returns Org::Document object.

    If 'handler' attribute is specified, will call handler repeatedly during
    parsing. See the 'handler' attribute for more details.

    Will die if there are syntax errors in documents.

    $opts is a hashref and can contain these keys: "time_zone" (will be
    passed to Org::Document's constructor).

  $orgp->parse_file($filename, $opts) => $doc
    Just like parse(), but will load document from file instead.

FAQ
  Why? Just as only perl can parse Perl, only org-mode can parse Org anyway!
    True. I'm only targetting good enough. As long as I can parse/process
    all my Org notes and todo files, I have no complaints.

  It's too slow!
    Parser is completely regex-based at the moment (I plan to use Marpa
    someday). Performance is quite lousy but I'm not annoyed enough at the
    moment to overhaul it.

SEE ALSO
    Org::Document

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 by Steven Haryanto.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

