1 ;;; semantic/symref.el --- Symbol Reference API
3 ;;; Copyright (C) 2008, 2009 Free Software Foundation, Inc.
5 ;; Author: Eric M. Ludlam <eric@siege-engine.com>
7 ;; This file is part of GNU Emacs.
9 ;; GNU Emacs is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;; Semantic Symbol Reference API.
26 ;; Semantic's native parsing tools do not handle symbol references.
27 ;; Tracking such information is a task that requires a huge amount of
28 ;; space and processing not apropriate for an Emacs Lisp program.
30 ;; Many desired tools used in refactoring, however, need to have
31 ;; such references available to them. This API aims to provide a
32 ;; range of functions that can be used to identify references. The
33 ;; API is backed by an OO system that is used to allow multiple
34 ;; external tools to provide the information.
36 ;; The default implementation uses a find/grep combination to do a
37 ;; search. This works ok in small projects. For larger projects, it
38 ;; is important to find an alternate tool to use as a back-end to
41 ;; See the command: `semantic-symref' for an example app using this api.
45 ;; The following functions can be used to find different kinds of
48 ;; `semantic-symref-find-references-by-name'
49 ;; `semantic-symref-find-file-references-by-name'
50 ;; `semantic-symref-find-text'
52 ;; All the search routines return a class of type
53 ;; `semantic-symref-result'. You can reference the various slots, but
54 ;; you will need the following methods to get extended information.
56 ;; `semantic-symref-result-get-files'
57 ;; `semantic-symref-result-get-tags'
59 ;; ADD A NEW EXTERNAL TOOL
61 ;; To support a new external tool, sublcass `semantic-symref-tool-baseclass'
62 ;; and implement the methods. The baseclass provides support for
63 ;; managing external processes that produce parsable output.
65 ;; Your tool should then create an instance of `semantic-symref-result'.
71 (defvar ede-minor-mode
)
72 (declare-function data-debug-new-buffer
"data-debug")
73 (declare-function data-debug-insert-object-slots
"eieio-datadebug")
74 (declare-function ede-toplevel
"ede/files")
75 (declare-function ede-project-root-directory
"ede/files")
78 (defvar semantic-symref-tool
'detect
79 "*The active symbol reference tool name.
80 The tool symbol can be 'detect, or a symbol that is the name of
81 a tool that can be used for symbol referencing.")
82 (make-variable-buffer-local 'semantic-symref-tool
)
86 (defvar semantic-symref-tool-alist
87 '( ( (lambda (rootdir) (file-exists-p (expand-file-name "GPATH" rootdir
))) .
89 ( (lambda (rootdir) (file-exists-p (expand-file-name "ID" rootdir
))) .
91 ( (lambda (rootdir) (file-exists-p (expand-file-name "cscope.out" rootdir
))) .
94 "Alist of tools usable by `semantic-symref'.
95 Each entry is of the form:
97 Where PREDICATE is a function that takes a directory name for the
98 root of a project, and returns non-nil if the tool represented by KEY
101 If no tools are supported, then 'grep is assumed.")
103 (defun semantic-symref-detect-symref-tool ()
104 "Detect the symref tool to use for the current buffer."
105 (if (not (eq semantic-symref-tool
'detect
))
107 ;; We are to perform a detection for the right tool to use.
108 (let* ((rootproj (when (and (featurep 'ede
) ede-minor-mode
)
110 (rootdir (if rootproj
111 (ede-project-root-directory rootproj
)
113 (tools semantic-symref-tool-alist
))
114 (while (and tools
(eq semantic-symref-tool
'detect
))
115 (when (funcall (car (car tools
)) rootdir
)
116 (setq semantic-symref-tool
(cdr (car tools
))))
117 (setq tools
(cdr tools
)))
119 (when (eq semantic-symref-tool
'detect
)
120 (setq semantic-symref-tool
'grep
))
122 semantic-symref-tool
)))
124 (defun semantic-symref-instantiate (&rest args
)
125 "Instantiate a new symref search object.
126 ARGS are the initialization arguments to pass to the created class."
127 (let* ((srt (symbol-name (semantic-symref-detect-symref-tool)))
128 (class (intern-soft (concat "semantic-symref-tool-" srt
)))
131 (when (not (class-p class
))
132 (error "Unknown symref tool %s" semantic-symref-tool
))
133 (setq inst
(apply 'make-instance class args
))
136 (defvar semantic-symref-last-result nil
137 "The last calculated symref result.")
139 (defun semantic-symref-data-debug-last-result ()
140 "Run the last symref data result in Data Debug."
142 (require 'eieio-datadebug
)
143 (if semantic-symref-last-result
145 (data-debug-new-buffer "*Symbol Reference ADEBUG*")
146 (data-debug-insert-object-slots semantic-symref-last-result
"]"))
147 (message "Empty results.")))
153 (defun semantic-symref-find-references-by-name (name &optional scope tool-return
)
154 "Find a list of references to NAME in the current project.
155 Optional SCOPE specifies which file set to search. Defaults to 'project.
156 Refers to `semantic-symref-tool', to determine the reference tool to use
157 for the current buffer.
158 Returns an object of class `semantic-symref-result'.
159 TOOL-RETURN is an optional symbol, which will be assigned the tool used
160 to perform the search. This was added for use by a test harness."
161 (interactive "sName: ")
162 (let* ((inst (semantic-symref-instantiate
165 :searchscope
(or scope
'project
)
167 (result (semantic-symref-get-result inst
)))
169 (set tool-return inst
))
171 (setq semantic-symref-last-result result
)
172 (when (interactive-p)
173 (semantic-symref-data-debug-last-result))))
177 (defun semantic-symref-find-tags-by-name (name &optional scope
)
178 "Find a list of references to NAME in the current project.
179 Optional SCOPE specifies which file set to search. Defaults to 'project.
180 Refers to `semantic-symref-tool', to determine the reference tool to use
181 for the current buffer.
182 Returns an object of class `semantic-symref-result'."
183 (interactive "sName: ")
184 (let* ((inst (semantic-symref-instantiate
187 :searchscope
(or scope
'project
)
189 (result (semantic-symref-get-result inst
)))
191 (setq semantic-symref-last-result result
)
192 (when (interactive-p)
193 (semantic-symref-data-debug-last-result))))
197 (defun semantic-symref-find-tags-by-regexp (name &optional scope
)
198 "Find a list of references to NAME in the current project.
199 Optional SCOPE specifies which file set to search. Defaults to 'project.
200 Refers to `semantic-symref-tool', to determine the reference tool to use
201 for the current buffer.
202 Returns an object of class `semantic-symref-result'."
203 (interactive "sName: ")
204 (let* ((inst (semantic-symref-instantiate
206 :searchtype
'tagregexp
207 :searchscope
(or scope
'project
)
209 (result (semantic-symref-get-result inst
)))
211 (setq semantic-symref-last-result result
)
212 (when (interactive-p)
213 (semantic-symref-data-debug-last-result))))
217 (defun semantic-symref-find-tags-by-completion (name &optional scope
)
218 "Find a list of references to NAME in the current project.
219 Optional SCOPE specifies which file set to search. Defaults to 'project.
220 Refers to `semantic-symref-tool', to determine the reference tool to use
221 for the current buffer.
222 Returns an object of class `semantic-symref-result'."
223 (interactive "sName: ")
224 (let* ((inst (semantic-symref-instantiate
226 :searchtype
'tagcompletions
227 :searchscope
(or scope
'project
)
229 (result (semantic-symref-get-result inst
)))
231 (setq semantic-symref-last-result result
)
232 (when (interactive-p)
233 (semantic-symref-data-debug-last-result))))
237 (defun semantic-symref-find-file-references-by-name (name &optional scope
)
238 "Find a list of references to NAME in the current project.
239 Optional SCOPE specifies which file set to search. Defaults to 'project.
240 Refers to `semantic-symref-tool', to determine the reference tool to use
241 for the current buffer.
242 Returns an object of class `semantic-symref-result'."
243 (interactive "sName: ")
244 (let* ((inst (semantic-symref-instantiate
247 :searchscope
(or scope
'project
)
249 (result (semantic-symref-get-result inst
)))
251 (setq semantic-symref-last-result result
)
252 (when (interactive-p)
253 (semantic-symref-data-debug-last-result))))
257 (defun semantic-symref-find-text (text &optional scope
)
258 "Find a list of occurances of TEXT in the current project.
259 TEXT is a regexp formatted for use with egrep.
260 Optional SCOPE specifies which file set to search. Defaults to 'project.
261 Refers to `semantic-symref-tool', to determine the reference tool to use
262 for the current buffer.
263 Returns an object of class `semantic-symref-result'."
264 (interactive "sEgrep style Regexp: ")
265 (let* ((inst (semantic-symref-instantiate
268 :searchscope
(or scope
'project
)
270 (result (semantic-symref-get-result inst
)))
272 (setq semantic-symref-last-result result
)
273 (when (interactive-p)
274 (semantic-symref-data-debug-last-result))))
279 ;; The results class and methods provide features for accessing hits.
280 (defclass semantic-symref-result
()
281 ((created-by :initarg
:created-by
282 :type semantic-symref-tool-baseclass
284 "Back-pointer to the symref tool creating these results.")
285 (hit-files :initarg
:hit-files
288 "The list of files hit.")
289 (hit-text :initarg
:hit-text
292 "If the result doesn't provide full lines, then fill in hit-text.
293 GNU Global does completion search this way.")
294 (hit-lines :initarg
:hit-lines
297 "The list of line hits.
298 Each element is a cons cell of the form (LINE . FILENAME).")
299 (hit-tags :initarg
:hit-tags
302 "The list of tags with hits in them.
303 Use the `semantic-symref-hit-tags' method to get this list.")
305 "The results from a symbol reference search.")
307 (defmethod semantic-symref-result-get-files ((result semantic-symref-result
))
308 "Get the list of files from the symref result RESULT."
309 (if (slot-boundp result
:hit-files
)
310 (oref result hit-files
)
311 (let* ((lines (oref result
:hit-lines
))
312 (files (mapcar (lambda (a) (cdr a
)) lines
))
314 (setq ans
(list (car files
))
317 ;; This algorithm for uniqing the file list depends on the
318 ;; tool in question providing all the hits in the same file
320 (when (not (string= F
(car ans
)))
321 (setq ans
(cons F ans
))))
322 (oset result hit-files
(nreverse ans
))
326 (defmethod semantic-symref-result-get-tags ((result semantic-symref-result
)
327 &optional open-buffers
)
328 "Get the list of tags from the symref result RESULT.
329 Optional OPEN-BUFFERS indicates that the buffers that the hits are
330 in should remain open after scanning.
331 Note: This can be quite slow if most of the hits are not in buffers
333 (if (and (slot-boundp result
:hit-tags
) (oref result hit-tags
))
334 (oref result hit-tags
)
335 ;; Calculate the tags.
336 (let ((lines (oref result
:hit-lines
))
337 (txt (oref (oref result
:created-by
) :searchfor
))
338 (searchtype (oref (oref result
:created-by
) :searchtype
))
347 (let* ((line (car hit
))
349 (buff (get-file-buffer file
))
353 ;; We have a buffer already. Check it out.
357 ;; We have a table, but it needs a refresh.
358 ;; This means we should load in that buffer.
362 ;; Even if we keep the buffers open, don't
363 ;; let EDE ask lots of questions.
364 (let ((ede-auto-add-method 'never
))
365 (find-file-noselect file t
))
366 ;; When not keeping the buffers open, then
367 ;; don't setup all the fancy froo-froo features
369 (semantic-find-file-noselect file t
))))
371 (setq buffs-to-kill
(cons kbuff buffs-to-kill
))
372 (semantic-fetch-tags)
376 ;; Too much baggage in goto-line
378 (goto-char (point-min))
379 (forward-line (1- line
))
381 ;; Search forward for the matching text
382 (re-search-forward (regexp-quote txt
)
386 (setq tag
(semantic-current-tag))
388 ;; If we are searching for a tag, but bound the tag we are looking
389 ;; for, see if it resides in some other parent tag.
391 ;; If there is no parent tag, then we still need to hang the originator
393 (when (and (eq searchtype
'symbol
)
394 (string= (semantic-tag-name tag
) txt
))
395 (setq tag
(or (semantic-current-tag-parent) tag
)))
397 ;; Copy the tag, which adds a :filename property.
399 (setq tag
(semantic-tag-copy tag nil t
))
400 ;; Ad this hit to the tag.
401 (semantic--tag-put-property tag
:hit
(list line
)))
404 ;; Kill off dead buffers, unless we were requested to leave them open.
405 (when (not open-buffers
)
406 (mapc 'kill-buffer buffs-to-kill
))
407 ;; Strip out duplicates.
409 (if (and T
(not (semantic-equivalent-tag-p (car out
) T
)))
410 (setq out
(cons T out
))
412 ;; Else, add this line into the existing list of lines.
413 (let ((lines (append (semantic--tag-get-property (car out
) :hit
)
414 (semantic--tag-get-property T
:hit
))))
415 (semantic--tag-put-property (car out
) :hit lines
)))
417 ;; Out is reversed... twice
418 (oset result
:hit-tags
(nreverse out
)))))
422 ;; The base symref tool provides something to hang new tools off of
423 ;; for finding symbol references.
424 (defclass semantic-symref-tool-baseclass
()
425 ((searchfor :initarg
:searchfor
427 :documentation
"The thing to search for.")
428 (searchtype :initarg
:searchtype
430 :documentation
"The type of search to do.
431 Values could be `symbol, `regexp, 'tagname, or 'completion.")
432 (searchscope :initarg
:searchscope
435 "The scope to search for.
436 Can be 'project, 'target, or 'file.")
437 (resulttype :initarg
:resulttype
440 "The kind of search results desired.
441 Can be 'line, 'file, or 'tag.
442 The type of result can be converted from 'line to 'file, or 'line to 'tag,
443 but not from 'file to 'line or 'tag.")
445 "Baseclass for all symbol references tools.
446 A symbol reference tool supplies functionality to identify the locations of
447 where different symbols are used.
449 Subclasses should be named `semantic-symref-tool-NAME', where
450 NAME is the name of the tool used in the configuration variable
451 `semantic-symref-tool'"
454 (defmethod semantic-symref-get-result ((tool semantic-symref-tool-baseclass
))
455 "Calculate the results of a search based on TOOL.
456 The symref TOOL should already contain the search criteria."
457 (let ((answer (semantic-symref-perform-search tool
))
460 (let ((answersym (if (eq (oref tool
:resulttype
) 'file
)
462 (if (stringp (car answer
))
465 (semantic-symref-result (oref tool searchfor
)
472 (defmethod semantic-symref-perform-search ((tool semantic-symref-tool-baseclass
))
473 "Base search for symref tools should throw an error."
474 (error "Symref tool objects must implement `semantic-symref-perform-search'"))
476 (defmethod semantic-symref-parse-tool-output ((tool semantic-symref-tool-baseclass
)
478 "Parse the entire OUTPUTBUFFER of a symref tool.
479 Calls the method `semantic-symref-parse-tool-output-one-line' over and
480 over until it returns nil."
482 (set-buffer outputbuffer
)
483 (goto-char (point-min))
486 (while (setq hit
(semantic-symref-parse-tool-output-one-line tool
))
487 (setq result
(cons hit result
)))
491 (defmethod semantic-symref-parse-tool-output-one-line ((tool semantic-symref-tool-baseclass
))
492 "Base tool output parser is not implemented."
493 (error "Symref tool objects must implement `semantic-symref-parse-tool-output-one-line'"))
495 (provide 'semantic
/symref
)
498 ;; generated-autoload-file: "loaddefs.el"
499 ;; generated-autoload-feature: semantic/loaddefs
500 ;; generated-autoload-load-name: "semantic/symref"
503 ;;; semantic/symref.el ends here