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