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-2014  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
  61     (:framework react
  62      :call-re "\\_<React\\.createClass\\s-*("
  63      :recorder js2-imenu-record-react-class)
  64
  65     (:framework sencha
  66      :call-re "^\\s-*Ext\\.define\\s-*("
  67      :recorder js2-imenu-record-sencha-class))
  68   "List of JavaScript class definition or extension styles.
  69
  70 :framework is a valid value in `js2-imenu-enabled-frameworks'.
  71
  72 :call-re is a regular expression that has no capturing groups.
  73
  74 :recorder is a function name that will be called when the regular
  75 expression matches some text in the buffer.  When it's called, point will be
  76 at the end of the match.  The function must keep the point position.")
  77
  78 (defconst js2-imenu-available-frameworks
  79   (mapcar (lambda (style) (plist-get style :framework)) js2-imenu-extension-styles)
  80   "List of available JavaScript framework symbols.")
  81
  82 (defcustom js2-imenu-enabled-frameworks js2-imenu-available-frameworks
  83   "Frameworks to be recognized by `js2-mode'."
  84   :type (cons 'set (mapcar (lambda (x) (list 'const x))
  85                            js2-imenu-available-frameworks))
  86   :group 'js2-imenu)
  87
  88 (defcustom js2-imenu-show-other-functions t
  89   "Non-nil to show functions not recognized by other mechanisms,
  90 in a shared namespace."
  91   :type 'boolean
  92   :group 'js2-imenu)
  93
  94 (defcustom js2-imenu-other-functions-ns "?"
  95   "Namespace name to use for other functions."
  96   :type 'string
  97   :group 'js2-imenu)
  98
  99 (defcustom js2-imenu-show-module-pattern t
 100   "Non-nil to recognize the module pattern:
 101
 102 var foobs = (function(a) {
 103   return {fib: function() {}, fub: function() {}};
 104 })(b);
 105
 106 We record the returned hash as belonging to the named module, and
 107 prefix any functions defined inside the IIFE with the module name."
 108   :type 'boolean
 109   :group 'js2-imenu)
 110
 111 (defcustom js2-imenu-split-string-identifiers t
 112   "When non-nil, split string identifiers on dots.
 113 Currently used for jQuery widgets, Dojo and Enyo declarations."
 114   :type 'boolean
 115   :group 'js2-imenu)
 116
 117 ;;;###autoload
 118 (defun js2-imenu-extras-setup ()
 119   (when js2-imenu-enabled-frameworks
 120     (add-hook 'js2-build-imenu-callbacks 'js2-imenu-record-declarations t t))
 121   (when (or js2-imenu-show-other-functions js2-imenu-show-module-pattern)
 122     (add-hook 'js2-build-imenu-callbacks 'js2-imenu-walk-ast t t)))
 123
 124 (defun js2-imenu-extras-remove ()
 125   (remove-hook 'js2-build-imenu-callbacks 'js2-imenu-record-declarations t)
 126   (remove-hook 'js2-build-imenu-callbacks 'js2-imenu-walk-ast t))
 127
 128 (defun js2-imenu-record-declarations ()
 129   (let* ((styles (loop for style in js2-imenu-extension-styles
 130                        when (memq (plist-get style :framework)
 131                                   js2-imenu-enabled-frameworks)
 132                        collect style))
 133          (re (mapconcat (lambda (style)
 134                           (concat "\\(" (plist-get style :call-re) "\\)"))
 135                         styles "\\|")))
 136     (goto-char (point-min))
 137     (while (js2-re-search-forward re nil t)
 138       (loop for i from 0 to (1- (length styles))
 139             when (match-beginning (1+ i))
 140             return (funcall (plist-get (nth i styles) :recorder))))))
 141
 142 (defun js2-imenu-record-jquery-extend ()
 143   (let ((pred (lambda (subject)
 144                 (and
 145                  (js2-prop-get-node-p subject)
 146                  (string= (js2-name-node-name (js2-prop-get-node-right subject))
 147                           "prototype")))))
 148     (js2-imenu-record-extend-first-arg (1- (point)) pred
 149                                        'js2-compute-nested-prop-get)))
 150
 151 (defun js2-imenu-record-string-declare ()
 152   (js2-imenu-record-extend-first-arg
 153    (1- (point)) 'js2-string-node-p
 154    (lambda (node)
 155      (if js2-imenu-split-string-identifiers
 156          (split-string (js2-string-node-value node) "\\." t)
 157        (list (js2-string-node-value node))))))
 158
 159 (defun js2-imenu-record-extend-first-arg (point pred qname-fn)
 160   (let* ((node (js2-node-at-point point))
 161          (args (js2-call-node-args node))
 162          (subject (first args)))
 163     (when (funcall pred subject)
 164       (loop for arg in (cdr args)
 165             when (js2-object-node-p arg)
 166             do (js2-record-object-literal
 167                 arg (funcall qname-fn subject) (js2-node-abs-pos arg))))))
 168
 169 (defun js2-imenu-record-backbone-or-react ()
 170   (let* ((node (js2-node-at-point (1- (point))))
 171          (args (js2-call-node-args node))
 172          (methods (first args))
 173          (parent (js2-node-parent node)))
 174     (when (js2-object-node-p methods)
 175       (let ((subject (cond ((js2-var-init-node-p parent)
 176                             (js2-var-init-node-target parent))
 177                            ((js2-assign-node-p parent)
 178                             (js2-assign-node-left parent)))))
 179         (when subject
 180           (js2-record-object-literal methods
 181                                      (js2-compute-nested-prop-get subject)
 182                                      (js2-node-abs-pos methods)))))))
 183
 184 (defalias 'js2-imenu-record-backbone-extend 'js2-imenu-record-backbone-or-react)
 185
 186 (defalias 'js2-imenu-record-react-class 'js2-imenu-record-backbone-or-react)
 187
 188 (defun js2-imenu-record-enyo-kind ()
 189   (let* ((node (js2-node-at-point (1- (point))))
 190          (args (js2-call-node-args node))
 191          (options (first args)))
 192     (when (js2-object-node-p options)
 193       (let ((name-value
 194              (loop for elem in (js2-object-node-elems options)
 195                    thereis
 196                    (let ((key (js2-object-prop-node-left elem))
 197                          (value (js2-object-prop-node-right elem)))
 198                      (when (and (equal
 199                                  (cond ((js2-name-node-p key)
 200                                         (js2-name-node-name key))
 201                                        ((js2-string-node-p key)
 202                                         (js2-string-node-value key)))
 203                                  "name")
 204                                 (js2-string-node-p value))
 205                        (js2-string-node-value value))))))
 206         (when name-value
 207           (js2-record-object-literal options
 208                                      (if js2-imenu-split-string-identifiers
 209                                          (split-string name-value "\\.")
 210                                        (list name-value))
 211                                      (js2-node-abs-pos options)))))))
 212
 213 (defun js2-imenu-record-sencha-class ()
 214   (let* ((node (js2-node-at-point (1- (point))))
 215          (args (js2-call-node-args node))
 216          (name (first args))
 217          (methods (second args)))
 218     (when (and (js2-string-node-p name) (js2-object-node-p methods))
 219       (let ((name-value (js2-string-node-value name)))
 220         (js2-record-object-literal methods
 221                                    (if js2-imenu-split-string-identifiers
 222                                        (split-string name-value "\\." t)
 223                                      (list name-value))
 224                                    (js2-node-abs-pos methods))))))
 225
 226 (defun js2-imenu-walk-ast ()
 227   (js2-visit-ast
 228    js2-mode-ast
 229    (lambda (node end-p)
 230      (unless end-p
 231        (cond
 232         ((and js2-imenu-show-other-functions
 233               (js2-object-prop-node-p node))
 234          (js2-imenu-record-orphan-prop-node-function node))
 235         ((js2-assign-node-p node)
 236          (cond
 237           ((and js2-imenu-show-other-functions
 238                 (js2-function-node-p
 239                  (js2-assign-node-right node)))
 240            (js2-imenu-record-orphan-assign-node-function node))
 241           (js2-imenu-show-module-pattern
 242            (js2-imenu-record-module-pattern node)))))
 243        t))))
 244
 245 (defun js2-imenu-parent-key-names (node)
 246   "Get the list of parent key names of NODE.
 247
 248 For example, for code
 249
 250   {rules: {password: {required: function() {}}}}
 251
 252 when NODE is the inner `js2-object-prop-mode',
 253 it returns `(\"rules\" \"password\")'."
 254   (let (rlt (n node))
 255     (while (setq n (js2-imenu-parent-prop-node n))
 256       (push (js2-prop-node-name (js2-object-prop-node-left n)) rlt))
 257     rlt))
 258
 259 (defun js2-imenu-parent-prop-node (node)
 260   "When the parent of NODE is `js2-object-node',
 261 and the grandparent is `js2-object-prop-node',
 262 return the grandparent."
 263   ;; Suppose the code is:
 264   ;; {parent-key: {required: function() {}}}
 265   ;; NODE is `required: function() {}'.
 266   (let (p2 p3)
 267     ;; Parent is `{required: function() {}}'.
 268     (setq p2 (js2-node-parent node))
 269     ;; GP is `parent-key: {required: function() {}}'.
 270     (when (and p2 (js2-object-node-p p2))
 271       (setq p3 (js2-node-parent p2))
 272       (if (and p3 (js2-object-prop-node-p p3)) p3))))
 273
 274 (defun js2-imenu-record-orphan-prop-node-function (node)
 275   "Record orphan function when it's the value of NODE.
 276 NODE must be `js2-object-prop-node'."
 277   (when (js2-function-node-p (js2-object-prop-node-right node))
 278     (let ((fn-node (js2-object-prop-node-right node)))
 279       (unless (and js2-imenu-function-map
 280                    (gethash fn-node js2-imenu-function-map))
 281         (let ((key-node (js2-object-prop-node-left node))
 282               (parent-prop-node (js2-imenu-parent-prop-node node))
 283               chain)
 284           (setq chain (nconc (js2-imenu-parent-key-names node)
 285                              (list (js2-prop-node-name key-node))))
 286           (push js2-imenu-other-functions-ns chain)
 287           (js2-record-imenu-entry fn-node chain
 288                                   (js2-node-abs-pos key-node)))))))
 289
 290 (defun js2-imenu-record-orphan-assign-node-function (node)
 291   "Return orphan function entry when it's the right hand of NODE.
 292 NODE must be `js2-assign-node'."
 293   (let ((fn-node (js2-assign-node-right node)))
 294     (when (or (not js2-imenu-function-map)
 295               (eq 'skip
 296                   (gethash fn-node js2-imenu-function-map 'skip)))
 297       (let* ((target-node (js2-assign-node-left node))
 298              (chain (js2-compute-nested-prop-get target-node)))
 299         (when chain
 300           (push js2-imenu-other-functions-ns chain)
 301           (js2-record-imenu-entry fn-node chain (js2-node-abs-pos fn-node)))))))
 302
 303 (defun js2-imenu-record-module-pattern (node)
 304   "Recognize and record module pattern use instance.
 305 NODE must be `js2-assign-node'."
 306   (let ((init (js2-assign-node-right node)))
 307     (when (js2-call-node-p init)
 308       (let ((target (js2-assign-node-left node))
 309             (callt (js2-call-node-target init)))
 310         ;; Just basic call form: (function() {...})();
 311         ;; TODO: Handle variations without duplicating `js2-wrapper-function-p'?
 312         (when (and (js2-paren-node-p callt)
 313                    (js2-function-node-p (js2-paren-node-expr callt)))
 314           (let* ((fn (js2-paren-node-expr callt))
 315                  (blk (js2-function-node-body fn))
 316                  (ret (car (last (js2-block-node-kids blk)))))
 317             (when (and (js2-return-node-p ret)
 318                        (js2-object-node-p (js2-return-node-retval ret)))
 319               ;; TODO: Map function names when revealing module pattern is used.
 320               (let ((retval (js2-return-node-retval ret))
 321                     (target-qname (js2-compute-nested-prop-get target)))
 322                 (js2-record-object-literal retval target-qname
 323                                            (js2-node-abs-pos retval))
 324                 (js2-record-imenu-entry fn target-qname
 325                                         (js2-node-abs-pos target))))))))))
 326
 327 ;;;###autoload
 328 (define-minor-mode js2-imenu-extras-mode
 329   "Toggle Imenu support for frameworks and structural patterns."
 330   :lighter ""
 331   (if js2-imenu-extras-mode
 332       (js2-imenu-extras-setup)
 333     (js2-imenu-extras-remove)))
 334
 335 (provide 'js2-imenu-extras)