X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/06d8ace51597cd41e110560a56a1abeb6cce23d6..a2014063066a4b6feb66eba883fae94e26e01087:/lisp/help-fns.el diff --git a/lisp/help-fns.el b/lisp/help-fns.el index 3eb36b7444..b13e6a77d5 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -1,7 +1,6 @@ -;;; help-fns.el --- Complex help functions +;;; help-fns.el --- Complex help functions -*- lexical-binding: t -*- -;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002, -;; 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +;; Copyright (C) 1985-1986, 1993-1994, 1998-2011 ;; Free Software Foundation, Inc. ;; Maintainer: FSF @@ -77,15 +76,18 @@ DEF is the function whose usage we're looking for in DOCSTRING." ;; Replace `fn' with the actual function name. (if (consp def) "anonymous" def) (match-string 1 docstring)) - (substring docstring 0 (match-beginning 0))))) + (unless (zerop (match-beginning 0)) + (substring docstring 0 (match-beginning 0)))))) +;; FIXME: Move to subr.el? (defun help-add-fundoc-usage (docstring arglist) "Add the usage info to DOCSTRING. If DOCSTRING already has a usage info, then just return it unchanged. The usage info is built from ARGLIST. DOCSTRING can be nil. ARGLIST can also be t or a string of the form \"(FUN ARG1 ARG2 ...)\"." - (unless (stringp docstring) (setq docstring "Not documented")) - (if (or (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring) (eq arglist t)) + (unless (stringp docstring) (setq docstring "")) + (if (or (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring) + (eq arglist t)) docstring (concat docstring (if (string-match "\n?\n\\'" docstring) @@ -96,18 +98,61 @@ ARGLIST can also be t or a string of the form \"(FUN ARG1 ARG2 ...)\"." (concat "(fn" (match-string 1 arglist) ")") (format "%S" (help-make-usage 'fn arglist)))))) -(defun help-function-arglist (def) +;; FIXME: Move to subr.el? +(defun help-function-arglist (def &optional preserve-names) + "Return a formal argument list for the function DEF. +IF PRESERVE-NAMES is non-nil, return a formal arglist that uses +the same names as used in the original source code, when possible." ;; Handle symbols aliased to other symbols. (if (and (symbolp def) (fboundp def)) (setq def (indirect-function def))) ;; If definition is a macro, find the function inside it. (if (eq (car-safe def) 'macro) (setq def (cdr def))) (cond - ((byte-code-function-p def) (aref def 0)) + ((and (byte-code-function-p def) (listp (aref def 0))) (aref def 0)) ((eq (car-safe def) 'lambda) (nth 1 def)) + ((eq (car-safe def) 'closure) (nth 2 def)) + ((or (and (byte-code-function-p def) (integerp (aref def 0))) + (subrp def)) + (or (when preserve-names + (let* ((doc (condition-case nil (documentation def) (error nil))) + (docargs (if doc (car (help-split-fundoc doc nil)))) + (arglist (if docargs + (cdar (read-from-string (downcase docargs))))) + (valid t)) + ;; Check validity. + (dolist (arg arglist) + (unless (and (symbolp arg) + (let ((name (symbol-name arg))) + (if (eq (aref name 0) ?&) + (memq arg '(&rest &optional)) + (not (string-match "\\." name))))) + (setq valid nil))) + (when valid arglist))) + (let* ((args-desc (if (not (subrp def)) + (aref def 0) + (let ((a (subr-arity def))) + (logior (car a) + (if (numberp (cdr a)) + (lsh (cdr a) 8) + (lsh 1 7)))))) + (max (lsh args-desc -8)) + (min (logand args-desc 127)) + (rest (logand args-desc 128)) + (arglist ())) + (dotimes (i min) + (push (intern (concat "arg" (number-to-string (1+ i)))) arglist)) + (when (> max min) + (push '&optional arglist) + (dotimes (i (- max min)) + (push (intern (concat "arg" (number-to-string (+ 1 i min)))) + arglist))) + (unless (zerop rest) (push '&rest arglist) (push 'rest arglist)) + (nreverse arglist)))) ((and (eq (car-safe def) 'autoload) (not (eq (nth 4 def) 'keymap))) "[Arg list not available until function definition is loaded.]") (t t))) +;; FIXME: Move to subr.el? (defun help-make-usage (function arglist) (cons (if (symbolp function) function 'anonymous) (mapcar (lambda (arg) @@ -118,8 +163,11 @@ ARGLIST can also be t or a string of the form \"(FUN ARG1 ARG2 ...)\"." (cdr arg)) arg) (let ((name (symbol-name arg))) - (if (string-match "\\`&" name) arg - (intern (upcase name)))))) + (cond + ((string-match "\\`&" name) arg) + ((string-match "\\`_" name) + (intern (upcase (substring name 1)))) + (t (intern (upcase name))))))) arglist))) ;; Could be this, if we make symbol-file do the work below. @@ -174,7 +222,7 @@ if the variable `help-downcase-arguments' is non-nil." (defun help-do-arg-highlight (doc args) (with-syntax-table (make-syntax-table emacs-lisp-mode-syntax-table) (modify-syntax-entry ?\- "w") - (dolist (arg args doc) + (dolist (arg args) (setq doc (replace-regexp-in-string ;; This is heuristic, but covers all common cases ;; except ARG1-ARG2 @@ -188,10 +236,11 @@ if the variable `help-downcase-arguments' is non-nil." "\\(?:-[{([<`\"].*?\\)?"; for ARG-{x}, (x), , [x], `x' "\\>") ; end of word (help-highlight-arg arg) - doc t t 1))))) + doc t t 1))) + doc)) (defun help-highlight-arguments (usage doc &rest args) - (when usage + (when (and usage (string-match "^(" usage)) (with-temp-buffer (insert usage) (goto-char (point-min)) @@ -354,8 +403,7 @@ suitable file is found, return nil." (pt1 (with-current-buffer (help-buffer) (point))) errtype) (setq string - (cond ((or (stringp def) - (vectorp def)) + (cond ((or (stringp def) (vectorp def)) "a keyboard macro") ((subrp def) (if (eq 'unevalled (cdr (subr-arity def))) @@ -374,6 +422,8 @@ suitable file is found, return nil." (concat beg "Lisp function")) ((eq (car-safe def) 'macro) "a Lisp macro") + ((eq (car-safe def) 'closure) + (concat beg "Lisp closure")) ((eq (car-safe def) 'autoload) (format "%s autoloaded %s" (if (commandp def) "an interactive" "an") @@ -477,7 +527,8 @@ suitable file is found, return nil." (let* ((advertised (gethash def advertised-signature-table t)) (arglist (if (listp advertised) advertised (help-function-arglist def))) - (doc (documentation function)) + (doc (condition-case err (documentation function) + (error (format "No Doc! %S" err)))) (usage (help-split-fundoc doc function))) (with-current-buffer standard-output ;; If definition is a keymap, skip arglist note. @@ -507,6 +558,21 @@ suitable file is found, return nil." (insert (car high) "\n") (fill-region fill-begin (point))) (setq doc (cdr high)))) + + ;; If this is a derived mode, link to the parent. + (let ((parent-mode (and (symbolp real-function) + (get real-function + 'derived-mode-parent)))) + (when parent-mode + (with-current-buffer standard-output + (insert "\nParent mode: `") + (let ((beg (point))) + (insert (format "%s" parent-mode)) + (make-text-button beg (point) + 'type 'help-function + 'help-args (list parent-mode)))) + (princ "'.\n"))) + (let* ((obsolete (and ;; function might be a lambda construct. (symbolp function) @@ -534,6 +600,7 @@ If ANY-SYMBOL is non-nil, don't insist the symbol be bound." (with-syntax-table emacs-lisp-mode-syntax-table (or (condition-case () (save-excursion + (skip-chars-forward "'") (or (not (zerop (skip-syntax-backward "_w"))) (eq (char-syntax (following-char)) ?w) (eq (char-syntax (following-char)) ?_) @@ -592,9 +659,9 @@ it is displayed along with the global value." "Describe variable (default %s): " v) "Describe variable: ") obarray - '(lambda (vv) - (or (boundp vv) - (get vv 'variable-documentation))) + (lambda (vv) + (or (get vv 'variable-documentation) + (and (boundp vv) (not (keywordp vv))))) t nil nil (if (symbolp v) (symbol-name v)))) (list (if (equal val "") @@ -664,12 +731,18 @@ it is displayed along with the global value." (delete-region (1- from) from))))))) (terpri) (when locus - (if (bufferp locus) - (princ (format "%socal in buffer %s; " - (if (get variable 'permanent-local) - "Permanently l" "L") - (buffer-name))) - (princ (format "It is a frame-local variable; "))) + (cond + ((bufferp locus) + (princ (format "%socal in buffer %s; " + (if (get variable 'permanent-local) + "Permanently l" "L") + (buffer-name)))) + ((framep locus) + (princ (format "It is a frame-local variable; "))) + ((terminal-live-p locus) + (princ (format "It is a terminal-local variable; "))) + (t + (princ (format "It is local to %S" locus)))) (if (not (default-boundp variable)) (princ "globally void") (let ((val (default-value variable))) @@ -738,7 +811,8 @@ it is displayed along with the global value." (when obsolete (setq extra-line t) (princ " This variable is obsolete") - (if (cdr obsolete) (princ (format " since %s" (cdr obsolete)))) + (if (nth 2 obsolete) + (princ (format " since %s" (nth 2 obsolete)))) (princ (cond ((stringp use) (concat ";\n " use)) (use (format ";\n use `%s' instead." (car obsolete))) (t "."))) @@ -748,15 +822,21 @@ it is displayed along with the global value." (setq extra-line t) (if (member (cons variable val) dir-local-variables-alist) (let ((file (and (buffer-file-name) - (not (file-remote-p (buffer-file-name))) - (dir-locals-find-file (buffer-file-name))))) + (not (file-remote-p (buffer-file-name))) + (dir-locals-find-file + (buffer-file-name)))) + (type "file")) (princ " This variable is a directory local variable") (when file - (princ (concat "\n from the file \"" - (if (consp file) - (car file) - file) - "\""))) + (if (consp file) ; result from cache + ;; If the cache element has an mtime, we + ;; assume it came from a file. + (if (nth 2 file) + (setq file (expand-file-name + dir-locals-file (car file))) + ;; Otherwise, assume it was set directly. + (setq type "directory"))) + (princ (format "\n from the %s \"%s\"" type file))) (princ ".\n")) (princ " This variable is a file local variable.\n"))) @@ -831,7 +911,7 @@ BUFFER defaults to the current buffer." (insert (cond ((null value) "default") ((char-table-p value) "deeper char-table ...") - (t (condition-case err + (t (condition-case nil (category-set-mnemonics value) (error "invalid"))))))