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

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