code.delx.au - gnu-emacs-elpa/blob - js2-imenu-extras.el

   1 ;;; js2-imenu-extras.el --- Imenu support for additional constructs
   2
   3 ;; Author:    Dmitry Gutov <dgutov@yandex.ru>
   4 ;; Keywords:  languages, javascript, imenu
   5
   6 ;; This file is part of GNU Emacs.
   7
   8 ;; GNU Emacs is free software: you can redistribute it and/or modify
   9 ;; it under the terms of the GNU General Public License as published by
  10 ;; the Free Software Foundation, either version 3 of the License, or
  11 ;; (at your option) any later version.
  12
  13 ;; GNU Emacs is distributed in the hope that it will be useful,
  14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 ;; GNU General Public License for more details.
  17
  18 ;; You should have received a copy of the GNU General Public License
  19 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  20
  21 ;;; Commentary:
  22
  23 ;; This package adds Imenu support for additional framework constructs and
  24 ;; general patterns to `js2-mode'.
  25
  26 ;; Usage:
  27
  28 ;; (eval-after-load 'js2-mode
  29 ;;   '(progn
  30 ;;      (require 'js2-imenu-extras)
  31 ;;      (js2-imenu-extras-setup)))
  32
  33 ;; To customize how it works:
  34 ;;   M-x customize-group RET js2-imenu RET
  35
  36 (eval-when-compile
  37   (require 'cl))
  38
  39 (require 'js2-mode)
  40
  41 (defconst js2-imenu-extension-styles
  42   `((:framework jquery
  43      :call-re   "\\_<\\(?:jQuery\\|\\$\\|_\\)\\.extend\\s-*("
  44      :recorder  js2-imenu-record-jquery-extend)
  45
  46     (:framework jquery-ui
  47      :call-re   "^\\s-*\\(?:jQuery\\|\\$\\)\\.widget\\s-*("
  48      :recorder  js2-imenu-record-string-declare)
  49
  50     (:framework dojo
  51      :call-re   "^\\s-*dojo.declare\\s-*("
  52      :recorder  js2-imenu-record-string-declare)
  53
  54     (:framework backbone
  55      :call-re   ,(concat "\\_<" js2-mode-identifier-re "\\.extend\\s-*(")
  56      :recorder  js2-imenu-record-backbone-extend))
  57   "List of JavaScript class definition or extension styles.
  58
  59 :framework is a valid value in `js2-imenu-enabled-frameworks'.
  60
  61 :call-re is a regular expression that has no capturing groups.
  62
  63 :recorder is a function name that will be called when the regular
  64 expression matches some text in the buffer.  When it's called, point will be
  65 at the end of the match.  The function must keep the point position.")
  66
  67 (defconst js2-imenu-available-frameworks
  68   (mapcar (lambda (style) (plist-get style :framework)) js2-imenu-extension-styles)
  69   "List of available JavaScript framework symbols.")
  70
  71 (defcustom js2-imenu-enabled-frameworks js2-imenu-available-frameworks
  72   "Frameworks to be recognized by `js2-mode'."
  73   :type (cons 'set (mapcar (lambda (x) (list 'const x))
  74                            js2-imenu-available-frameworks))
  75   :group 'js2-imenu)
  76
  77 (defcustom js2-imenu-show-other-functions t
  78   "Non-nil to show functions not recognized by other mechanisms,
  79 in a shared namespace."
  80   :type 'boolean
  81   :group 'js2-imenu)
  82
  83 (defcustom js2-imenu-other-functions-ns "?"
  84   "Namespace name to use for other functions."
  85   :type 'string
  86   :group 'js2-imenu)
  87
  88 (defcustom js2-imenu-show-module-pattern t
  89   "Non-nil to recognize the module pattern:
  90
  91 var foobs = (function(a) {
  92   return {fib: function() {}, fub: function() {}};
  93 })(b);
  94
  95 We record the returned hash as belonging to the named module, and
  96 prefix any functions defined inside the IIFE with the module name."
  97   :type 'boolean
  98   :group 'js2-imenu)
  99
 100 ;;;###autoload
 101 (defun js2-imenu-extras-setup ()
 102   (when js2-imenu-enabled-frameworks
 103     (add-to-list 'js2-post-parse-callbacks 'js2-imenu-record-declarations t))
 104   (when (or js2-imenu-show-other-functions js2-imenu-show-module-pattern)
 105     (add-to-list 'js2-post-parse-callbacks 'js2-imenu-walk-ast t)))
 106
 107 (defun js2-imenu-record-declarations ()
 108   (let* ((styles (loop for style in js2-imenu-extension-styles
 109                        when (memq (plist-get style :framework)
 110                                   js2-imenu-enabled-frameworks)
 111                        collect style))
 112          (re (mapconcat (lambda (style)
 113                           (concat "\\(" (plist-get style :call-re) "\\)"))
 114                         styles "\\|")))
 115     (goto-char (point-min))
 116     (while (js2-re-search-forward re nil t)
 117       (loop for i from 0 to (1- (length styles))
 118             when (match-beginning (1+ i))
 119             return (funcall (plist-get (nth i styles) :recorder))))))
 120
 121 (defun js2-imenu-record-jquery-extend ()
 122   (let ((pred (lambda (subject)
 123                 (and
 124                  (js2-prop-get-node-p subject)
 125                  (string= (js2-name-node-name (js2-prop-get-node-right subject))
 126                           "prototype")))))
 127     (js2-imenu-record-extend-first-arg (1- (point)) pred
 128                                        'js2-compute-nested-prop-get)))
 129
 130 (defun js2-imenu-record-string-declare ()
 131   (js2-imenu-record-extend-first-arg
 132    (1- (point)) 'js2-string-node-p
 133    (lambda (node) (split-string (js2-string-node-value node) "\\." t))))
 134
 135 (defun js2-imenu-record-extend-first-arg (point pred qname-fn)
 136   (let* ((node (js2-node-at-point point))
 137          (args (js2-call-node-args node))
 138          (subject (first args)))
 139     (when (funcall pred subject)
 140       (loop for arg in (cdr args)
 141             when (js2-object-node-p arg)
 142             do (js2-record-object-literal
 143                 arg (funcall qname-fn subject) (js2-node-abs-pos arg))))))
 144
 145 (defun js2-imenu-record-backbone-extend ()
 146   (let* ((node (js2-node-at-point (1- (point))))
 147          (args (js2-call-node-args node))
 148          (methods (first args))
 149          (parent (js2-node-parent node)))
 150     (when (js2-object-node-p methods)
 151       (let ((subject (cond ((js2-var-init-node-p parent)
 152                             (js2-var-init-node-target parent))
 153                            ((js2-assign-node-p parent)
 154                             (js2-assign-node-left parent)))))
 155         (when subject
 156           (js2-record-object-literal methods
 157                                      (js2-compute-nested-prop-get subject)
 158                                      (js2-node-abs-pos methods)))))))
 159
 160 (defun js2-imenu-walk-ast ()
 161   (js2-visit-ast
 162    js2-mode-ast
 163    (lambda (node end-p)
 164      (unless end-p
 165        (cond
 166         ((and js2-imenu-show-other-functions
 167               (js2-object-prop-node-p node))
 168          (js2-imenu-record-orphan-function node))
 169         ((and js2-imenu-show-module-pattern
 170               (js2-assign-node-p node))
 171          (js2-imenu-record-module-pattern node)))
 172        t))))
 173
 174 (defun js2-imenu-record-orphan-function (node)
 175   "Record orphan function when it's the value of NODE.
 176 NODE must be `js2-object-prop-node'."
 177   (when (js2-function-node-p (js2-object-prop-node-right node))
 178     (let ((fn-node (js2-object-prop-node-right node)))
 179       (unless (and js2-imenu-function-map
 180                    (gethash fn-node js2-imenu-function-map))
 181         (let ((key-node (js2-object-prop-node-left node)))
 182           (js2-record-imenu-entry fn-node
 183                                   (list js2-imenu-other-functions-ns
 184                                         (js2-prop-node-name key-node))
 185                                   (js2-node-abs-pos key-node)))))))
 186
 187 (defun js2-imenu-record-module-pattern (node)
 188   "Recognize and record module pattern use instance.
 189 NODE must be `js2-assign-node'."
 190   (let ((init (js2-assign-node-right node)))
 191     (when (js2-call-node-p init)
 192       (let ((target (js2-assign-node-left node))
 193             (callt (js2-call-node-target init)))
 194         ;; Just basic call form: (function() {...})();
 195         ;; TODO: Handle variations without duplicating `js2-wrapper-function-p'?
 196         (when (and (js2-paren-node-p callt)
 197                    (js2-function-node-p (js2-paren-node-expr callt)))
 198           (let* ((fn (js2-paren-node-expr callt))
 199                  (blk (js2-function-node-body fn))
 200                  (ret (car (last (js2-block-node-kids blk)))))
 201             (when (and (js2-return-node-p ret)
 202                        (js2-object-node-p (js2-return-node-retval ret)))
 203               ;; TODO: Map function names when revealing module pattern is used.
 204               (let ((retval (js2-return-node-retval ret))
 205                     (target-qname (js2-compute-nested-prop-get target)))
 206                 (js2-record-object-literal retval target-qname
 207                                            (js2-node-abs-pos retval))
 208                 (js2-record-imenu-entry fn target-qname
 209                                         (js2-node-abs-pos target))))))))))
 210
 211 (provide 'js2-imenu-extras)