1 ;;; js2-imenu-extras.el --- Imenu support for additional constructs
3 ;; Copyright (C) 2012-2014 Free Software Foundation, Inc.
5 ;; Author: Dmitry Gutov <dgutov@yandex.ru>
6 ;; Keywords: languages, javascript, imenu
8 ;; This file is part of GNU Emacs.
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.
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.
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/>.
25 ;; This package adds Imenu support for additional framework constructs and
26 ;; structural patterns to `js2-mode'.
30 ;; (add-hook 'js2-mode-hook 'js2-imenu-extras-mode)
32 ;; To customize how it works:
33 ;; M-x customize-group RET js2-imenu RET
40 (defvar js2-imenu-extension-styles
42 :call-re "\\_<\\(?:jQuery\\|\\$\\|_\\)\\.extend\\s-*("
43 :recorder js2-imenu-record-jquery-extend)
46 :call-re "^\\s-*\\(?:jQuery\\|\\$\\)\\.widget\\s-*("
47 :recorder js2-imenu-record-string-declare)
50 :call-re "^\\s-*dojo.declare\\s-*("
51 :recorder js2-imenu-record-string-declare)
54 :call-re ,(concat "\\_<" js2-mode-identifier-re "\\.extend\\s-*(")
55 :recorder js2-imenu-record-backbone-extend)
58 :call-re "\\_<enyo\\.kind\\s-*("
59 :recorder js2-imenu-record-enyo-kind)
62 :call-re "\\_<React\\.createClass\\s-*("
63 :recorder js2-imenu-record-react-class)
66 :call-re "^\\s-*Ext\\.define\\s-*("
67 :recorder js2-imenu-record-sencha-class))
68 "List of JavaScript class definition or extension styles.
70 :framework is a valid value in `js2-imenu-enabled-frameworks'.
72 :call-re is a regular expression that has no capturing groups.
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.")
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.")
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))
88 (defcustom js2-imenu-show-other-functions t
89 "Non-nil to show functions not recognized by other mechanisms,
90 in a shared namespace."
94 (defcustom js2-imenu-other-functions-ns "?"
95 "Namespace name to use for other functions."
99 (defcustom js2-imenu-show-module-pattern t
100 "Non-nil to recognize the module pattern:
102 var foobs = (function(a) {
103 return {fib: function() {}, fub: function() {}};
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."
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."
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)))
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))
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)
133 (re (mapconcat (lambda (style)
134 (concat "\\(" (plist-get style :call-re) "\\)"))
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))))))
142 (defun js2-imenu-record-jquery-extend ()
143 (let ((pred (lambda (subject)
145 (js2-prop-get-node-p subject)
146 (string= (js2-name-node-name (js2-prop-get-node-right subject))
148 (js2-imenu-record-extend-first-arg (1- (point)) pred
149 'js2-compute-nested-prop-get)))
151 (defun js2-imenu-record-string-declare ()
152 (js2-imenu-record-extend-first-arg
153 (1- (point)) 'js2-string-node-p
155 (if js2-imenu-split-string-identifiers
156 (split-string (js2-string-node-value node) "\\." t)
157 (list (js2-string-node-value node))))))
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))))))
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)))))
180 (js2-record-object-literal methods
181 (js2-compute-nested-prop-get subject)
182 (js2-node-abs-pos methods)))))))
184 (defalias 'js2-imenu-record-backbone-extend 'js2-imenu-record-backbone-or-react)
186 (defalias 'js2-imenu-record-react-class 'js2-imenu-record-backbone-or-react)
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)
194 (loop for elem in (js2-object-node-elems options)
196 (let ((key (js2-object-prop-node-left elem))
197 (value (js2-object-prop-node-right elem)))
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)))
204 (js2-string-node-p value))
205 (js2-string-node-value value))))))
207 (js2-record-object-literal options
208 (if js2-imenu-split-string-identifiers
209 (split-string name-value "\\.")
211 (js2-node-abs-pos options)))))))
213 (defun js2-imenu-record-sencha-class ()
214 (let* ((node (js2-node-at-point (1- (point))))
215 (args (js2-call-node-args node))
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)
224 (js2-node-abs-pos methods))))))
226 (defun js2-imenu-walk-ast ()
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)
237 ((and js2-imenu-show-other-functions
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
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)
251 ((and js2-imenu-show-other-functions
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
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))))))
265 (defun js2-imenu-parent-key-names (node)
266 "Get the list of parent key names of NODE.
268 For example, for code
270 {rules: {password: {required: function() {}}}}
272 when NODE is the inner `js2-object-prop-mode',
273 it returns (\"rules\" \"password\")."
275 (while (setq n (js2-imenu-parent-prop-node n))
276 (push (js2-prop-node-name (js2-object-prop-node-left n)) rlt))
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() {}'.
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))))
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))
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)))))))
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)
314 (gethash fn-node js2-imenu-function-map 'skip)))
315 (let ((chain (js2-compute-nested-prop-get target-node)))
317 (push js2-imenu-other-functions-ns chain)
318 (js2-record-imenu-entry fn-node chain (js2-node-abs-pos fn-node))))))
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))))))))
342 (define-minor-mode js2-imenu-extras-mode
343 "Toggle Imenu support for frameworks and structural patterns."
345 (if js2-imenu-extras-mode
346 (js2-imenu-extras-setup)
347 (js2-imenu-extras-remove)))
349 (provide 'js2-imenu-extras)