Org::Element::Headline - Represent Org headline


This document describes version 0.555 of Org::Element::Headline (from Perl distribution Org-Parser), released on 2021-06-27.


Derived from Org::Element.


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.


$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.


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


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


Does the opposite of promote_node().


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

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

 ** h4
 * h5


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

 ** h4
 * h5


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.


Please visit the project's homepage at


Source repository is at


Please report any bugs or feature requests on the bugtracker website

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.


perlancar <>


This software is copyright (c) 2021, 2020, 2019, 2017, 2016, 2015, 2014, 2013, 2012, 2011 by

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