README

   1 NAME
   2     Org::Parser - Parse Org documents
   3
   4 VERSION
   5     version 0.23
   6
   7 SYNOPSIS
   8      use 5.010;
   9      use Org::Parser;
  10      my $orgp = Org::Parser->new();
  11
  12      # parse a file
  13      my $doc = $orgp->parse_file("$ENV{HOME}/todo.org");
  14
  15      # parse a string
  16      $doc = $orgp->parse(<<EOF);
  17      #+TODO: TODO | DONE CANCELLED
  18      <<<radio target>>>
  19      * heading1a
  20      ** TODO heading2a
  21      SCHEDULED: <2011-03-31 Thu>
  22      [[some][link]]
  23      ** DONE heading2b
  24      [2011-03-18 ]
  25      this will become a link: radio target
  26      * TODO heading1b *bold*
  27      - some
  28      - plain
  29      - list
  30      - [ ] with /checkbox/
  31        * and
  32        * sublist
  33      * CANCELLED heading1c
  34      + definition :: list
  35      + another :: def
  36      EOF
  37
  38      # walk the document tree
  39      $doc->walk(sub {
  40          my ($el) = @_;
  41          return unless $el->isa('Org::Element::Headline');
  42          say "heading level ", $el->level, ": ", $el->title->as_string;
  43      });
  44
  45     will print something like:
  46
  47      heading level 1: heading1a
  48      heading level 2: heading2a
  49      heading level 2: heading2b *bold*
  50      heading level 1: heading1b
  51      heading level 1: heading1c
  52
  53     A command-line utility (in a separate distribution: App::OrgUtils) is
  54     available for debugging:
  55
  56      % dump-org-structure ~/todo.org
  57      Document:
  58        Setting: "#+TODO: TODO | DONE CANCELLED\n"
  59        RadioTarget: "<<<radio target>>>"
  60        Text: "\n"
  61        Headline: l=1
  62          (title)
  63          Text: "heading1a"
  64          (children)
  65          Headline: l=2 todo=TODO
  66            (title)
  67            Text: "heading2a"
  68            (children)
  69            Text: "SCHEDULED: "
  70      ...
  71
  72 DESCRIPTION
  73     This module parses Org documents. See http://orgmode.org/ for more
  74     details on Org documents.
  75
  76     This module uses Log::Any logging framework.
  77
  78     This module uses Moo object system.
  79
  80     See "todo.org" in the distribution for the list of already- and not yet
  81     implemented stuffs.
  82
  83 ATTRIBUTES
  84 METHODS
  85   new()
  86     Create a new parser instance.
  87
  88   $orgp->parse($str | $arrayref | $coderef | $filehandle, $opts) => $doc
  89     Parse document (which can be contained in a scalar $str, an array of
  90     lines $arrayref, a subroutine which will be called for chunks until it
  91     returns undef, or a filehandle).
  92
  93     Returns Org::Document object.
  94
  95     If 'handler' attribute is specified, will call handler repeatedly during
  96     parsing. See the 'handler' attribute for more details.
  97
  98     Will die if there are syntax errors in documents.
  99
 100     $opts is a hashref and can contain these keys: "time_zone" (will be
 101     passed to Org::Document's constructor).
 102
 103   $orgp->parse_file($filename, $opts) => $doc
 104     Just like parse(), but will load document from file instead.
 105
 106 FAQ
 107   Why? Just as only perl can parse Perl, only org-mode can parse Org anyway!
 108     True. I'm only targetting good enough. As long as I can parse/process
 109     all my Org notes and todo files, I have no complaints.
 110
 111   It's too slow!
 112     Parser is completely regex-based at the moment (I plan to use Marpa
 113     someday). Performance is quite lousy but I'm not annoyed enough at the
 114     moment to overhaul it.
 115
 116 SEE ALSO
 117     Org::Document
 118
 119 AUTHOR
 120     Steven Haryanto <stevenharyanto@gmail.com>
 121
 122 COPYRIGHT AND LICENSE
 123     This software is copyright (c) 2012 by Steven Haryanto.
 124
 125     This is free software; you can redistribute it and/or modify it under
 126     the same terms as the Perl 5 programming language system itself.
 127