diff options
Diffstat (limited to 'lisp/emacs-lisp/shortdoc.el')
| -rw-r--r-- | lisp/emacs-lisp/shortdoc.el | 174 |
1 files changed, 124 insertions, 50 deletions
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index 39e69f5aab9..7d4a69f42a9 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -32,13 +32,10 @@ "Short documentation." :group 'lisp) -(defface shortdoc-separator - '((((class color) (background dark)) - :height 0.1 :background "#505050" :extend t) - (((class color) (background light)) - :height 0.1 :background "#a0a0a0" :extend t) - (t :height 0.1 :inverse-video t :extend t)) - "Face used to separate sections.") +(defface shortdoc-heading + '((t :inherit variable-pitch :height 1.3 :weight bold)) + "Face used for a heading." + :version "28.1") (defface shortdoc-section '((t :inherit variable-pitch)) @@ -55,8 +52,10 @@ FUNCTIONS is a list of elements on the form: :args ARGS :eval EXAMPLE-FORM :no-eval EXAMPLE-FORM + :no-eval* EXAMPLE-FORM :no-value EXAMPLE-FORM :result RESULT-FORM + :result-string RESULT-FORM :eg-result RESULT-FORM :eg-result-string RESULT-FORM) @@ -155,6 +154,10 @@ There can be any number of :example/:result elements." :eval (split-string "foo bar") :eval (split-string "|foo|bar|" "|") :eval (split-string "|foo|bar|" "|" t)) + (split-string-and-unquote + :eval (split-string-and-unquote "foo \"bar zot\"")) + (split-string-shell-command + :eval (split-string-shell-command "ls /tmp/'foo bar'")) (string-lines :eval (string-lines "foo\n\nbar") :eval (string-lines "foo\n\nbar" t)) @@ -163,15 +166,12 @@ There can be any number of :example/:result elements." (replace-regexp-in-string :eval (replace-regexp-in-string "[a-z]+" "_" "*foo*")) (string-trim - :no-manual t :args (string) :doc "Trim STRING of leading and trailing white space." :eval (string-trim " foo ")) (string-trim-left - :no-manual t :eval (string-trim-left "oofoo" "o+")) (string-trim-right - :no-manual t :eval (string-trim-right "barkss" "s+")) (string-truncate-left :no-manual t @@ -219,7 +219,7 @@ There can be any number of :example/:result elements." (string-greaterp :eval (string-greaterp "foo" "bar")) (string-version-lessp - :eval (string-lessp "foo32.png" "bar4.png")) + :eval (string-version-lessp "pic4.png" "pic32.png")) (string-prefix-p :eval (string-prefix-p "foo" "foobar")) (string-suffix-p @@ -264,14 +264,25 @@ There can be any number of :example/:result elements." :eval (file-name-extension "/tmp/foo.txt")) (file-name-sans-extension :eval (file-name-sans-extension "/tmp/foo.txt")) + (file-name-with-extension + :eval (file-name-with-extension "foo.txt" "bin") + :eval (file-name-with-extension "foo" "bin")) (file-name-base :eval (file-name-base "/tmp/foo.txt")) (file-relative-name :eval (file-relative-name "/tmp/foo" "/tmp")) (make-temp-name :eval (make-temp-name "/tmp/foo-")) + (file-name-concat + :eval (file-name-concat "/tmp/" "foo") + :eval (file-name-concat "/tmp" "foo") + :eval (file-name-concat "/tmp" "foo" "bar/" "zot") + :eval (file-name-concat "/tmp" "~")) (expand-file-name - :eval (expand-file-name "foo" "/tmp/")) + :eval (expand-file-name "foo" "/tmp/") + :eval (expand-file-name "foo" "/tmp///") + :eval (expand-file-name "foo" "/tmp/foo/.././") + :eval (expand-file-name "~" "/tmp/")) (substitute-in-file-name :eval (substitute-in-file-name "$HOME/foo")) "Directory Functions" @@ -492,9 +503,13 @@ There can be any number of :example/:result elements." (flatten-tree :eval (flatten-tree '(1 (2 3) 4))) (car - :eval (car '(one two three))) + :eval (car '(one two three)) + :eval (car '(one . two)) + :eval (car nil)) (cdr - :eval (cdr '(one two three))) + :eval (cdr '(one two three)) + :eval (cdr '(one . two)) + :eval (cdr nil)) (last :eval (last '(one two three))) (butlast @@ -611,7 +626,7 @@ There can be any number of :example/:result elements." (lax-plist-get :eval (lax-plist-get '("a" 1 "b" 2 "c" 3) "b")) (lax-plist-put - :no-eval (setq plist (plist-put plist "d" 4)) + :no-eval (setq plist (lax-plist-put plist "d" 4)) :eq-result '("a" 1 "b" 2 "c" 3 "d" 4)) (plist-member :eval (plist-member '(a 1 b 2 c 3) 'b)) @@ -623,7 +638,7 @@ There can be any number of :example/:result elements." (length> :eval (length> '(a b c) 1)) (length= - :eval (length> '(a b c) 3)) + :eval (length= '(a b c) 3)) (safe-length :eval (safe-length '(a b c)))) @@ -664,7 +679,7 @@ There can be any number of :example/:result elements." :no-eval (re-search-backward "^foo$" nil t) :eg-result 43) (looking-at-p - :no-eval (looking-at "f[0-9]") + :no-eval (looking-at-p "f[0-9]") :eg-result t) "Match Data" (match-string @@ -685,6 +700,8 @@ There can be any number of :example/:result elements." (match-substitute-replacement :no-eval (match-substitute-replacement "new") :eg-result "new") + (replace-regexp-in-region + :no-value (replace-regexp-in-region "[0-9]+" "Num \\&")) "Utilities" (regexp-quote :eval (regexp-quote "foo.*bar")) @@ -836,7 +853,7 @@ There can be any number of :example/:result elements." (point :eval (point)) (point-min - :eval (point-max)) + :eval (point-min)) (point-max :eval (point-max)) (line-beginning-position @@ -879,11 +896,61 @@ There can be any number of :example/:result elements." :no-value (erase-buffer)) (insert :no-value (insert "This string will be inserted in the buffer\n")) + (subst-char-in-region + :no-eval "(subst-char-in-region (point-min) (point-max) ?+ ?-)") + (replace-string-in-region + :no-value (replace-string-in-region "foo" "bar")) "Locking" (lock-buffer :no-value (lock-buffer "/tmp/foo")) (unlock-buffer - :no-value (lock-buffer))) + :no-value (unlock-buffer))) + +(define-short-documentation-group overlay + "Predicates" + (overlayp + :no-eval (overlayp some-overlay) + :eg-result t) + "Creation and Deletion" + (make-overlay + :args (beg end &optional buffer) + :no-eval (make-overlay 1 10) + :eg-result-string "#<overlay from 1 to 10 in *foo*>") + (delete-overlay + :no-eval (delete-overlay foo) + :eg-result t) + "Searching Overlays" + (overlays-at + :no-eval (overlays-at 15) + :eg-result-string "(#<overlay from 1 to 10 in *foo*>)") + (overlays-in + :no-eval (overlays-in 1 30) + :eg-result-string "(#<overlay from 1 to 10 in *foo*>)") + (next-overlay-change + :no-eval (next-overlay-change 1) + :eg-result 20) + (previous-overlay-change + :no-eval (previous-overlay-change 30) + :eg-result 20) + "Overlay Properties" + (overlay-start + :no-eval (overlay-start foo) + :eg-result 1) + (overlay-end + :no-eval (overlay-end foo) + :eg-result 10) + (overlay-put + :no-eval (overlay-put foo 'happy t) + :eg-result t) + (overlay-get + :no-eval (overlay-get foo 'happy) + :eg-result t) + (overlay-buffer + :no-eval (overlay-buffer foo)) + "Moving Overlays" + (move-overlay + :no-eval (move-overlay foo 5 20) + :eg-result-string "#<overlay from 5 to 20 in *foo*>")) (define-short-documentation-group process (make-process @@ -1054,7 +1121,7 @@ There can be any number of :example/:result elements." (logb :eval (logb 10.5)) (ffloor - :eval (floor 1.2)) + :eval (ffloor 1.2)) (fceiling :eval (fceiling 1.2)) (ftruncate @@ -1084,8 +1151,9 @@ There can be any number of :example/:result elements." :eval (sqrt -1))) ;;;###autoload -(defun shortdoc-display-group (group) - "Pop to a buffer with short documentation summary for functions in GROUP." +(defun shortdoc-display-group (group &optional function) + "Pop to a buffer with short documentation summary for functions in GROUP. +If FUNCTION is non-nil, place point on the entry for FUNCTION (if any)." (interactive (list (completing-read "Show summary for functions in: " (mapcar #'car shortdoc--groups)))) (when (stringp group) @@ -1107,24 +1175,26 @@ There can be any number of :example/:result elements." (insert "\n")) (insert (propertize (concat (substitute-command-keys data) "\n\n") - 'face '(variable-pitch (:height 1.3 :weight bold)) + 'face 'shortdoc-heading 'shortdoc-section t))) ;; There may be functions not yet defined in the data. ((fboundp (car data)) (when prev - (insert (propertize "\n" 'face 'shortdoc-separator))) + (insert (make-separator-line))) (setq prev t) (shortdoc--display-function data)))) (cdr (assq group shortdoc--groups)))) - (goto-char (point-min))) + (goto-char (point-min)) + (when function + (text-property-search-forward 'shortdoc-function function t) + (beginning-of-line))) (defun shortdoc--display-function (data) (let ((function (pop data)) (start-section (point)) arglist-start) ;; Function calling convention. - (insert (propertize "(" - 'shortdoc-function t)) + (insert (propertize "(" 'shortdoc-function function)) (if (plist-get data :no-manual) (insert-text-button (symbol-name function) @@ -1175,7 +1245,7 @@ function's documentation in the Info manual"))) (prin1 value (current-buffer))) (insert "\n " single-arrow " " (propertize "[it depends]" - 'face 'variable-pitch) + 'face 'shortdoc-section) "\n")) (:no-value (if (stringp value) @@ -1233,11 +1303,11 @@ Example: (let ((glist (assq group shortdoc--groups))) (unless glist (setq glist (list group)) - (setq shortdoc--groups (append shortdoc--groups (list glist)))) + (push glist shortdoc--groups)) (let ((slist (member section glist))) (unless slist (setq slist (list section)) - (setq slist (append glist slist))) + (nconc glist slist)) (while (and (cdr slist) (not (stringp (cadr slist)))) (setq slist (cdr slist))) @@ -1250,41 +1320,45 @@ Example: (define-key map (kbd "C-c C-n") 'shortdoc-next-section) (define-key map (kbd "C-c C-p") 'shortdoc-previous-section) map) - "Keymap for `shortdoc-mode'") + "Keymap for `shortdoc-mode'.") (define-derived-mode shortdoc-mode special-mode "shortdoc" - "Mode for shortdoc.") + "Mode for shortdoc." + :interactive nil) -(defmacro shortdoc--goto-section (arg sym &optional reverse) - `(progn - (unless (natnump ,arg) - (setq ,arg 1)) - (while (< 0 ,arg) - (,(if reverse - 'text-property-search-backward - 'text-property-search-forward) - ,sym t) - (setq ,arg (1- ,arg))))) +(defun shortdoc--goto-section (arg sym &optional reverse) + (unless (natnump arg) + (setq arg 1)) + (while (> arg 0) + (funcall + (if reverse 'text-property-search-backward + 'text-property-search-forward) + sym nil t t) + (setq arg (1- arg)))) (defun shortdoc-next (&optional arg) - "Move cursor to next function." - (interactive "p") + "Move cursor to the next function. +With ARG, do it that many times." + (interactive "p" shortdoc-mode) (shortdoc--goto-section arg 'shortdoc-function)) (defun shortdoc-previous (&optional arg) - "Move cursor to previous function." - (interactive "p") + "Move cursor to the previous function. +With ARG, do it that many times." + (interactive "p" shortdoc-mode) (shortdoc--goto-section arg 'shortdoc-function t) (backward-char 1)) (defun shortdoc-next-section (&optional arg) - "Move cursor to next section." - (interactive "p") + "Move cursor to the next section. +With ARG, do it that many times." + (interactive "p" shortdoc-mode) (shortdoc--goto-section arg 'shortdoc-section)) (defun shortdoc-previous-section (&optional arg) - "Move cursor to previous section." - (interactive "p") + "Move cursor to the previous section. +With ARG, do it that many times." + (interactive "p" shortdoc-mode) (shortdoc--goto-section arg 'shortdoc-section t) (forward-line -2)) |