File: org-list.el.html
This file contains the code dealing with plain lists in Org mode.
The core concept behind lists is their structure. A structure is
a snapshot of the list, in the shape of a data tree (see
org-list-struct).
Once the list structure is stored, it is possible to make changes
on it that will be mirrored to the real list or to get information
about the list, using accessors and methods provided in the
library. Most of them require the use of one or two helper
functions, namely org-list-parents-alist and
org-list-prevs-alist.
Structure is eventually applied to the buffer with
org-list-write-struct. This function repairs (bullets,
indentation, checkboxes) the list in the process. It should be
called near the end of any function working on structures.
Thus, a function applying to lists should usually follow this template:
1. Verify point is in a list and grab item beginning (with the same
function org-in-item-p). If the function requires the cursor
to be at item's bullet, org-at-item-p is more selective. It
is also possible to move point to the closest item with
org-list-search-backward, or org-list-search-forward,
applied to the function org-item-beginning-re.
2. Get list structure with org-list-struct.
3. Compute one, or both, helper functions,
(org-list-parents-alist, org-list-prevs-alist) depending on
needed accessors.
4. Proceed with the modifications, using methods and accessors.
5. Verify and apply structure to buffer, using
org-list-write-struct.
6. If changes made to the list might have modified check-boxes,
call org-update-checkbox-count-maybe.
Computing a structure can be a costly operation on huge lists (a
few thousand lines long). Thus, code should follow the rule:
"collect once, use many". As a corollary, it is usually a bad idea
to use directly an interactive function inside the code, as those,
being independent entities, read the whole list structure another
time.
Defined variables (16)
org--item-re-cache | Results cache for ‘org-item-re’. |
org-checkbox-hierarchical-statistics | Non-nil means checkbox statistics counts only the state of direct children. |
org-checkbox-statistics-hook | Hook that is run whenever Org thinks checkbox statistics should be updated. |
org-cycle-include-plain-lists | When t, make TAB cycle visibility on plain list items. |
org-list-allow-alphabetical | Non-nil means single character alphabetical bullets are allowed. |
org-list-automatic-rules | Non-nil means apply set of rules when acting on lists. |
org-list-checkbox-radio-mode | Non-nil if Org-List-Checkbox-Radio mode is enabled. |
org-list-checkbox-radio-mode-hook | Hook run after entering or leaving ‘org-list-checkbox-radio-mode’. |
org-list-demote-modify-bullet | Default bullet type installed when demoting an item. |
org-list-end-re | Regex matching the end of a plain list. |
org-list-forbidden-blocks | Names of blocks where lists are not allowed. |
org-list-full-item-re | Matches a list item and puts everything into groups: |
org-list-indent-offset | Additional indentation for sub-items in a list. |
org-list-two-spaces-after-bullet-regexp | A regular expression matching bullets that should have 2 spaces after them. |
org-list-use-circular-motion | Non-nil means commands implying motion in lists should be cyclic. |
org-plain-list-ordered-item-terminator | The character that makes a line with leading number an ordered list item. |