NAME

Org::Parser::Tiny - Parse Org documents with as little code (and no non-core deps) as possible

VERSION

This document describes version 0.005 of Org::Parser::Tiny (from Perl distribution Org-Parser-Tiny), released on 2020-02-07.

SYNOPSIS

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

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

# parse a string
$doc = $orgp->parse(<<EOF);
* this is a headline
* this is another headline
** this is yet another headline
EOF

Dump document structure using Tree::Dump:

use Tree::Dump;
td($doc);

Select document nodes using Data::CSel:

use Data::CSel qw(csel);

# select headlines with "foo" in their title
my @nodes = csel(
    {class_prefixes => ["Org::Parser::Tiny::Node"]},
    "Headline[title =~ /foo/]"
);

Manipulate tree nodes with path-like semantic using Tree::FSMethods::Org:

Sample sample.org:

some text before the first headline.

* header1                                                               :tag:
contains an internal link to another part of the document [[blah]]
* header2 [#A] [20%]
- contains priority and progress cookie (percent-style)
* header3 [1/10]
- contains progress cookie (fraction-style)
** header3.1
** header3.2
** header3.3
* header4
blah blah.
* blah

Using Tree::FSMethods::Org:

use Tree::FSMethods::Org;
my $fs = Tree::FSMethods::Org->new(
    org_file => "sample.org",
);

# list nodes right above the root node
my %nodes = $fs->ls; # (header1=>{...}, header2=>{...}, header3=>{...}, header4=>{})

# list nodes below header3
$fs->cd("header3");
%nodes = $fs->ls; # ("header3.1"=>{...}, "header3.2"=>{...}, "header3.3"=>{...})

# die, path not found
$fs->cd("/header5");

# remove top-level headlines which have "3"
$fs->rm("*3*");

DESCRIPTION

This module is a more lightweight alternative to Org:Parser. Currently it is very simple and only parses headlines; thus it is several times faster than Org::Parser. I use this to write utilities like sort-org-headlines-tiny or to use it with Tree::FSMethods.

NODE CLASSES

Org::Parser::Tiny::Node

Base class.

Methods:

• parent

• children

• as_string

Org::Parser::Tiny::Node::Document

Root node.

Methods:

Org::Parser::Tiny::Node::Headline

Root node.

Methods:

• level

  Integer.

• title

  Str.

• is_todo

  Whether headline has a done or undone todo state. For example, the following headlines will have their is_todo() return true:

  * TODO foo
  * DONE bar

• is_done

  Whether headline has a done todo state. For example, the following headlines will have their is_done() return true:

  * DONE bar

• todo_state

  Todo state or empty string. For example, this headline:

  * TODO foo

  will have "TODO" as the todo_state, while:

  * foo

  will have "".

• tags

  Array of strings. For example, this headline:

  * foo    :tag1:tag2:

  will have its tags() return ["tag1","tag2"], while this headline:

  * foo

  will have its tags() return [].

• header_as_string

  First line of headline (the header) as string, without the preamble and children.

ATTRIBUTES

METHODS

new

Usage:

my $orgp = Org::Parser::Tiny->new;

Constructor. Create a new parser instance.

parse

Usage:

my $doc = $orgp->parse($str | $arrayref | $coderef | $filehandle, \%opts);

Parse document (which can be contained in a $str, an array of lines $arrayref, a $coderef which will be called for chunks until it returns undef, or a $filehandle.

Returns a tree of node objects (of class Org::Parser::Tiny::Node and its subclasses Org::Parser::Tiny::Node::Document and Org::Parser::Tiny::Node::Headline). The tree node complies to Role::TinyCommons::Tree::Node role, so these tools are available: Data::CSel, Tree::Dump, Tree::FSMethods, etc.

Will die if there are syntax errors in documents.

Known options:

parse_file

Usage:

my $doc = $orgp->parse_file($filename, \%opts);

Just like "parse", but will load document from file instead.

Known options (aside from those known by parse()):

FAQ

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Org-Parser-Tiny.

SOURCE

Source repository is at https://github.com/perlancar/perl-Org-Parser-Tiny.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Org-Parser-Tiny

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

Org::Parser, the more fully featured Org parser.

https://orgmode.org.

Tree::FSMethods::Org and Tree::FSMethods.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020, 2019 by perlancar@cpan.org.

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

cpanm Org::Parser::Tiny

perl -MCPAN -e shell
install Org::Parser::Tiny