mirror/org-mode
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs/org-mode.git synced 2024-11-24 07:20:29 +00:00
Code

Small refactoring and docstrings update

Browse Source
This commit is contained in:
Nicolas Goaziou 2010-09-14 18:30:03 +02:00 committed by David Maus
parent d3db88ffe4
commit 1caba219da
1 changed files with 15 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
lisp/org-list.el
View File

@ -73,7 +73,6 @@
(defcustom org-cycle-include-plain-lists t
"When t, make TAB cycle visibility on plain list items.
Cycling plain lists works only when the cursor is on a plain list
item. When the cursor is on an outline heading, plain lists are
treated as text. This is the most stable way of handling this,
@ -161,7 +160,6 @@ spaces instead of one after the bullet in each item of the list."
(defcustom org-list-ending-method 'both
"Determine where plain lists should end.
Valid values are: `regexp', `indent' or `both'.
When set to `regexp', Org will look into two variables,
@ -183,7 +181,6 @@ determine lists endings. This is the default method."
(defcustom org-empty-line-terminates-plain-lists nil
"Non-nil means an empty line ends all plain list levels.
This variable only makes sense if `org-list-ending-method' is set
to `regexp' or `both'. This is then equivalent to set
`org-list-end-regexp' to \"^[ \\t]*$\"."
@ -203,14 +200,12 @@ precedence over it."
(indent . t)
(insert . t))
"Non-nil means apply set of rules when acting on lists.
By default, automatic actions are taken when using
\\[org-shiftmetaup], \\[org-shiftmetadown], \\[org-meta-return],
\\[org-metaright], \\[org-metaleft], \\[org-shiftmetaright],
\\[org-shiftmetaleft], \\[org-ctrl-c-minus],
\\[org-toggle-checkbox] or \\[org-insert-todo-heading]. You can
disable individually these rules by setting them to nil. Valid
rules are:
\\[org-meta-return], \\[org-metaright], \\[org-metaleft],
\\[org-shiftmetaright], \\[org-shiftmetaleft],
\\[org-ctrl-c-minus], \\[org-toggle-checkbox] or
\\[org-insert-todo-heading]. You can disable individually these
rules by setting them to nil. Valid rules are:
bullet when non-nil, cycling bullet do not allow lists at
column 0 to have * as a bullet and descriptions lists
@ -327,7 +322,6 @@ the end of the nearest terminator from MAX."
(defun org-list-maybe-skip-block (search limit)
"Return non-nil value if point is in a block, skipping it on the way.
It looks for the boundary of the block in SEARCH direction,
stopping at LIMIT."
(save-match-data
@ -341,7 +335,6 @@ stopping at LIMIT."
(defun org-list-search-unenclosed-generic (search re bound noerr)
"Search a string outside blocks and protected places.
Arguments SEARCH, RE, BOUND and NOERR are similar to those in
`search-forward', `search-backward', `re-search-forward' and
`re-search-backward'."
@ -360,7 +353,6 @@ Arguments SEARCH, RE, BOUND and NOERR are similar to those in
(defun org-search-backward-unenclosed (regexp &optional bound noerror)
"Like `re-search-backward' but don't stop inside blocks or protected places.
Arguments REGEXP, BOUND and NOERROR are similar to those used in
`re-search-backward'."
(org-list-search-unenclosed-generic
@ -368,7 +360,6 @@ Arguments REGEXP, BOUND and NOERROR are similar to those used in
(defun org-search-forward-unenclosed (regexp &optional bound noerror)
"Like `re-search-forward' but don't stop inside blocks or protected places.
Arguments REGEXP, BOUND and NOERROR are similar to those used in
`re-search-forward'."
(org-list-search-unenclosed-generic
@ -376,7 +367,6 @@ Arguments REGEXP, BOUND and NOERROR are similar to those used in
(defun org-list-in-item-p-with-indent (limit)
"Is the cursor inside a plain list?
Plain lists are considered ending when a non-blank line is less
indented than the previous item within LIMIT."
(save-excursion
@ -413,7 +403,6 @@ indented than the previous item within LIMIT."
(defun org-list-in-item-p-with-regexp (limit)
"Is the cursor inside a plain list?
Plain lists end when `org-list-end-regexp' is matched, or at a
blank line if `org-empty-line-terminates-plain-lists' is true.
@ -434,7 +423,6 @@ Argument LIMIT specifies the upper-bound of the search."
(defun org-list-top-point-with-regexp (limit)
"Return point at the top level item in a list.
Argument LIMIT specifies the upper-bound of the search.
List ending is determined by regexp. See
@ -450,7 +438,6 @@ List ending is determined by regexp. See
(defun org-list-bottom-point-with-regexp (limit)
"Return point just before list ending.
Argument LIMIT specifies the lower-bound of the search.
List ending is determined by regexp. See
@ -464,7 +451,6 @@ List ending is determined by regexp. See
(defun org-list-top-point-with-indent (limit)
"Return point at the top level in a list.
Argument LIMIT specifies the upper-bound of the search.
List ending is determined by indentation of text. See
@ -501,7 +487,6 @@ List ending is determined by indentation of text. See
(defun org-list-bottom-point-with-indent (limit)
"Return point just before list ending or nil if not in a list.
Argument LIMIT specifies the lower-bound of the search.
List ending is determined by the indentation of text. See
@ -568,7 +553,6 @@ uses PRE-MOVE before search. Return nil if no item was found."
(defun org-list-separating-blank-lines-number (pos top bottom)
"Return number of blank lines that should separate items in list.
POS is the position of point to be considered.
TOP and BOTTOM are respectively position of list beginning and
@ -613,7 +597,6 @@ some heuristics to guess the result."
(defun org-list-insert-item-generic (pos &optional checkbox after-bullet)
"Insert a new list item at POS.
If POS is before first character after bullet of the item, the
new item will be created before the current one.
@ -703,7 +686,6 @@ function ends."
(defun org-list-indent-item-generic (arg no-subtree top bottom)
"Indent a local list item including its children.
When number ARG is a negative, item will be outdented, otherwise
it will be indented.
@ -876,8 +858,10 @@ A checkbox is blocked if all of the following conditions are fulfilled:
;; already in a list and doesn't compute list boundaries.
;; If you plan to use more than one org-list function is some code,
;; you should therefore first compute list boundaries, and then make
;; use of non-interactive forms.
;; you should therefore first check if point is in a list with
;; `org-in-item-p' or `org-at-item-p', then compute list boundaries
;; with `org-list-top-point' and `org-list-bottom-point', and make use
;; of non-interactive forms.
(defun org-list-top-point ()
"Return point at the top level in a list.
@ -973,8 +957,8 @@ If the cursor in not in an item, throw an error."
(defun org-get-end-of-item (bottom)
"Return position at the end of the current item.
BOTTOM is the position at list ending."
(let* ((next-p (org-get-next-item (point) bottom)))
(or next-p (org-get-end-of-list bottom))))
(or (org-get-next-item (point) bottom)
(org-get-end-of-list bottom)))
(defun org-end-of-item ()
"Go to the end of the current hand-formatted item.
@ -1011,7 +995,6 @@ Stop searching at LIMIT. Return nil if no item is found."
(defun org-previous-item ()
"Move to the beginning of the previous item.
Item is at the same level in the current plain list. Error if not
in a plain list, or if this is the first item in the list."
(interactive)
@ -1028,7 +1011,6 @@ Stop searching at LIMIT. Return nil if no item is found."
(defun org-next-item ()
"Move to the beginning of the next item.
Item is at the same level in the current plain list. Error if not
in a plain list, or if this is the last item in the list."
(interactive)
@ -1041,7 +1023,6 @@ in a plain list, or if this is the last item in the list."
(defun org-list-exchange-items (beg-A beg-B bottom)
"Swap item starting at BEG-A with item starting at BEG-B.
Blank lines at the end of items are left in place. Assume BEG-A
is lesser than BEG-B.
@ -1062,7 +1043,6 @@ BOTTOM is the position at list ending."
(defun org-move-item-down ()
"Move the plain list item at point down, i.e. swap with following item.
Subitems (items with larger indentation) are considered part of the item,
so this really moves item trees."
(interactive)
@ -1084,7 +1064,6 @@ so this really moves item trees."
(defun org-move-item-up ()
"Move the plain list item at point up, i.e. swap with previous item.
Subitems (items with larger indentation) are considered part of the item,
so this really moves item trees."
(interactive)
@ -1106,7 +1085,6 @@ so this really moves item trees."
(defun org-insert-item (&optional checkbox)
"Insert a new item at the current level.
If cursor is before first character after bullet of the item, the
new item will be created before the current one.
@ -1166,7 +1144,6 @@ bullet string and bullet counter, if any."
(defun org-list-struct (begin end top bottom &optional outdent)
"Return the structure containing the list between BEGIN and END.
A structure is an alist where key is point of item and values
are, in that order, indentation, bullet string and value of
counter, if any. A structure contains every list and sublist that
@ -1232,7 +1209,6 @@ change is an outdent."
(defun org-list-struct-origins (struct)
"Return an alist where key is item's position and value parent's.
STRUCT is the list's structure looked up."
(let* ((struct-rev (reverse struct))
(acc (list (cons (nth 1 (car struct)) 0)))
@ -1263,7 +1239,6 @@ STRUCT is the list's structure looked up."
(defun org-list-struct-get-parent (item struct origins)
"Return parent association of ITEM in STRUCT or nil.
ORIGINS is the alist of parents. See `org-list-struct-origins'."
(let* ((parent-pos (cdr (assq (car item) origins))))
(when (> parent-pos 0) (assq parent-pos struct))))
@ -1276,7 +1251,6 @@ ORIGINS is the alist of parents. See `org-list-struct-origins'."
(defun org-list-struct-fix-bul (struct origins)
"Verify and correct bullets for every association in STRUCT.
ORIGINS is the alist of parents. See `org-list-struct-origins'.
This function modifies STRUCT."
@ -1317,7 +1291,6 @@ This function modifies STRUCT."
(defun org-list-struct-fix-ind (struct origins)
"Verify and correct indentation for every association in STRUCT.
ORIGINS is the alist of parents. See `org-list-struct-origins'.
This function modifies STRUCT."
@ -1337,7 +1310,6 @@ This function modifies STRUCT."
(defun org-list-struct-fix-struct (struct origins)
"Return STRUCT with correct bullets and indentation.
ORIGINS is the alist of parents. See `org-list-struct-origins'.
Only elements of STRUCT that have changed are returned."
@ -1348,7 +1320,6 @@ Only elements of STRUCT that have changed are returned."
(defun org-list-struct-outdent (start end origins)
"Outdent items in a structure.
Items are indented when their key is between START, included, and
END, excluded.
@ -1381,7 +1352,6 @@ STRUCT is the concerned structure."
(defun org-list-struct-indent (start end origins struct)
"Indent items in a structure.
Items are indented when their key is between START, included, and
END, excluded.
@ -1444,7 +1414,6 @@ END."
(defun org-list-struct-apply-struct (struct bottom)
"Apply modifications to list so it mirrors STRUCT.
BOTTOM is position at list ending.
Initial position is restored after the changes."
@ -1517,7 +1486,6 @@ BOTTOM is position at list ending."
(defun org-outdent-item ()
"Outdent a local list item, but not its children.
If a region is active, all items inside will be moved."
(interactive)
(org-list-indent-item-generic
@ -1525,7 +1493,6 @@ If a region is active, all items inside will be moved."
(defun org-indent-item ()
"Indent a local list item, but not its children.
If a region is active, all items inside will be moved."
(interactive)
(org-list-indent-item-generic
@ -1533,7 +1500,6 @@ If a region is active, all items inside will be moved."
(defun org-outdent-item-tree ()
"Outdent a local list item including its children.
If a region is active, all items inside will be moved."
(interactive)
(org-list-indent-item-generic
@ -1541,7 +1507,6 @@ If a region is active, all items inside will be moved."
(defun org-indent-item-tree ()
"Indent a local list item including its children.
If a region is active, all items inside will be moved."
(interactive)
(org-list-indent-item-generic
@ -1550,9 +1515,8 @@ If a region is active, all items inside will be moved."
(defvar org-tab-ind-state)
(defun org-cycle-item-indentation ()
"Cycle levels of indentation of an empty item.
The first run indent the item, if applicable. Subsequents runs
outdent it at meaningful levels in the list. When done, item is
The first run indent the item, if applicable. Subsequents runs
outdent it at meaningful levels in the list. When done, item is
put back at its original position with its original bullet.
Return t at each successful move."
@ -1699,7 +1663,6 @@ is an integer, 0 means `-', 1 means `+' etc. If WHICH is
(defun org-toggle-checkbox (&optional toggle-presence)
"Toggle the checkbox in the current line.
With prefix arg TOGGLE-PRESENCE, add or remove checkboxes. With
double prefix, set checkbox to [-].
@ -1935,8 +1898,7 @@ Otherwise it will be `org-todo'."
;;; Misc Tools
(defun org-apply-on-list (function init-value &rest args)
"Call FUNCTION for each item of a the list under point.
"Call FUNCTION on each item of the list at point.
FUNCTION must be called with at least one argument: INIT-VALUE,
that will contain the value returned by the function at the
previous item, plus ARGS extra arguments.
@ -1944,7 +1906,7 @@ previous item, plus ARGS extra arguments.
As an example, (org-apply-on-list (lambda (result) (1+ result)) 0)
will return the number of items in the current list.
Sublists of the list are skipped. Cursor is always at the
Sublists of the list are skipped. Cursor is always at the
beginning of the item."
(let* ((pos (copy-marker (point)))
(end (copy-marker (org-list-bottom-point)))
@ -2189,7 +2151,6 @@ this list."
(defun org-list-to-generic (list params)
"Convert a LIST parsed through `org-list-parse-list' to other formats.
Valid parameters PARAMS are
:ustart String to start an unordered list