/ 
Org-Parser-0.560
River stage two • 10 direct dependents • 13 total dependents
/ Org::Element::Headline

NAME

Org::Element::Headline - Represent Org headline

VERSION

This document describes version 0.560 of Org::Element::Headline (from Perl distribution Org-Parser), released on 2023-08-05.

DESCRIPTION

Derived from Org::Element.

ATTRIBUTES

level => INT

Level of headline (e.g. 1, 2, 3). Corresponds to the number of bullet stars.

title => OBJ

Org::Element::Text representing the headline title

priority => STR

String (optional) representing priority.

tags => ARRAY

Arrayref (optional) containing list of defined tags.

is_todo => BOOL

Whether this headline is a TODO item.

is_done => BOOL

Whether this TODO item is in a done state (state which requires no more action, e.g. DONE). Only meaningful if headline is a TODO item.

todo_state => STR

TODO state.

Statistics cookie, e.g. '5/10' or '50%'. TODO: there might be more than one statistics cookie.

METHODS

$el->get_tags() => ARRAY

Get tags for this headline. A headline can define tags or inherit tags from its parent headline (or from document).

$el->get_active_timestamp() => ELEMENT

Get the first active timestamp element for this headline, either in the title or in the child elements.

$el->is_leaf() => BOOL

Returns true if element doesn't contain subtrees.

$el->promote_node([$num_levels])

Promote (decrease the level) of this headline node. $level specifies number of levels, defaults to 1. Won't further promote if already at level 1. Illustration:

* h1
** h2   <-- promote 1 level
*** h3
*** h3b
** h4
* h5

becomes:

* h1
* h2
*** h3
*** h3b
** h4
* h5

$el->demote_node([$num_levels])

Does the opposite of promote_node().

$el->promote_branch([$num_levels])

Like promote_node(), but all children headlines will also be promoted. Illustration:

* h1
** h2   <-- promote 1 level
*** h3
**** grandkid
*** h3b

** h4
* h5

becomes:

* h1
* h2
** h3
*** grandkid
** h3b

** h4
* h5

$el->demote_branch([$num_levels])

Does the opposite of promote_branch().

$el->get_property($name, $search_parent) => VALUE

Search for property named $name in the PROPERTIES drawer. If $search_parent is set to true (default is false), will also search in upper-level properties (useful for searching for inherited property, like foo_ALL). Return undef if property cannot be found.

Regardless of $search_parent setting, file-wide properties will be consulted if property is not found in the headline's properties drawer.

$el->get_drawer([$drawer_name]) => VALUE

Return an entire drawer as an Org::Element::Drawer object. By default, return the PROPERTIES drawer. If you want LOGBOOK or some other drawer, ask for it by name.

Update the statistics cookies by recalculating the number of TODO and checkboxes.

Will do nothing if the headline does not have any statistics cookie.

HOMEPAGE

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

SOURCE

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

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2017, 2016, 2015, 2014, 2013, 2012, 2011 by perlancar <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.

BUGS

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

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.