1 ;;; semantic/db-find.el --- Searching through semantic databases.
3 ;;; Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
4 ;;; 2008, 2009 Free Software Foundation, Inc.
6 ;; Author: Eric M. Ludlam <zappo@gnu.org>
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
26 ;; Databases of various forms can all be searched.
27 ;; There are a few types of searches that can be done:
30 ;; These searches scan a database table collection for tags based
33 ;; Basic Attribute Search:
34 ;; These searches allow searching on specific attributes of tags,
35 ;; such as name, type, or other attribute.
38 ;; These are searches that were needed to accomplish some
39 ;; specialized tasks as discovered in utilities. Advanced searches
40 ;; include matching methods defined outside some parent class.
42 ;; The reason for advanced searches are so that external
43 ;; repositories such as the Emacs obarray, or java .class files can
44 ;; quickly answer these needed questions without dumping the entire
45 ;; symbol list into Emacs for additional refinement searches via
46 ;; regular semanticdb search.
48 ;; How databases are decided upon is another important aspect of a
49 ;; database search. When it comes to searching for a name, there are
50 ;; these types of searches:
53 ;; Basic search means that tags looking for a given name start
54 ;; with a specific search path. Names are sought on that path
55 ;; until it is empty or items on the path can no longer be found.
56 ;; Use `semanticdb-dump-all-table-summary' to test this list.
57 ;; Use `semanticdb-find-throttle-custom-list' to refine this list.
60 ;; A deep search will search more than just the global namespace.
61 ;; It will recurse into tags that contain more tags, and search
65 ;; Brute search means that all tables in all databases in a given
66 ;; project are searched. Brute searches are the search style as
67 ;; written for semantic version 1.x.
69 ;; How does the search path work?
71 ;; A basic search starts with three parameters:
73 ;; (FINDME &optional PATH FIND-FILE-MATCH)
75 ;; FINDME is key to be searched for dependent on the type of search.
76 ;; PATH is an indicator of which tables are to be searched.
77 ;; FIND-FILE-MATCH indicates that any time a match is found, the
78 ;; file associated with the tag should be read into a file.
80 ;; The PATH argument is then the most interesting argument. It can
83 ;; nil - Take the current buffer, and use it's include list
84 ;; buffer - Use that buffer's include list.
85 ;; filename - Use that file's include list. If the file is not
86 ;; in a buffer, see of there is a semanticdb table for it. If
87 ;; not, read that file into a buffer.
88 ;; tag - Get that tag's buffer of file file. See above.
89 ;; table - Search that table, and it's include list.
93 ;; Semanticdb returns the results in a specific format. There are a
94 ;; series of routines for using those results, and results can be
95 ;; passed in as a search-path for refinement searches with
96 ;; semanticdb. Apropos for semanticdb.*find-result for more.
100 ;; Here are applications where different searches are needed which
101 ;; exist as of semantic 1.4.x
103 ;; eldoc - popup help
104 ;; => Requires basic search using default path. (Header files ok)
105 ;; tag jump - jump to a named tag
106 ;; => Requires a brute search useing whole project. (Source files only)
107 ;; completion - Completing symbol names in a smart way
108 ;; => Basic search (headers ok)
109 ;; type analysis - finding type definitions for variables & fcns
110 ;; => Basic search (headers ok)
111 ;; Class browser - organize types into some structure
112 ;; => Brute search, or custom navigation.
115 ;; During a search, load any unloaded DB files based on paths in the
118 (require 'semantic/db)
119 (require 'semantic/db-ref)
122 (require 'semantic/find))
126 (defvar data-debug-thing-alist)
127 (declare-function data-debug-insert-stuff-list "data-debug")
128 (declare-function data-debug-insert-tag-list "data-debug")
129 (declare-function semantic-scope-reset-cache "semantic/scope")
130 (declare-function semanticdb-typecache-notify-reset "semantic/db-typecache")
131 (declare-function ede-current-project "ede")
133 (defvar semanticdb-find-throttle-custom-list
134 '(repeat (radio (const 'local)
139 (const 'omniscience)))
140 "Customization values for semanticdb find throttle.
141 See `semanticdb-find-throttle' for details.")
144 (defcustom semanticdb-find-default-throttle
145 '(local project unloaded system recursive)
146 "The default throttle for `semanticdb-find' routines.
147 The throttle controls how detailed the list of database
148 tables is for a symbol lookup. The value is a list with
150 `file' - The file the search is being performed from.
151 This option is here for completeness only, and
152 is assumed to always be on.
153 `local' - Tables from the same local directory are included.
154 This includes files directly referenced by a file name
155 which might be in a different directory.
156 `project' - Tables from the same local project are included
157 If `project' is specified, then `local' is assumed.
158 `unloaded' - If a table is not in memory, load it. If it is not cached
159 on disk either, get the source, parse it, and create
161 `system' - Tables from system databases. These are specifically
162 tables from system header files, or language equivalent.
163 `recursive' - For include based searches, includes tables referenced
165 `omniscience' - Included system databases which are omniscience, or
166 somehow know everything. Omniscience databases are found
167 in `semanticdb-project-system-databases'.
168 The Emacs Lisp system DB is an omniscience database."
170 :type semanticdb-find-throttle-custom-list)
172 (defun semanticdb-find-throttle-active-p (access-type)
173 "Non-nil if ACCESS-TYPE is an active throttle type."
174 (or (memq access-type semanticdb-find-default-throttle)
175 (eq access-type 'file)
176 (and (eq access-type 'local)
177 (memq 'project semanticdb-find-default-throttle))
182 ;; The find routines spend a lot of time looking stuff up.
183 ;; Use this handy search index to cache data between searches.
184 ;; This should allow searches to start running faster.
185 (defclass semanticdb-find-search-index (semanticdb-abstract-search-index)
186 ((include-path :initform nil
188 "List of semanticdb tables from the include path.")
189 (type-cache :initform nil
191 "Cache of all the data types accessible from this file.
192 Includes all types from all included files, merged namespaces, and
193 expunge duplicates.")
195 "Concrete search index for `semanticdb-find'.
196 This class will cache data derived during various searches.")
198 (defmethod semantic-reset ((idx semanticdb-find-search-index))
199 "Reset the object IDX."
200 (require 'semantic/scope)
201 ;; Clear the include path.
202 (oset idx include-path nil)
203 (when (oref idx type-cache)
204 (semantic-reset (oref idx type-cache)))
205 ;; Clear the scope. Scope doesn't have the data it needs to track
207 (semantic-scope-reset-cache)
210 (defmethod semanticdb-synchronize ((idx semanticdb-find-search-index)
212 "Synchronize the search index IDX with some NEW-TAGS."
215 ;; Notify dependants by clearning their indicies.
216 (semanticdb-notify-references
219 (semantic-reset (semanticdb-get-table-index tab))))
222 (defmethod semanticdb-partial-synchronize ((idx semanticdb-find-search-index)
224 "Synchronize the search index IDX with some changed NEW-TAGS."
225 ;; Only reset if include statements changed.
226 (if (semantic-find-tags-by-class 'include new-tags)
229 ;; Notify dependants by clearning their indicies.
230 (semanticdb-notify-references
233 (semantic-reset (semanticdb-get-table-index tab))))
235 ;; Else, not an include, by just a type.
236 (when (oref idx type-cache)
237 (when (semanticdb-partial-synchronize (oref idx type-cache) new-tags)
238 ;; If the synchronize returns true, we need to notify.
239 ;; Notify dependants by clearning their indicies.
240 (semanticdb-notify-references
243 (let ((tab-idx (semanticdb-get-table-index tab)))
245 (when (oref tab-idx type-cache)
246 (require 'db-typecache)
247 (semanticdb-typecache-notify-reset
248 (oref tab-idx type-cache)))
254 ;;; Path Translations
256 ;;; OVERLOAD Functions
258 ;; These routines needed to be overloaded by specific language modes.
259 ;; They are needed for translating an INCLUDE tag into a semanticdb
262 (define-overloadable-function semanticdb-find-translate-path (path brutish)
263 "Translate PATH into a list of semantic tables.
264 Path translation involves identifying the PATH input argument
265 in one of the following ways:
266 nil - Take the current buffer, and use it's include list
267 buffer - Use that buffer's include list.
268 filename - Use that file's include list. If the file is not
269 in a buffer, see of there is a semanticdb table for it. If
270 not, read that file into a buffer.
271 tag - Get that tag's buffer of file file. See above.
272 table - Search that table, and it's include list.
273 find result - Search the results of a previous find.
275 In addition, once the base path is found, there is the possibility of
276 each added table adding yet more tables to the path, so this routine
277 can return a lengthy list.
279 If argument BRUTISH is non-nil, then instead of using the include
280 list, use all tables found in the parent project of the table
281 identified by translating PATH. Such searches use brute force to
282 scan every available table.
284 The return value is a list of objects of type `semanticdb-table' or
285 it's children. In the case of passing in a find result, the result
286 is returned unchanged.
288 This routine uses `semanticdb-find-table-for-include' to translate
289 specific include tags into a semanticdb table.
291 Note: When searching using a non-brutish method, the list of
292 included files will be cached between runs. Database-references
293 are used to track which files need to have their include lists
294 refreshed when things change. See `semanticdb-ref-test'.
296 Note for overloading: If you opt to overload this function for your
297 major mode, and your routine takes a long time, be sure to call
299 (semantic-throw-on-input 'your-symbol-here)
301 so that it can be called from the idle work handler."
304 (defun semanticdb-find-translate-path-default (path brutish)
305 "Translate PATH into a list of semantic tables.
306 If BRUTISH is non nil, return all tables associated with PATH.
307 Default action as described in `semanticdb-find-translate-path'."
308 (if (semanticdb-find-results-p path)
309 ;; nil means perform the search over these results.
312 (semanticdb-find-translate-path-brutish-default path)
313 (semanticdb-find-translate-path-includes-default path))))
316 (define-overloadable-function semanticdb-find-table-for-include (includetag &optional table)
317 "For a single INCLUDETAG found in TABLE, find a `semanticdb-table' object
318 INCLUDETAG is a semantic TAG of class 'include.
319 TABLE is a semanticdb table that identifies where INCLUDETAG came from.
320 TABLE is optional if INCLUDETAG has an overlay of :filename attribute."
323 (defun semanticdb-find-translate-path-brutish-default (path)
324 "Translate PATH into a list of semantic tables.
325 Default action as described in `semanticdb-find-translate-path'."
327 (cond ((null path) semanticdb-current-database)
328 ((semanticdb-table-p path) (oref path parent-db))
329 (t (let ((tt (semantic-something-to-tag-table path)))
331 ;; @todo - What does this DO ??!?!
332 (set-buffer (semantic-tag-buffer (car tt)))
333 semanticdb-current-database))))))
338 (let ((tabs (semanticdb-get-database-tables db))
340 ;; Only return tables of the same language (major-mode)
341 ;; as the current search environment.
344 (semantic-throw-on-input 'translate-path-brutish)
346 (if (semanticdb-equivalent-mode-for-search (car tabs)
348 (setq ret (cons (car tabs) ret)))
349 (setq tabs (cdr tabs)))
352 ;; This should scan the current project directory list for all
353 ;; semanticdb files, perhaps handling proxies for them.
354 (semanticdb-current-database-list
355 (if basedb (oref basedb reference-directory)
356 default-directory))))
359 (defun semanticdb-find-incomplete-cache-entries-p (cache)
360 "Are there any incomplete entries in CACHE?"
363 (when (and (semanticdb-table-child-p tab)
364 (not (number-or-marker-p (oref tab pointmax))))
369 (defun semanticdb-find-need-cache-update-p (table)
370 "Non nil if the semanticdb TABLE cache needs to be updated."
371 ;; If we were passed in something related to a TABLE,
372 ;; do a caching lookup.
373 (let* ((index (semanticdb-get-table-index table))
374 (cache (when index (oref index include-path)))
375 (incom (semanticdb-find-incomplete-cache-entries-p cache))
376 (unl (semanticdb-find-throttle-active-p 'unloaded))
379 cache ;; Must have a cache
381 ;; If all entries are "full", or if 'unloaded
383 ;; is not in the throttle, it is ok to use the cache.
384 (not incom) (not unl)
390 ;; We need an update.
394 (defun semanticdb-find-translate-path-includes-default (path)
395 "Translate PATH into a list of semantic tables.
396 Default action as described in `semanticdb-find-translate-path'."
397 (let ((table (cond ((null path)
398 semanticdb-current-table)
400 (semantic-buffer-local-value 'semanticdb-current-table path))
401 ((and (stringp path) (file-exists-p path))
402 (semanticdb-file-table-object path t))
403 ((semanticdb-abstract-table-child-p path)
407 ;; If we were passed in something related to a TABLE,
408 ;; do a caching lookup.
409 (let ((index (semanticdb-get-table-index table)))
410 (if (semanticdb-find-need-cache-update-p table)
411 ;; Lets go look up our indicies
412 (let ((ans (semanticdb-find-translate-path-includes--internal path)))
413 (oset index include-path ans)
414 ;; Once we have our new indicies set up, notify those
415 ;; who depend on us if we found something for them to
417 (when ans (semanticdb-refresh-references table))
421 ;; Just return the cache.
422 (oref index include-path)))
423 ;; If we were passed in something like a tag list, or other boring
424 ;; searchable item, then instead do the regular thing without caching.
425 (semanticdb-find-translate-path-includes--internal path))))
427 (defvar semanticdb-find-lost-includes nil
428 "Include files that we cannot find associated with this buffer.")
429 (make-variable-buffer-local 'semanticdb-find-lost-includes)
431 (defvar semanticdb-find-scanned-include-tags nil
432 "All include tags scanned, plus action taken on the tag.
433 Each entry is an alist:
435 where ACTION is one of 'scanned, 'duplicate, 'lost.
436 and TAG is a clone of the include tag that was found.")
437 (make-variable-buffer-local 'semanticdb-find-scanned-include-tags)
439 (defvar semanticdb-implied-include-tags nil
440 "Include tags implied for all files of a given mode.
441 Set this variable with `defvar-mode-local' for a particular mode so
442 that any symbols that exist for all files for that mode are included.
444 Note: This could be used as a way to write a file in a langauge
445 to declare all the built-ins for that language.")
447 (defun semanticdb-find-translate-path-includes--internal (path)
448 "Internal implementation of `semanticdb-find-translate-path-includes-default'.
449 This routine does not depend on the cache, but will always derive
450 a new path from the provided PATH."
451 (let ((includetags nil)
453 (matchedtables (list semanticdb-current-table))
454 (matchedincludes nil)
456 (scannedincludes nil)
460 (semantic-refresh-tags-safe)
461 (setq includetags (append
462 (semantic-find-tags-included (current-buffer))
463 semanticdb-implied-include-tags)
464 curtable semanticdb-current-table
465 incfname (buffer-file-name))
467 ((semanticdb-table-p path)
468 (setq includetags (semantic-find-tags-included path)
470 incfname (semanticdb-full-filename path))
475 (semantic-refresh-tags-safe))
476 (setq includetags (semantic-find-tags-included path)
477 curtable (save-excursion (set-buffer path)
478 semanticdb-current-table)
479 incfname (buffer-file-name path)))
481 (setq includetags (semantic-find-tags-included path))
483 ;; If we have some tags, derive a table from them.
484 ;; else we will do nothing, so the table is useless.
486 ;; @todo - derive some tables
487 (message "Need to derive tables for %S in translate-path-includes--default."
491 ;; Make sure each found include tag has an originating file name associated
494 (dolist (it includetags)
495 (semantic--tag-put-property it :filename incfname)))
497 ;; Loop over all include tags adding to matchedtables
499 (semantic-throw-on-input 'semantic-find-translate-path-includes-default)
501 ;; If we've seen this include string before, lets skip it.
502 (if (member (semantic-tag-name (car includetags)) matchedincludes)
505 (push (cons 'duplicate (semantic-tag-clone (car includetags)))
508 (setq nexttable (semanticdb-find-table-for-include (car includetags) curtable))
509 (when (not nexttable)
510 ;; Save the lost include.
511 (push (car includetags) lostincludes)
512 (push (cons 'lost (semantic-tag-clone (car includetags)))
517 ;; Push the include file, so if we can't find it, we only
518 ;; can't find it once.
519 (push (semantic-tag-name (car includetags)) matchedincludes)
521 ;; (message "Scanning %s" (semantic-tag-name (car includetags)))
523 (not (memq nexttable matchedtables))
524 (semanticdb-equivalent-mode-for-search nexttable
527 ;; Add to list of tables
528 (push nexttable matchedtables)
530 ;; Queue new includes to list
531 (if (semanticdb-find-throttle-active-p 'recursive)
532 ;; @todo - recursive includes need to have the originating
533 ;; buffer's location added to the path.
536 ((semanticdb-table-p nexttable)
537 (semanticdb-refresh-table nexttable)
538 ;; Use the method directly, or we will recurse
539 ;; into ourselves here.
540 (semanticdb-find-tags-by-class-method
542 (t ;; @todo - is this ever possible???
543 (message "semanticdb-ftp - how did you do that?")
544 (semantic-find-tags-included
545 (semanticdb-get-tags nexttable)))
547 (newincfname (semanticdb-full-filename nexttable))
550 (push (cons 'scanned (semantic-tag-clone (car includetags)))
553 ;; Setup new tags so we know where they are.
555 (semantic--tag-put-property it :filename
558 (setq includetags (nconc includetags newtags)))
559 ;; ELSE - not recursive throttle
560 (push (cons 'scanned-no-recurse
561 (semantic-tag-clone (car includetags)))
565 (setq includetags (cdr includetags)))
567 (setq semanticdb-find-lost-includes lostincludes)
568 (setq semanticdb-find-scanned-include-tags (reverse scannedincludes))
570 ;; Find all the omniscient databases for this major mode, and
571 ;; add them if needed
572 (when (and (semanticdb-find-throttle-active-p 'omniscience)
573 semanticdb-search-system-databases)
574 ;; We can append any mode-specific omniscience databases into
575 ;; our search list here.
576 (let ((systemdb semanticdb-project-system-databases)
579 (setq ans (semanticdb-file-table
581 ;; I would expect most omniscient to return the same
582 ;; thing reguardless of filename, but we may have
583 ;; one that can return a table of all things the
584 ;; current file needs.
585 (buffer-file-name (current-buffer))))
586 (when (not (memq ans matchedtables))
587 (setq matchedtables (cons ans matchedtables)))
588 (setq systemdb (cdr systemdb))))
590 (nreverse matchedtables)))
592 (define-overloadable-function semanticdb-find-load-unloaded (filename)
593 "Create a database table for FILENAME if it hasn't been parsed yet.
594 Assumes that FILENAME exists as a source file.
595 Assumes that a preexisting table does not exist, even if it
596 isn't in memory yet."
597 (if (semanticdb-find-throttle-active-p 'unloaded)
599 (semanticdb-file-table-object filename t)))
601 (defun semanticdb-find-load-unloaded-default (filename)
602 "Load an unloaded file in FILENAME using the default semanticdb loader."
603 (semanticdb-file-table-object filename))
605 (defun semanticdb-find-table-for-include-default (includetag &optional table)
606 "Default implementation of `semanticdb-find-table-for-include'.
607 Uses `semanticdb-current-database-list' as the search path.
608 INCLUDETAG and TABLE are documented in `semanticdb-find-table-for-include'.
609 Included databases are filtered based on `semanticdb-find-default-throttle'."
610 (if (not (eq (semantic-tag-class includetag) 'include))
611 (signal 'wrong-type-argument (list includetag 'include)))
614 ;; Note, some languages (like Emacs or Java) use include tag names
615 ;; that don't represent files! We want to have file names.
616 (semantic-tag-include-filename includetag))
622 ;; INCLUDETAG should have some way to reference where it came
623 ;; from! If not, TABLE should provide the way. Each time we
624 ;; look up a tag, we may need to find it in some relative way
625 ;; and must set our current buffer eto the origin of includetag
626 ;; or nothing may work.
628 (cond ((semantic-tag-file-name includetag)
629 ;; A tag may have a buffer, or a :filename property.
630 (file-name-directory (semantic-tag-file-name includetag)))
632 (file-name-directory (semanticdb-full-filename table)))
634 ;; @todo - what to do here? Throw an error maybe
635 ;; and fix usage bugs?
639 ;; Step 1: Relative path name
641 ;; If the name is relative, then it should be findable as relative
642 ;; to the source file that this tag originated in, and be fast.
644 ((and (semanticdb-find-throttle-active-p 'local)
645 (file-exists-p (expand-file-name name originfiledir)))
647 (setq ans (semanticdb-find-load-unloaded
648 (expand-file-name name originfiledir)))
650 ;; Step 2: System or Project level includes
653 ;; First, if it a system include, we can investigate that tags
655 (and (semanticdb-find-throttle-active-p 'system)
657 ;; Sadly, not all languages make this distinction.
658 ;;(semantic-tag-include-system-p includetag)
660 ;; Here, we get local and system files.
661 (setq tmp (semantic-dependency-tag-file includetag))
663 ;; Second, project files are active, we and we have EDE,
664 ;; we can find it using the same tool.
665 (and (semanticdb-find-throttle-active-p 'project)
666 ;; Make sure EDE is available, and we have a project
667 (featurep 'ede) (ede-current-project originfiledir)
668 ;; The EDE query is hidden in this call.
669 (setq tmp (semantic-dependency-tag-file includetag))
672 (setq ans (semanticdb-find-load-unloaded tmp))
674 ;; Somewhere in our project hierarchy
676 ;; Remember: Roots includes system databases which can create
677 ;; specialized tables we can search.
679 ;; NOTE: Not used if EDE is active!
680 ((and (semanticdb-find-throttle-active-p 'project)
681 ;; And dont do this if it is a system include. Not supported by all languages,
682 ;; but when it is, this is a nice fast way to skip this step.
683 (not (semantic-tag-include-system-p includetag))
684 ;; Don't do this if we have an EDE project.
685 (not (and (featurep 'ede)
686 ;; Note: We don't use originfiledir here because
687 ;; we want to know about the source file we are
689 (ede-current-project)))
692 (setq roots (semanticdb-current-database-list))
694 (while (and (not ans) roots)
695 (let* ((ref (if (slot-boundp (car roots) 'reference-directory)
696 (oref (car roots) reference-directory)))
697 (fname (cond ((null ref) nil)
698 ((file-exists-p (expand-file-name name ref))
699 (expand-file-name name ref))
700 ((file-exists-p (expand-file-name (file-name-nondirectory name) ref))
701 (expand-file-name (file-name-nondirectory name) ref)))))
702 (when (and ref fname)
703 ;; There is an actual file. Grab it.
704 (setq ans (semanticdb-find-load-unloaded fname)))
708 ;; NOTE: We used to look up omniscient databases here, but that
709 ;; is now handled one layer up.
711 ;; Missing: a database that knows where missing files are. Hmm.
712 ;; perhaps I need an override function for that?
716 (setq roots (cdr roots))))
721 ;;; Perform interactive tests on the path/search mechanisms.
724 (defun semanticdb-find-test-translate-path (&optional arg)
725 "Call and output results of `semanticdb-find-translate-path'.
726 With ARG non-nil, specify a BRUTISH translation.
727 See `semanticdb-find-default-throttle' and `semanticdb-project-roots'
728 for details on how this list is derived."
730 (semantic-fetch-tags)
731 (require 'data-debug)
732 (let ((start (current-time))
733 (p (semanticdb-find-translate-path nil arg))
736 (data-debug-new-buffer "*SEMANTICDB FTP ADEBUG*")
737 (message "Search of tags took %.2f seconds."
738 (semantic-elapsed-time start end))
740 (data-debug-insert-stuff-list p "*")))
742 (defun semanticdb-find-test-translate-path-no-loading (&optional arg)
743 "Call and output results of `semanticdb-find-translate-path'.
744 With ARG non-nil, specify a BRUTISH translation.
745 See `semanticdb-find-default-throttle' and `semanticdb-project-roots'
746 for details on how this list is derived."
748 (semantic-fetch-tags)
749 (require 'data-debug)
750 (let* ((semanticdb-find-default-throttle
751 (if (featurep 'semanticdb-find)
752 (remq 'unloaded semanticdb-find-default-throttle)
754 (start (current-time))
755 (p (semanticdb-find-translate-path nil arg))
758 (data-debug-new-buffer "*SEMANTICDB FTP ADEBUG*")
759 (message "Search of tags took %.2f seconds."
760 (semantic-elapsed-time start end))
762 (data-debug-insert-stuff-list p "*")))
765 (defun semanticdb-find-adebug-lost-includes ()
766 "Translate the current path, then display the lost includes.
767 Examines the variable `semanticdb-find-lost-includes'."
769 (require 'data-debug)
770 (semanticdb-find-translate-path nil nil)
771 (let ((lost semanticdb-find-lost-includes)
775 (message "There are no unknown includes for %s"
778 (data-debug-new-buffer "*SEMANTICDB lost-includes ADEBUG*")
779 (data-debug-insert-tag-list lost "*")
782 (defun semanticdb-find-adebug-insert-scanned-tag-cons (consdata prefix prebuttontext)
783 "Insert a button representing scanned include CONSDATA.
784 PREFIX is the text that preceeds the button.
785 PREBUTTONTEXT is some text between prefix and the overlay button."
786 (let* ((start (point))
788 (mode (car consdata))
790 (name (semantic-tag-name tag))
791 (file (semantic-tag-file-name tag))
792 (str1 (format "%S %s" mode name))
793 (str2 (format " : %s" file))
795 (insert prefix prebuttontext str1)
798 (put-text-property start end 'face
799 (cond ((eq mode 'scanned)
800 'font-lock-function-name-face)
801 ((eq mode 'duplicate)
802 'font-lock-comment-face)
804 'font-lock-variable-name-face)
805 ((eq mode 'scanned-no-recurse)
806 'font-lock-type-face)))
807 (put-text-property start end 'ddebug (cdr consdata))
808 (put-text-property start end 'ddebug-indent(length prefix))
809 (put-text-property start end 'ddebug-prefix prefix)
810 (put-text-property start end 'help-echo tip)
811 (put-text-property start end 'ddebug-function
812 'data-debug-insert-tag-parts-from-point)
817 (defun semanticdb-find-adebug-scanned-includes ()
818 "Translate the current path, then display the lost includes.
819 Examines the variable `semanticdb-find-lost-includes'."
821 (require 'data-debug)
822 (semanticdb-find-translate-path nil nil)
823 (let ((scanned semanticdb-find-scanned-include-tags)
824 (data-debug-thing-alist
826 '((lambda (thing) (and (consp thing)
827 (symbolp (car thing))
829 '(scanned scanned-no-recurse
831 . semanticdb-find-adebug-insert-scanned-tag-cons)
832 data-debug-thing-alist))
836 (message "There are no includes scanned %s"
839 (data-debug-new-buffer "*SEMANTICDB scanned-includes ADEBUG*")
840 (data-debug-insert-stuff-list scanned "*")
843 ;;; FIND results and edebug
845 (eval-after-load "cedet-edebug"
847 (cedet-edebug-add-print-override
848 '(semanticdb-find-results-p object)
849 '(semanticdb-find-result-prin1-to-string object) )
856 ;; Once you have a search result, use these routines to operate
857 ;; on the search results at a higher level
860 (defun semanticdb-strip-find-results (results &optional find-file-match)
861 "Strip a semanticdb search RESULTS to exclude objects.
862 This makes it appear more like the results of a `semantic-find-' call.
863 Optional FIND-FILE-MATCH loads all files associated with RESULTS
864 into buffers. This has the side effect of enabling `semantic-tag-buffer' to
866 If FIND-FILE-MATCH is 'name, then only the filename is stored
867 in each tag instead of loading each file into a buffer.
868 If the input RESULTS are not going to be used again, and if
869 FIND-FILE-MATCH is nil, you can use `semanticdb-fast-strip-find-results'
872 ;; Load all files associated with RESULTS.
876 (let ((tab (car (car tmp)))
877 (tags (cdr (car tmp))))
879 ;; Normilzation gives specialty database tables a chance
880 ;; to convert into a more stable tag format.
881 (let* ((norm (semanticdb-normalize-one-tag tab T))
886 ;; If it didn't normalize, use what we had.
889 (setq output (append output (list ntag))))
891 ;; Find-file-match allows a tool to make sure the tag is
892 ;; 'live', somewhere in a buffer.
893 (cond ((eq find-file-match 'name)
894 (let ((f (semanticdb-full-filename nametable)))
895 (semantic--tag-put-property ntag :filename f)))
896 ((and find-file-match ntab)
897 (semanticdb-get-buffer ntab))
901 (setq tmp (cdr tmp)))
903 ;; @todo - I could use nconc, but I don't know what the caller may do with
904 ;; RESULTS after this is called. Right now semantic-complete will
905 ;; recycling the input after calling this routine.
906 (apply #'append (mapcar #'cdr results))))
908 (defun semanticdb-fast-strip-find-results (results)
909 "Destructively strip a semanticdb search RESULTS to exclude objects.
910 This makes it appear more like the results of a `semantic-find-' call.
911 This is like `semanticdb-strip-find-results', except the input list RESULTS
913 (apply #'nconc (mapcar #'cdr results)))
915 (defun semanticdb-find-results-p (resultp)
916 "Non-nil if RESULTP is in the form of a semanticdb search result.
917 This query only really tests the first entry in the list that is RESULTP,
918 but should be good enough for debugging assertions."
920 (listp (car resultp))
921 (semanticdb-abstract-table-child-p (car (car resultp)))
922 (or (semantic-tag-p (car (cdr (car resultp))))
923 (null (car (cdr (car resultp)))))))
925 (defun semanticdb-find-result-prin1-to-string (result)
926 "Presuming RESULT satisfies `semanticdb-find-results-p', provide a short PRIN1 output."
927 (if (< (length result) 2)
928 (concat "#<FIND RESULT "
929 (mapconcat (lambda (a)
930 (concat "(" (object-name (car a) ) " . "
931 "#<TAG LIST " (number-to-string (length (cdr a))) ">)"))
935 ;; Longer results should have an abreviated form.
936 (format "#<FIND RESULT %d TAGS in %d FILES>"
937 (semanticdb-find-result-length result)
940 (defun semanticdb-find-result-with-nil-p (resultp)
941 "Non-nil of RESULTP is in the form of a semanticdb search result.
942 nil is a valid value where a TABLE usually is, but only if the TAG
943 results include overlays.
944 This query only really tests the first entry in the list that is RESULTP,
945 but should be good enough for debugging assertions."
947 (listp (car resultp))
948 (let ((tag-to-test (car-safe (cdr (car resultp)))))
949 (or (and (semanticdb-abstract-table-child-p (car (car resultp)))
950 (or (semantic-tag-p tag-to-test)
952 (and (null (car (car resultp)))
953 (or (semantic-tag-with-position-p tag-to-test)
954 (null tag-to-test))))
958 (defun semanticdb-find-result-length (result)
959 "Number of tags found in RESULT."
961 (mapc (lambda (onetable)
962 (setq count (+ count (1- (length onetable)))))
967 (defun semanticdb-find-result-nth (result n)
968 "In RESULT, return the Nth search result.
969 This is a 0 based search result, with the first match being element 0.
971 The returned value is a cons cell: (TAG . TABLE) where TAG
972 is the tag at the Nth position. TABLE is the semanticdb table where
973 the TAG was found. Sometimes TABLE can be nil."
976 ;; Loop over each single table hit.
977 (while (and (not ans) result)
978 ;; For each table result, get local length, and modify
979 ;; N to be that much less.
980 (let ((ll (length (cdr (car result))))) ;; local length
982 ;; We have a local match.
983 (setq ans (nth n (cdr (car result)))
984 anstable (car (car result)))
985 ;; More to go. Decrement N.
988 (setq result (cdr result)))
989 (cons ans anstable)))
991 (defun semanticdb-find-result-test (result)
992 "Test RESULT by accessing all the tags in the list."
993 (if (not (semanticdb-find-results-p result))
994 (error "Does not pass `semanticdb-find-results-p.\n"))
995 (let ((len (semanticdb-find-result-length result))
998 (let ((tag (semanticdb-find-result-nth result i)))
999 (if (not (semantic-tag-p (car tag)))
1000 (error "%d entry is not a tag" i)))
1004 (defun semanticdb-find-result-nth-in-buffer (result n)
1005 "In RESULT, return the Nth search result.
1006 Like `semanticdb-find-result-nth', except that only the TAG
1007 is returned, and the buffer it is found it will be made current.
1008 If the result tag has no position information, the originating buffer
1009 is still made current."
1010 (let* ((ret (semanticdb-find-result-nth result n))
1012 (anstable (cdr ret)))
1013 ;; If we have a hit, double-check the find-file
1014 ;; entry. If the file must be loaded, then gat that table's
1015 ;; source file into a buffer.
1018 (let ((norm (semanticdb-normalize-one-tag anstable ans)))
1020 ;; The normalized tags can now be found based on that
1022 (semanticdb-set-buffer (car norm))
1024 (setq ans (cdr norm))
1030 (defun semanticdb-find-result-mapc (fcn result)
1031 "Apply FCN to each element of find RESULT for side-effects only.
1032 FCN takes two arguments. The first is a TAG, and the
1033 second is a DB from wence TAG originated.
1035 (mapc (lambda (sublst)
1037 (funcall fcn tag (car sublst)))
1044 ;; Basic logging to see what the search routines are doing.
1045 (defvar semanticdb-find-log-flag nil
1046 "Non-nil means log the process of searches.")
1048 (defvar semanticdb-find-log-buffer-name "*SemanticDB Find Log*"
1049 "The name of the logging buffer.")
1051 (defun semanticdb-find-toggle-logging ()
1052 "Toggle sematnicdb logging."
1054 (setq semanticdb-find-log-flag (null semanticdb-find-log-flag))
1055 (message "Semanticdb find logging is %sabled"
1056 (if semanticdb-find-log-flag "en" "dis")))
1058 (defun semanticdb-reset-log ()
1059 "Reset the log buffer."
1061 (when semanticdb-find-log-flag
1063 (set-buffer (get-buffer-create semanticdb-find-log-buffer-name))
1067 (defun semanticdb-find-log-move-to-end ()
1068 "Move to the end of the semantic log."
1069 (let ((cb (current-buffer))
1070 (cw (selected-window)))
1073 (set-buffer semanticdb-find-log-buffer-name)
1074 (if (get-buffer-window (current-buffer) 'visible)
1075 (select-window (get-buffer-window (current-buffer) 'visible)))
1076 (goto-char (point-max)))
1077 (if cw (select-window cw))
1080 (defun semanticdb-find-log-new-search (forwhat)
1081 "Start a new search FORWHAT."
1082 (when semanticdb-find-log-flag
1084 (set-buffer (get-buffer-create semanticdb-find-log-buffer-name))
1085 (insert (format "New Search: %S\n" forwhat))
1087 (semanticdb-find-log-move-to-end)))
1089 (defun semanticdb-find-log-activity (table result)
1090 "Log that TABLE has been searched and RESULT was found."
1091 (when semanticdb-find-log-flag
1093 (set-buffer semanticdb-find-log-buffer-name)
1094 (insert "Table: " (object-print table)
1095 " Result: " (int-to-string (length result)) " tags"
1098 (semanticdb-find-log-move-to-end)))
1100 ;;; Semanticdb find API functions
1101 ;; These are the routines actually used to perform searches.
1103 (defun semanticdb-find-tags-collector (function &optional path find-file-match
1105 "Collect all tags returned by FUNCTION over PATH.
1106 The FUNCTION must take two arguments. The first is TABLE,
1107 which is a semanticdb table containing tags. The second argument
1108 to FUNCTION is TAGS. TAGS may be a list of tags. If TAGS is non-nil, then
1109 FUNCTION should search the TAG list, not through TABLE.
1111 See `semanticdb-find-translate-path' for details on PATH.
1112 FIND-FILE-MATCH indicates that any time a match is found, the file
1113 associated with that tag should be loaded into a buffer.
1115 Note: You should leave FIND-FILE-MATCH as nil. It is far more
1116 efficient to take the results from any search and use
1117 `semanticdb-strip-find-results' instead. This argument is here
1118 for backward compatibility.
1120 If optional argument BRUTISH is non-nil, then ignore include statements,
1121 and search all tables in this project tree."
1124 ;; If path is a buffer, set ourselves up in that buffer
1125 ;; so that the override methods work correctly.
1126 (when (bufferp path) (set-buffer path))
1127 (if (semanticdb-find-results-p path)
1128 ;; When we get find results, loop over that.
1129 (dolist (tableandtags path)
1130 (semantic-throw-on-input 'semantic-find-translate-path)
1131 ;; If FIND-FILE-MATCH is non-nil, skip tables of class
1132 ;; `semanticdb-search-results-table', since those are system
1133 ;; databases and not associated with a file.
1134 (unless (and find-file-match
1136 (car tableandtags) semanticdb-search-results-table))
1137 (when (setq match (funcall function
1138 (car tableandtags) (cdr tableandtags)))
1139 (when find-file-match
1140 (save-excursion (semanticdb-set-buffer (car tableandtags))))
1141 (push (cons (car tableandtags) match) found)))
1143 ;; Only log searches across data bases.
1144 (semanticdb-find-log-new-search nil)
1145 ;; If we get something else, scan the list of tables resulting
1146 ;; from translating it into a list of objects.
1147 (dolist (table (semanticdb-find-translate-path path brutish))
1148 (semantic-throw-on-input 'semantic-find-translate-path)
1149 ;; If FIND-FILE-MATCH is non-nil, skip tables of class
1150 ;; `semanticdb-search-results-table', since those are system
1151 ;; databases and not associated with a file.
1152 (unless (and find-file-match
1153 (obj-of-class-p table semanticdb-search-results-table))
1154 (when (and table (setq match (funcall function table nil)))
1155 (semanticdb-find-log-activity table match)
1156 (when find-file-match
1157 (save-excursion (semanticdb-set-buffer table)))
1158 (push (cons table match) found))))))
1159 ;; At this point, FOUND has had items pushed onto it.
1160 ;; This means items are being returned in REVERSE order
1161 ;; of the tables searched, so if you just get th CAR, then
1162 ;; too-bad, you may have some system-tag that has no
1163 ;; buffer associated with it.
1165 ;; It must be reversed.
1169 (defun semanticdb-find-tags-by-name (name &optional path find-file-match)
1170 "Search for all tags matching NAME on PATH.
1171 See `semanticdb-find-translate-path' for details on PATH.
1172 FIND-FILE-MATCH indicates that any time a match is found, the file
1173 associated with that tag should be loaded into a buffer."
1174 (semanticdb-find-tags-collector
1175 (lambda (table tags)
1176 (semanticdb-find-tags-by-name-method table name tags))
1177 path find-file-match))
1180 (defun semanticdb-find-tags-by-name-regexp (regexp &optional path find-file-match)
1181 "Search for all tags matching REGEXP on PATH.
1182 See `semanticdb-find-translate-path' for details on PATH.
1183 FIND-FILE-MATCH indicates that any time a match is found, the file
1184 associated with that tag should be loaded into a buffer."
1185 (semanticdb-find-tags-collector
1186 (lambda (table tags)
1187 (semanticdb-find-tags-by-name-regexp-method table regexp tags))
1188 path find-file-match))
1191 (defun semanticdb-find-tags-for-completion (prefix &optional path find-file-match)
1192 "Search for all tags matching PREFIX on PATH.
1193 See `semanticdb-find-translate-path' for details on PATH.
1194 FIND-FILE-MATCH indicates that any time a match is found, the file
1195 associated with that tag should be loaded into a buffer."
1196 (semanticdb-find-tags-collector
1197 (lambda (table tags)
1198 (semanticdb-find-tags-for-completion-method table prefix tags))
1199 path find-file-match))
1202 (defun semanticdb-find-tags-by-class (class &optional path find-file-match)
1203 "Search for all tags of CLASS on PATH.
1204 See `semanticdb-find-translate-path' for details on PATH.
1205 FIND-FILE-MATCH indicates that any time a match is found, the file
1206 associated with that tag should be loaded into a buffer."
1207 (semanticdb-find-tags-collector
1208 (lambda (table tags)
1209 (semanticdb-find-tags-by-class-method table class tags))
1210 path find-file-match))
1213 (defun semanticdb-deep-find-tags-by-name (name &optional path find-file-match)
1214 "Search for all tags matching NAME on PATH.
1215 Search also in all components of top level tags founds.
1216 See `semanticdb-find-translate-path' for details on PATH.
1217 FIND-FILE-MATCH indicates that any time a match is found, the file
1218 associated with that tag should be loaded into a buffer."
1219 (semanticdb-find-tags-collector
1220 (lambda (table tags)
1221 (semanticdb-deep-find-tags-by-name-method table name tags))
1222 path find-file-match))
1224 (defun semanticdb-deep-find-tags-by-name-regexp (regexp &optional path find-file-match)
1225 "Search for all tags matching REGEXP on PATH.
1226 Search also in all components of top level tags founds.
1227 See `semanticdb-find-translate-path' for details on PATH.
1228 FIND-FILE-MATCH indicates that any time a match is found, the file
1229 associated with that tag should be loaded into a buffer."
1230 (semanticdb-find-tags-collector
1231 (lambda (table tags)
1232 (semanticdb-deep-find-tags-by-name-regexp-method table regexp tags))
1233 path find-file-match))
1235 (defun semanticdb-deep-find-tags-for-completion (prefix &optional path find-file-match)
1236 "Search for all tags matching PREFIX on PATH.
1237 Search also in all components of top level tags founds.
1238 See `semanticdb-find-translate-path' for details on PATH.
1239 FIND-FILE-MATCH indicates that any time a match is found, the file
1240 associated with that tag should be loaded into a buffer."
1241 (semanticdb-find-tags-collector
1242 (lambda (table tags)
1243 (semanticdb-deep-find-tags-for-completion-method table prefix tags))
1244 path find-file-match))
1246 ;;; Brutish Search Routines
1248 (defun semanticdb-brute-deep-find-tags-by-name (name &optional path find-file-match)
1249 "Search for all tags matching NAME on PATH.
1250 See `semanticdb-find-translate-path' for details on PATH.
1251 The argument BRUTISH will be set so that searching includes all tables
1252 in the current project.
1253 FIND-FILE-MATCH indicates that any time a matchi is found, the file
1254 associated wit that tag should be loaded into a buffer."
1255 (semanticdb-find-tags-collector
1256 (lambda (table tags)
1257 (semanticdb-deep-find-tags-by-name-method table name tags))
1258 path find-file-match t))
1260 (defun semanticdb-brute-deep-find-tags-for-completion (prefix &optional path find-file-match)
1261 "Search for all tags matching PREFIX on PATH.
1262 See `semanticdb-find-translate-path' for details on PATH.
1263 The argument BRUTISH will be set so that searching includes all tables
1264 in the current project.
1265 FIND-FILE-MATCH indicates that any time a matchi is found, the file
1266 associated wit that tag should be loaded into a buffer."
1267 (semanticdb-find-tags-collector
1268 (lambda (table tags)
1269 (semanticdb-deep-find-tags-for-completion-method table prefix tags))
1270 path find-file-match t))
1272 (defun semanticdb-brute-find-tags-by-class (class &optional path find-file-match)
1273 "Search for all tags of CLASS on PATH.
1274 See `semanticdb-find-translate-path' for details on PATH.
1275 The argument BRUTISH will be set so that searching includes all tables
1276 in the current project.
1277 FIND-FILE-MATCH indicates that any time a match is found, the file
1278 associated with that tag should be loaded into a buffer."
1279 (semanticdb-find-tags-collector
1280 (lambda (table tags)
1281 (semanticdb-find-tags-by-class-method table class tags))
1282 path find-file-match t))
1284 ;;; Specialty Search Routines
1285 (defun semanticdb-find-tags-external-children-of-type
1286 (type &optional path find-file-match)
1287 "Search for all tags defined outside of TYPE w/ TYPE as a parent.
1288 See `semanticdb-find-translate-path' for details on PATH.
1289 FIND-FILE-MATCH indicates that any time a match is found, the file
1290 associated with that tag should be loaded into a buffer."
1291 (semanticdb-find-tags-collector
1292 (lambda (table tags)
1293 (semanticdb-find-tags-external-children-of-type-method table type tags))
1294 path find-file-match))
1296 (defun semanticdb-find-tags-subclasses-of-type
1297 (type &optional path find-file-match)
1298 "Search for all tags of class type defined that subclass TYPE.
1299 See `semanticdb-find-translate-path' for details on PATH.
1300 FIND-FILE-MATCH indicates that any time a match is found, the file
1301 associated with that tag should be loaded into a buffer."
1302 (semanticdb-find-tags-collector
1303 (lambda (table tags)
1304 (semanticdb-find-tags-subclasses-of-type-method table type tags))
1305 path find-file-match t))
1309 ;; Default methods for semanticdb database and table objects.
1310 ;; Override these with system databases to as new types of back ends.
1312 ;;; Top level Searches
1313 (defmethod semanticdb-find-tags-by-name-method ((table semanticdb-abstract-table) name &optional tags)
1314 "In TABLE, find all occurances of tags with NAME.
1315 Optional argument TAGS is a list of tags to search.
1316 Returns a table of all matching tags."
1317 (semantic-find-tags-by-name name (or tags (semanticdb-get-tags table))))
1319 (defmethod semanticdb-find-tags-by-name-regexp-method ((table semanticdb-abstract-table) regexp &optional tags)
1320 "In TABLE, find all occurances of tags matching REGEXP.
1321 Optional argument TAGS is a list of tags to search.
1322 Returns a table of all matching tags."
1323 (semantic-find-tags-by-name-regexp regexp (or tags (semanticdb-get-tags table))))
1325 (defmethod semanticdb-find-tags-for-completion-method ((table semanticdb-abstract-table) prefix &optional tags)
1326 "In TABLE, find all occurances of tags matching PREFIX.
1327 Optional argument TAGS is a list of tags to search.
1328 Returns a table of all matching tags."
1329 (semantic-find-tags-for-completion prefix (or tags (semanticdb-get-tags table))))
1331 (defmethod semanticdb-find-tags-by-class-method ((table semanticdb-abstract-table) class &optional tags)
1332 "In TABLE, find all occurances of tags of CLASS.
1333 Optional argument TAGS is a list of tags to search.
1334 Returns a table of all matching tags."
1335 (semantic-find-tags-by-class class (or tags (semanticdb-get-tags table))))
1337 (defmethod semanticdb-find-tags-external-children-of-type-method ((table semanticdb-abstract-table) parent &optional tags)
1338 "In TABLE, find all occurances of tags whose parent is the PARENT type.
1339 Optional argument TAGS is a list of tags to search.
1340 Returns a table of all matching tags."
1341 (semantic-find-tags-external-children-of-type parent (or tags (semanticdb-get-tags table))))
1343 (defmethod semanticdb-find-tags-subclasses-of-type-method ((table semanticdb-abstract-table) parent &optional tags)
1344 "In TABLE, find all occurances of tags whose parent is the PARENT type.
1345 Optional argument TAGS is a list of tags to search.
1346 Returns a table of all matching tags."
1347 (semantic-find-tags-subclasses-of-type parent (or tags (semanticdb-get-tags table))))
1350 (defmethod semanticdb-deep-find-tags-by-name-method ((table semanticdb-abstract-table) name &optional tags)
1351 "In TABLE, find all occurances of tags with NAME.
1352 Search in all tags in TABLE, and all components of top level tags in
1354 Optional argument TAGS is a list of tags to search.
1355 Return a table of all matching tags."
1356 (semantic-find-tags-by-name name (semantic-flatten-tags-table (or tags (semanticdb-get-tags table)))))
1358 (defmethod semanticdb-deep-find-tags-by-name-regexp-method ((table semanticdb-abstract-table) regexp &optional tags)
1359 "In TABLE, find all occurances of tags matching REGEXP.
1360 Search in all tags in TABLE, and all components of top level tags in
1362 Optional argument TAGS is a list of tags to search.
1363 Return a table of all matching tags."
1364 (semantic-find-tags-by-name-regexp regexp (semantic-flatten-tags-table (or tags (semanticdb-get-tags table)))))
1366 (defmethod semanticdb-deep-find-tags-for-completion-method ((table semanticdb-abstract-table) prefix &optional tags)
1367 "In TABLE, find all occurances of tags matching PREFIX.
1368 Search in all tags in TABLE, and all components of top level tags in
1370 Optional argument TAGS is a list of tags to search.
1371 Return a table of all matching tags."
1372 (semantic-find-tags-for-completion prefix (semantic-flatten-tags-table (or tags (semanticdb-get-tags table)))))
1374 (provide 'semantic/db-find)
1377 ;; generated-autoload-file: "loaddefs.el"
1378 ;; generated-autoload-feature: semantic/loaddefs
1379 ;; generated-autoload-load-name: "semantic/db-find"
1382 ;;; semantic/db-find.el ends here