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 (defvar 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
 241             (js2-assign-node-left node)
 242             (js2-assign-node-right node)))
 243           ((and js2-imenu-show-module-pattern
 244                 (js2-call-node-p
 245                  (js2-assign-node-right node)))
 246            (js2-imenu-record-module-pattern
 247             (js2-assign-node-left node)
 248             (js2-assign-node-right node)))))
 249         ((js2-var-init-node-p node)
 250          (cond
 251           ((and js2-imenu-show-other-functions
 252                 (js2-function-node-p
 253                  (js2-var-init-node-initializer node)))
 254            (js2-imenu-record-orphan-assign-node-function
 255             (js2-var-init-node-target node)
 256             (js2-var-init-node-initializer node)))
 257           ((and js2-imenu-show-module-pattern
 258                 (js2-call-node-p
 259                  (js2-var-init-node-initializer node)))
 260            (js2-imenu-record-module-pattern
 261             (js2-var-init-node-target node)
 262             (js2-var-init-node-initializer node))))))
 263        t))))
 264
 265 (defun js2-imenu-parent-key-names (node)
 266   "Get the list of parent key names of NODE.
 267
 268 For example, for code
 269
 270   {rules: {password: {required: function() {}}}}
 271
 272 when NODE is the inner `js2-object-prop-mode',
 273 it returns `(\"rules\" \"password\")'."
 274   (let (rlt (n node))
 275     (while (setq n (js2-imenu-parent-prop-node n))
 276       (push (js2-prop-node-name (js2-object-prop-node-left n)) rlt))
 277     rlt))
 278
 279 (defun js2-imenu-parent-prop-node (node)
 280   "When the parent of NODE is `js2-object-node',
 281 and the grandparent is `js2-object-prop-node',
 282 return the grandparent."
 283   ;; Suppose the code is:
 284   ;; {parent-key: {required: function() {}}}
 285   ;; NODE is `required: function() {}'.
 286   (let (p2 p3)
 287     ;; Parent is `{required: function() {}}'.
 288     (setq p2 (js2-node-parent node))
 289     ;; GP is `parent-key: {required: function() {}}'.
 290     (when (and p2 (js2-object-node-p p2))
 291       (setq p3 (js2-node-parent p2))
 292       (if (and p3 (js2-object-prop-node-p p3)) p3))))
 293
 294 (defun js2-imenu-record-orphan-prop-node-function (node)
 295   "Record orphan function when it's the value of NODE.
 296 NODE must be `js2-object-prop-node'."
 297   (when (js2-function-node-p (js2-object-prop-node-right node))
 298     (let ((fn-node (js2-object-prop-node-right node)))
 299       (unless (and js2-imenu-function-map
 300                    (gethash fn-node js2-imenu-function-map))
 301         (let ((key-node (js2-object-prop-node-left node))
 302               (parent-prop-node (js2-imenu-parent-prop-node node))
 303               chain)
 304           (setq chain (nconc (js2-imenu-parent-key-names node)
 305                              (list (js2-prop-node-name key-node))))
 306           (push js2-imenu-other-functions-ns chain)
 307           (js2-record-imenu-entry fn-node chain
 308                                   (js2-node-abs-pos key-node)))))))
 309
 310 (defun js2-imenu-record-orphan-assign-node-function (target-node fn-node)
 311   "Record orphan function FN-NODE assigned to node TARGET."
 312   (when (or (not js2-imenu-function-map)
 313             (eq 'skip
 314                 (gethash fn-node js2-imenu-function-map 'skip)))
 315     (let ((chain (js2-compute-nested-prop-get target-node)))
 316       (when chain
 317         (push js2-imenu-other-functions-ns chain)
 318         (js2-record-imenu-entry fn-node chain (js2-node-abs-pos fn-node))))))
 319
 320 (defun js2-imenu-record-module-pattern (target init)
 321   "Recognize and record module pattern use instance.
 322 INIT must be `js2-call-node'."
 323   (let ((callt (js2-call-node-target init)))
 324     ;; Just basic call form: (function() {...})();
 325     ;; TODO: Handle variations without duplicating `js2-wrapper-function-p'?
 326     (when (and (js2-paren-node-p callt)
 327                (js2-function-node-p (js2-paren-node-expr callt)))
 328       (let* ((fn (js2-paren-node-expr callt))
 329              (blk (js2-function-node-body fn))
 330              (ret (car (last (js2-block-node-kids blk)))))
 331         (when (and (js2-return-node-p ret)
 332                    (js2-object-node-p (js2-return-node-retval ret)))
 333           ;; TODO: Map function names when revealing module pattern is used.
 334           (let ((retval (js2-return-node-retval ret))
 335                 (target-qname (js2-compute-nested-prop-get target)))
 336             (js2-record-object-literal retval target-qname
 337                                        (js2-node-abs-pos retval))
 338             (js2-record-imenu-entry fn target-qname
 339                                     (js2-node-abs-pos target))))))))
 340
 341 ;;;###autoload
 342 (define-minor-mode js2-imenu-extras-mode
 343   "Toggle Imenu support for frameworks and structural patterns."
 344   :lighter ""
 345   (if js2-imenu-extras-mode
 346       (js2-imenu-extras-setup)
 347     (js2-imenu-extras-remove)))
 348
 349 (provide 'js2-imenu-extras)