Function: org-toggle-item

org-toggle-item is an interactive and byte-compiled function defined in org-list.el.gz.

Signature

(org-toggle-item ARG)

Documentation

Convert headings or normal lines to items, items to normal lines.

If there is no active region, only the current line is considered.

If the first non blank line in the region is a headline, convert all headlines to items, shifting text accordingly.

If it is an item, convert all items to normal lines.

If it is normal text, change region into a list of items. With a prefix argument ARG, change the region in a single item.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-list.el.gz
(defun org-toggle-item (arg)
  "Convert headings or normal lines to items, items to normal lines.
If there is no active region, only the current line is considered.

If the first non blank line in the region is a headline, convert
all headlines to items, shifting text accordingly.

If it is an item, convert all items to normal lines.

If it is normal text, change region into a list of items.
With a prefix argument ARG, change the region in a single item."
  (interactive "P")
  (let ((shift-text
	 (lambda (ind end)
	   ;; Shift text in current section to IND, from point to END.
	   ;; The function leaves point to END line.
	   (let ((min-i 1000) (end (copy-marker end)))
	     ;; First determine the minimum indentation (MIN-I) of
	     ;; the text.
	     (save-excursion
	       (catch 'exit
		 (while (< (point) end)
		   (let ((i (current-indentation)))
		     (cond
		      ;; Skip blank lines and inline tasks.
		      ((looking-at "^[ \t]*$"))
		      ((looking-at org-outline-regexp-bol))
		      ;; We can't find less than 0 indentation.
		      ((zerop i) (throw 'exit (setq min-i 0)))
		      ((< i min-i) (setq min-i i))))
		   (forward-line))))
	     ;; Then indent each line so that a line indented to
	     ;; MIN-I becomes indented to IND.  Ignore blank lines
	     ;; and inline tasks in the process.
	     (let ((delta (- ind min-i)))
	       (while (< (point) end)
		 (unless (or (looking-at "^[ \t]*$")
			     (looking-at org-outline-regexp-bol))
		   (indent-line-to (+ (current-indentation) delta)))
		 (forward-line))))))
	(skip-blanks
	 (lambda (pos)
	   ;; Return beginning of first non-blank line, starting from
	   ;; line at POS.
	   (save-excursion
	     (goto-char pos)
	     (skip-chars-forward " \r\t\n")
	     (point-at-bol))))
	beg end)
    ;; Determine boundaries of changes.
    (if (org-region-active-p)
	(setq beg (funcall skip-blanks (region-beginning))
	      end (copy-marker (region-end)))
      (setq beg (point-at-bol)
	    end (copy-marker (point-at-eol))))
    ;; Depending on the starting line, choose an action on the text
    ;; between BEG and END.
    (org-with-limited-levels
     (save-excursion
       (goto-char beg)
       (cond
	;; Case 1. Start at an item: de-itemize.  Note that it only
	;;         happens when a region is active: `org-ctrl-c-minus'
	;;         would call `org-cycle-list-bullet' otherwise.
	((org-at-item-p)
	 (while (< (point) end)
	   (when (org-at-item-p)
	     (skip-chars-forward " \t")
	     (delete-region (point) (match-end 0)))
	   (forward-line)))
	;; Case 2. Start at an heading: convert to items.
	((org-at-heading-p)
	 ;; Remove metadata
	 (let (org-loop-over-headlines-in-active-region)
	   (org-list--delete-metadata))
	 (let* ((bul (org-list-bullet-string "-"))
		(bul-len (length bul))
		;; Indentation of the first heading.  It should be
		;; relative to the indentation of its parent, if any.
		(start-ind (save-excursion
			     (cond
			      ((not org-adapt-indentation) 0)
			      ((not (outline-previous-heading)) 0)
			      (t (length (match-string 0))))))
		;; Level of first heading.  Further headings will be
		;; compared to it to determine hierarchy in the list.
		(ref-level (org-reduced-level (org-outline-level))))
	   (while (< (point) end)
	     (let* ((level (org-reduced-level (org-outline-level)))
		    (delta (max 0 (- level ref-level)))
		    (todo-state (org-get-todo-state)))
	       ;; If current headline is less indented than the first
	       ;; one, set it as reference, in order to preserve
	       ;; subtrees.
	       (when (< level ref-level) (setq ref-level level))
	       ;; Remove metadata
	       (let (org-loop-over-headlines-in-active-region)
		 (org-list--delete-metadata))
	       ;; Remove stars and TODO keyword.
	       (let ((case-fold-search nil)) (looking-at org-todo-line-regexp))
	       (delete-region (point) (or (match-beginning 3)
					  (line-end-position)))
	       (insert bul)
	       (indent-line-to (+ start-ind (* delta bul-len)))
	       ;; Turn TODO keyword into a check box.
	       (when todo-state
		 (let* ((struct (org-list-struct))
			(old (copy-tree struct)))
		   (org-list-set-checkbox
		    (line-beginning-position)
		    struct
		    (if (member todo-state org-done-keywords)
			"[X]"
		      "[ ]"))
		   (org-list-write-struct struct
					  (org-list-parents-alist struct)
					  old)))
	       ;; Ensure all text down to END (or SECTION-END) belongs
	       ;; to the newly created item.
	       (let ((section-end (save-excursion
				    (or (outline-next-heading) (point)))))
		 (forward-line)
		 (funcall shift-text
			  (+ start-ind (* (1+ delta) bul-len))
			  (min end section-end)))))))
	;; Case 3. Normal line with ARG: make the first line of region
	;;         an item, and shift indentation of others lines to
	;;         set them as item's body.
	(arg (let* ((bul (org-list-bullet-string "-"))
		    (bul-len (length bul))
		    (ref-ind (current-indentation)))
	       (skip-chars-forward " \t")
	       (insert bul)
	       (forward-line)
	       (while (< (point) end)
		 ;; Ensure that lines less indented than first one
		 ;; still get included in item body.
		 (funcall shift-text
			  (+ ref-ind bul-len)
			  (min end (save-excursion (or (outline-next-heading)
						       (point)))))
		 (forward-line))))
	;; Case 4. Normal line without ARG: turn each non-item line
	;;         into an item.
	(t
	 (while (< (point) end)
	   (unless (or (org-at-heading-p) (org-at-item-p))
	     (when (looking-at "\\([ \t]*\\)\\(\\S-\\)")
	       (replace-match
		(concat "\\1" (org-list-bullet-string "-") "\\2"))))
	   (forward-line))))))))