1 ;;; idle.el --- Schedule parsing tasks in idle time
3 ;; Copyright (C) 2003-2006, 2008-2014 Free Software Foundation, Inc.
5 ;; Author: Eric M. Ludlam <zappo@gnu.org>
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 ;; Originally, `semantic-auto-parse-mode' handled refreshing the
26 ;; tags in a buffer in idle time. Other activities can be scheduled
27 ;; in idle time, all of which require up-to-date tag tables.
28 ;; Having a specialized idle time scheduler that first refreshes
29 ;; the tags buffer, and then enables other idle time tasks reduces
30 ;; the amount of work needed. Any specialized idle tasks need not
31 ;; ask for a fresh tags list.
33 ;; NOTE ON SEMANTIC_ANALYZE
35 ;; Some of the idle modes use the semantic analyzer. The analyzer
36 ;; automatically caches the created context, so it is shared amongst
37 ;; all idle modes that will need it.
40 (require 'semantic
/ctxt
)
41 (require 'semantic
/format
)
42 (require 'semantic
/tag
)
46 ;; For the semantic-find-tags-by-name macro.
47 (eval-when-compile (require 'semantic
/find
))
49 (defvar eldoc-last-message
)
50 (declare-function eldoc-message
"eldoc")
51 (declare-function semantic-analyze-interesting-tag
"semantic/analyze")
52 (declare-function semantic-analyze-unsplit-name
"semantic/analyze/fcn")
53 (declare-function semantic-complete-analyze-inline-idle
"semantic/complete")
54 (declare-function semanticdb-deep-find-tags-by-name
"semantic/db-find")
55 (declare-function semanticdb-save-all-db-idle
"semantic/db")
56 (declare-function semanticdb-typecache-refresh-for-buffer
"semantic/db-typecache")
57 (declare-function semantic-decorate-flush-pending-decorations
58 "semantic/decorate/mode")
59 (declare-function pulse-momentary-highlight-region
"pulse")
60 (declare-function pulse-momentary-highlight-overlay
"pulse")
61 (declare-function semantic-symref-hits-in-region
"semantic/symref/filter")
65 ;;; TIMER RELATED FUNCTIONS
67 (defvar semantic-idle-scheduler-timer nil
68 "Timer used to schedule tasks in idle time.")
70 (defvar semantic-idle-scheduler-work-timer nil
71 "Timer used to schedule tasks in idle time that may take a while.")
73 (defcustom semantic-idle-scheduler-verbose-flag nil
74 "Non-nil means that the idle scheduler should provide debug messages.
75 Use this setting to debug idle activities."
79 (defcustom semantic-idle-scheduler-idle-time
1
80 "Time in seconds of idle before scheduling events.
81 This time should be short enough to ensure that idle-scheduler will be
82 run as soon as Emacs is idle."
85 :set
(lambda (sym val
)
87 (when (timerp semantic-idle-scheduler-timer
)
88 (cancel-timer semantic-idle-scheduler-timer
)
89 (setq semantic-idle-scheduler-timer nil
)
90 (semantic-idle-scheduler-setup-timers))))
92 (defcustom semantic-idle-scheduler-work-idle-time
60
93 "Time in seconds of idle before scheduling big work.
94 This time should be long enough that once any big work is started, it is
95 unlikely the user would be ready to type again right away."
98 :set
(lambda (sym val
)
100 (when (timerp semantic-idle-scheduler-timer
)
101 (cancel-timer semantic-idle-scheduler-timer
)
102 (setq semantic-idle-scheduler-timer nil
)
103 (semantic-idle-scheduler-setup-timers))))
105 (defun semantic-idle-scheduler-setup-timers ()
106 "Lazy initialization of the auto parse idle timer."
107 ;; REFRESH THIS FUNCTION for XEMACS FOIBLES
108 (or (timerp semantic-idle-scheduler-timer
)
109 (setq semantic-idle-scheduler-timer
111 semantic-idle-scheduler-idle-time t
112 #'semantic-idle-scheduler-function
)))
113 (or (timerp semantic-idle-scheduler-work-timer
)
114 (setq semantic-idle-scheduler-work-timer
116 semantic-idle-scheduler-work-idle-time t
117 #'semantic-idle-scheduler-work-function
)))
120 (defun semantic-idle-scheduler-kill-timer ()
121 "Kill the auto parse idle timer."
122 (if (timerp semantic-idle-scheduler-timer
)
123 (cancel-timer semantic-idle-scheduler-timer
))
124 (setq semantic-idle-scheduler-timer nil
))
129 ;; The minor mode portion of this code just sets up the minor mode
130 ;; which does the initial scheduling of the idle timers.
133 (defcustom semantic-idle-scheduler-mode-hook nil
134 "Hook run at the end of the function `semantic-idle-scheduler-mode'."
138 (defvar semantic-idle-scheduler-mode nil
139 "Non-nil if idle-scheduler minor mode is enabled.
140 Use the command `semantic-idle-scheduler-mode' to change this variable.")
141 (make-variable-buffer-local 'semantic-idle-scheduler-mode
)
143 (defcustom semantic-idle-scheduler-max-buffer-size
0
144 "*Maximum size in bytes of buffers where idle-scheduler is enabled.
145 If this value is less than or equal to 0, idle-scheduler is enabled in
146 all buffers regardless of their size."
150 (defsubst semantic-idle-scheduler-enabled-p
()
151 "Return non-nil if idle-scheduler is enabled for this buffer.
152 idle-scheduler is disabled when debugging or if the buffer size
153 exceeds the `semantic-idle-scheduler-max-buffer-size' threshold."
154 (let* ((remote-file?
(when (stringp buffer-file-name
) (file-remote-p buffer-file-name
))))
155 (and semantic-idle-scheduler-mode
156 (not (and (boundp 'semantic-debug-enabled
)
157 semantic-debug-enabled
))
158 (not semantic-lex-debug
)
159 ;; local file should exist on disk
160 ;; remote file should have active connection
161 (or (and (null remote-file?
) (stringp buffer-file-name
)
162 (file-exists-p buffer-file-name
))
163 (and remote-file?
(file-remote-p buffer-file-name nil t
)))
164 (or (<= semantic-idle-scheduler-max-buffer-size
0)
165 (< (buffer-size) semantic-idle-scheduler-max-buffer-size
)))))
168 (define-minor-mode semantic-idle-scheduler-mode
169 "Minor mode to auto parse buffer following a change.
170 When this mode is off, a buffer is only rescanned for tokens when
171 some command requests the list of available tokens. When idle-scheduler
172 is enabled, Emacs periodically checks to see if the buffer is out of
173 date, and reparses while the user is idle (not typing.)
175 With prefix argument ARG, turn on if positive, otherwise off. The
176 minor mode can be turned on only if semantic feature is available and
177 the current buffer was set up for parsing. Return non-nil if the
178 minor mode is enabled."
180 (if semantic-idle-scheduler-mode
181 (if (not (and (featurep 'semantic
) (semantic-active-p)))
183 ;; Disable minor mode if semantic stuff not available
184 (setq semantic-idle-scheduler-mode nil
)
185 (error "Buffer %s was not set up idle time scheduling"
187 (semantic-idle-scheduler-setup-timers))))
189 (semantic-add-minor-mode 'semantic-idle-scheduler-mode
192 ;;; SERVICES services
194 ;; These are services for managing idle services.
196 (defvar semantic-idle-scheduler-queue nil
197 "List of functions to execute during idle time.
198 These functions will be called in the current buffer after that
199 buffer has had its tags made up to date. These functions
200 will not be called if there are errors parsing the
203 (defun semantic-idle-scheduler-add (function)
204 "Schedule FUNCTION to occur during idle time."
205 (add-to-list 'semantic-idle-scheduler-queue function
))
207 (defun semantic-idle-scheduler-remove (function)
208 "Unschedule FUNCTION to occur during idle time."
209 (setq semantic-idle-scheduler-queue
210 (delete function semantic-idle-scheduler-queue
)))
214 (defun semantic-idle-core-handler ()
215 "Core idle function that handles reparsing.
216 And also manages services that depend on tag values."
217 (when semantic-idle-scheduler-verbose-flag
218 (message "IDLE: Core handler..."))
219 (semantic-exit-on-input 'idle-timer
220 (let* ((inhibit-quit nil
)
221 (buffers (delq (current-buffer)
223 (mapcar #'(lambda (b)
224 (and (buffer-file-name b
)
227 safe
;; This safe is not used, but could be.
230 (when (semantic-idle-scheduler-enabled-p)
232 ;; First, reparse the current buffer.
233 (setq mode major-mode
234 safe
(semantic-safe "Idle Parse Error: %S"
235 ;(error "Goofy error 1")
236 (semantic-idle-scheduler-refresh-tags)
239 ;; Now loop over other buffers with same major mode, trying to
240 ;; update them as well. Stop on keypress.
242 (semantic-throw-on-input 'parsing-mode-buffers
)
243 (with-current-buffer b
244 (if (eq major-mode mode
)
245 (and (semantic-idle-scheduler-enabled-p)
246 (semantic-safe "Idle Parse Error: %S"
247 ;(error "Goofy error")
248 (semantic-idle-scheduler-refresh-tags)))
249 (push (current-buffer) others
))))
250 (setq buffers others
))
251 ;; If re-parse of current buffer completed, evaluate all other
252 ;; services. Stop on keypress.
254 ;; NOTE ON COMMENTED SAFE HERE
255 ;; We used to not execute the services if the buffer was
256 ;; unparsable. We now assume that they are lexically
257 ;; safe to do, because we have marked the buffer unparsable
258 ;; if there was a problem.
260 (dolist (service semantic-idle-scheduler-queue
)
262 (semantic-throw-on-input 'idle-queue
)
263 (when semantic-idle-scheduler-verbose-flag
264 (message "IDLE: execute service %s..." service
))
265 (semantic-safe (format "Idle Service Error %s: %%S" service
)
267 (when semantic-idle-scheduler-verbose-flag
268 (message "IDLE: execute service %s...done" service
))
271 ;; Finally loop over remaining buffers, trying to update them as
272 ;; well. Stop on keypress.
275 (semantic-throw-on-input 'parsing-other-buffers
)
276 (with-current-buffer b
277 (and (semantic-idle-scheduler-enabled-p)
278 (semantic-idle-scheduler-refresh-tags)))))
280 (when semantic-idle-scheduler-verbose-flag
281 (message "IDLE: Core handler...done")))
283 (defun semantic-debug-idle-function ()
284 "Run the Semantic idle function with debugging turned on."
286 (let ((debug-on-error t
))
287 (semantic-idle-core-handler)
290 (defun semantic-idle-scheduler-function ()
291 "Function run when after `semantic-idle-scheduler-idle-time'.
292 This function will reparse the current buffer, and if successful,
293 call additional functions registered with the timer calls."
294 (when (zerop (recursion-depth))
295 (let ((debug-on-error nil
))
296 (save-match-data (semantic-idle-core-handler))
302 ;; Unlike the shorter timer, the WORK timer will kick of tasks that
303 ;; may take a long time to complete.
304 (defcustom semantic-idle-work-parse-neighboring-files-flag nil
305 "*Non-nil means to parse files in the same dir as the current buffer.
306 Disable to prevent lots of excessive parsing in idle time."
310 (defcustom semantic-idle-work-update-headers-flag nil
311 "*Non-nil means to parse through header files in idle time.
312 Disable to prevent idle time parsing of many files. If completion
313 is called that work will be done then instead."
317 (defun semantic-idle-work-for-one-buffer (buffer)
318 "Do long-processing work for BUFFER.
319 Uses `semantic-safe' and returns the output.
320 Returns t if all processing succeeded."
321 (with-current-buffer buffer
324 (semantic-safe "Idle Work Parse Error: %S"
325 (semantic-idle-scheduler-refresh-tags)
328 ;; Option to disable this work.
329 semantic-idle-work-update-headers-flag
331 ;; Force all our include files to get read in so we
332 ;; are ready to provide good smart completion and idle
333 ;; summary information
334 (semantic-safe "Idle Work Including Error: %S"
335 ;; Get the include related path.
336 (when (and (featurep 'semantic
/db
) (semanticdb-minor-mode-p))
337 (require 'semantic
/db-find
)
338 (semanticdb-find-translate-path buffer nil
)
342 ;; Pre-build the typecaches as needed.
343 (semantic-safe "Idle Work Typecaching Error: %S"
344 (when (featurep 'semantic
/db-typecache
)
345 (semanticdb-typecache-refresh-for-buffer buffer
))
350 (defun semantic-idle-work-core-handler ()
351 "Core handler for idle work processing of long running tasks.
352 Visits Semantic controlled buffers, and makes sure all needed
353 include files have been parsed, and that the typecache is up to date.
354 Uses `semantic-idle-work-for-on-buffer' to do the work."
357 (semantic-exit-on-input 'idle-work-timer
358 (let* ((inhibit-quit nil
)
359 (cb (current-buffer))
360 (buffers (delq (current-buffer)
362 (mapcar #'(lambda (b)
363 (and (buffer-file-name b
)
367 ;; First, handle long tasks in the current buffer.
368 (when (semantic-idle-scheduler-enabled-p)
370 (setq safe
(semantic-idle-work-for-one-buffer (current-buffer))
372 (when (not safe
) (push (current-buffer) errbuf
))
374 ;; Now loop over other buffers with same major mode, trying to
375 ;; update them as well. Stop on keypress.
377 (semantic-throw-on-input 'parsing-mode-buffers
)
378 (with-current-buffer b
379 (when (semantic-idle-scheduler-enabled-p)
380 (and (semantic-idle-scheduler-enabled-p)
381 (unless (semantic-idle-work-for-one-buffer (current-buffer))
382 (push (current-buffer) errbuf
)))
386 (when (and (featurep 'semantic
/db
) (semanticdb-minor-mode-p))
388 (semanticdb-save-all-db-idle)
390 ;; Parse up files near our active buffer
391 (when semantic-idle-work-parse-neighboring-files-flag
392 (semantic-safe "Idle Work Parse Neighboring Files: %S"
394 (semantic-idle-scheduler-work-parse-neighboring-files))
397 ;; Save everything... again
398 (semanticdb-save-all-db-idle)
401 ;; Done w/ processing
410 (format "done with 1 error in %s" (car errbuf
)))
412 (format "done with errors in %d buffers."
413 (length errbuf
)))))))
415 (defun semantic-debug-idle-work-function ()
416 "Run the Semantic idle work function with debugging turned on."
418 (let ((debug-on-error t
))
419 (semantic-idle-work-core-handler)
422 (defun semantic-idle-scheduler-work-function ()
423 "Function run when after `semantic-idle-scheduler-work-idle-time'.
424 This routine handles difficult tasks that require a lot of parsing, such as
425 parsing all the header files used by our active sources, or building up complex
427 (when semantic-idle-scheduler-verbose-flag
428 (message "Long Work Idle Timer..."))
429 (let ((exit-type (save-match-data
430 (semantic-idle-work-core-handler))))
431 (when semantic-idle-scheduler-verbose-flag
432 (message "Long Work Idle Timer...%s" exit-type
)))
435 (defun semantic-idle-scheduler-work-parse-neighboring-files ()
436 "Parse all the files in similar directories to buffers being edited."
437 ;; Let's tell EDE to ignore all the files we're about to load
438 (let ((ede-auto-add-method 'never
)
439 (matching-auto-mode-patterns nil
))
440 ;; Collect all patterns matching files of the same mode we edit.
441 (mapc (lambda (pat) (and (eq (cdr pat
) major-mode
)
442 (push (car pat
) matching-auto-mode-patterns
)))
444 ;; Loop over all files, and if one matches our mode, we force its
446 (dolist (file (directory-files default-directory t
".*" t
))
449 (semantic-throw-on-input 'parsing-mode-buffers
)
450 ;; We use string-match instead of passing the pattern
451 ;; into directory files, because some patterns don't
452 ;; work with directory files.
453 (and (string-match pat file
)
455 (semanticdb-file-table-object file
))
457 matching-auto-mode-patterns
)))))
462 ;; Reparsing is installed as semantic idle service.
463 ;; This part ALWAYS happens, and other services occur
466 (defvar semantic-before-idle-scheduler-reparse-hook nil
467 "Hook run before option `semantic-idle-scheduler' begins parsing.
468 If any hook function throws an error, this variable is reset to nil.
469 This hook is not protected from lexical errors.")
471 (defvar semantic-after-idle-scheduler-reparse-hook nil
472 "Hook run after option `semantic-idle-scheduler' has parsed.
473 If any hook function throws an error, this variable is reset to nil.
474 This hook is not protected from lexical errors.")
476 (semantic-varalias-obsolete 'semantic-before-idle-scheduler-reparse-hooks
477 'semantic-before-idle-scheduler-reparse-hook
"23.2")
478 (semantic-varalias-obsolete 'semantic-after-idle-scheduler-reparse-hooks
479 'semantic-after-idle-scheduler-reparse-hook
"23.2")
481 (defun semantic-idle-scheduler-refresh-tags ()
482 "Refreshes the current buffer's tags.
483 This is called by `semantic-idle-scheduler-function' to update the
484 tags in the current buffer.
486 Return non-nil if the refresh was successful.
487 Return nil if there is some sort of syntax error preventing a full
490 Does nothing if the current buffer doesn't need reparsing."
493 ;; These checks actually occur in `semantic-fetch-tags', but if we
494 ;; do them here, then all the bovination hooks are not run, and
495 ;; we save lots of time.
497 ;; If the buffer was previously marked unparsable,
498 ;; then don't waste our time.
499 ((semantic-parse-tree-unparseable-p)
501 ;; The parse tree is already ok.
502 ((semantic-parse-tree-up-to-date-p)
505 ;; If the buffer might need a reparse and it is safe to do so,
507 (let* (;(semantic-working-type nil)
509 ;; (working-use-echo-area-p
510 ;; (not semantic-idle-scheduler-working-in-modeline-flag))
511 ;; (working-status-dynamic-type
512 ;; (if semantic-idle-scheduler-no-working-message
514 ;; working-status-dynamic-type))
515 ;; (working-status-percentage-type
516 ;; (if semantic-idle-scheduler-no-working-message
518 ;; working-status-percentage-type))
521 ;; Let people hook into this, but don't let them hose
524 (run-hooks 'semantic-before-idle-scheduler-reparse-hook
)
525 (error (setq semantic-before-idle-scheduler-reparse-hook nil
)))
528 ;; Perform the parsing.
530 (when semantic-idle-scheduler-verbose-flag
531 (message "IDLE: reparse %s..." (buffer-name)))
532 (when (semantic-lex-catch-errors idle-scheduler
533 (save-excursion (semantic-fetch-tags))
535 ;; If we are here, it is because the lexical step failed,
536 ;; probably due to unterminated lists or something like that.
538 ;; We do nothing, and just wait for the next idle timer
539 ;; to go off. In the meantime, remember this, and make sure
540 ;; no other idle services can get executed.
541 (setq lexically-safe nil
))
542 (when semantic-idle-scheduler-verbose-flag
543 (message "IDLE: reparse %s...done" (buffer-name))))
544 ;; Let people hook into this, but don't let them hose
547 (run-hooks 'semantic-after-idle-scheduler-reparse-hook
)
548 (error (setq semantic-after-idle-scheduler-reparse-hook nil
))))
549 ;; Return if we are lexically safe (from prog1)
552 ;; After updating the tags, handle any pending decorations for this
554 (require 'semantic
/decorate
/mode
)
555 (semantic-decorate-flush-pending-decorations (current-buffer))
561 ;; Idle Services are minor modes which enable or disable a services in
562 ;; the idle scheduler. Creating a new services only requires calling
563 ;; `semantic-create-idle-services' which does all the setup
564 ;; needed to create the minor mode that will enable or disable
565 ;; a services. The services must provide a single function.
567 ;; FIXME doc is incomplete.
568 (defmacro define-semantic-idle-service
(name doc
&rest forms
)
569 "Create a new idle services with NAME.
570 DOC will be a documentation string describing FORMS.
571 FORMS will be called during idle time after the current buffer's
572 semantic tag information has been updated.
573 This routine creates the following functions and variables:"
574 (let ((global (intern (concat "global-" (symbol-name name
) "-mode")))
575 (mode (intern (concat (symbol-name name
) "-mode")))
576 (hook (intern (concat (symbol-name name
) "-mode-hook")))
577 (map (intern (concat (symbol-name name
) "-mode-map")))
578 (setup (intern (concat (symbol-name name
) "-mode-setup")))
579 (func (intern (concat (symbol-name name
) "-idle-function"))))
582 (define-minor-mode ,global
583 ,(concat "Toggle " (symbol-name global
) ".
584 With ARG, turn the minor mode on if ARG is positive, off otherwise.
586 When this minor mode is enabled, `" (symbol-name mode
) "' is
587 turned on in every Semantic-supported buffer.")
590 :group
'semantic-modes
591 :require
'semantic
/idle
592 (semantic-toggle-minor-mode-globally
593 ',mode
(if ,global
1 -
1)))
595 ;; FIXME: Get rid of this when define-minor-mode does it for us.
597 ,(concat "Hook run at the end of function `" (symbol-name mode
) "'.")
602 (let ((km (make-sparse-keymap)))
604 ,(concat "Keymap for `" (symbol-name mode
) "'."))
606 (define-minor-mode ,mode
610 (if (not (and (featurep 'semantic
) (semantic-active-p)))
612 ;; Disable minor mode if semantic stuff not available
614 (error "Buffer %s was not set up for parsing"
616 ;; Enable the mode mode
617 (semantic-idle-scheduler-add #',func
))
618 ;; Disable the mode mode
619 (semantic-idle-scheduler-remove #',func
)))
621 (semantic-add-minor-mode ',mode
622 "") ; idle schedulers are quiet?
625 ,(concat "Perform idle activity for the minor mode `"
626 (symbol-name mode
) "'.")
628 (put 'define-semantic-idle-service
'lisp-indent-function
1)
629 (add-hook 'edebug-setup-hook
631 (def-edebug-spec define-semantic-idle-service
632 (&define name stringp def-body
))))
636 ;; A mode similar to eldoc using semantic
637 (defcustom semantic-idle-truncate-long-summaries t
638 "Truncate summaries that are too long to fit in the minibuffer.
639 This can prevent minibuffer resizing in idle time."
643 (defcustom semantic-idle-summary-function
644 'semantic-format-tag-summarize-with-file
645 "Function to call when displaying tag information during idle time.
646 This function should take a single argument, a Semantic tag, and
647 return a string to display.
648 Some useful functions are found in `semantic-format-tag-functions'."
650 :type semantic-format-tag-custom-list
)
652 (defsubst semantic-idle-summary-find-current-symbol-tag
(sym)
653 "Search for a semantic tag with name SYM in database tables.
654 Return the tag found or nil if not found.
655 If semanticdb is not in use, use the current buffer only."
656 (car (if (and (featurep 'semantic
/db
)
657 semanticdb-current-database
658 (require 'semantic
/db-find
))
659 (cdar (semanticdb-deep-find-tags-by-name sym
))
660 (semantic-deep-find-tags-by-name sym
(current-buffer)))))
662 (defun semantic-idle-summary-current-symbol-info-brutish ()
663 "Return a string message describing the current context.
664 Gets a symbol with `semantic-ctxt-current-thing' and then
665 tries to find it with a deep targeted search."
666 ;; Try the current "thing".
667 (let ((sym (car (semantic-ctxt-current-thing))))
669 (semantic-idle-summary-find-current-symbol-tag sym
))))
671 (defun semantic-idle-summary-current-symbol-keyword ()
672 "Return a string message describing the current symbol.
673 Returns a value only if it is a keyword."
674 ;; Try the current "thing".
675 (let ((sym (car (semantic-ctxt-current-thing))))
676 (if (and sym
(semantic-lex-keyword-p sym
))
677 (semantic-lex-keyword-get sym
'summary
))))
679 (defun semantic-idle-summary-current-symbol-info-context ()
680 "Return a string message describing the current context.
681 Use the semantic analyzer to find the symbol information."
682 (let ((analysis (condition-case nil
683 (semantic-analyze-current-context (point))
686 (require 'semantic
/analyze
)
687 (semantic-analyze-interesting-tag analysis
))))
689 (defun semantic-idle-summary-current-symbol-info-default ()
690 "Return a string message describing the current context.
691 This function will disable loading of previously unloaded files
692 by semanticdb as a time-saving measure."
693 (semanticdb-without-unloaded-file-searches
695 ;; use whichever has success first.
697 (semantic-idle-summary-current-symbol-keyword)
699 (semantic-idle-summary-current-symbol-info-context)
701 (semantic-idle-summary-current-symbol-info-brutish)
704 (defvar semantic-idle-summary-out-of-context-faces
706 font-lock-comment-face
707 font-lock-string-face
708 font-lock-doc-string-face
; XEmacs.
709 font-lock-doc-face
; Emacs 21 and later.
711 "List of font-lock faces that indicate a useless summary context.
712 Those are generally faces used to highlight comments.
714 It might be useful to override this variable to add comment faces
715 specific to a major mode. For example, in jde mode:
717 \(defvar-mode-local jde-mode semantic-idle-summary-out-of-context-faces
718 (append (default-value 'semantic-idle-summary-out-of-context-faces)
719 '(jde-java-font-lock-doc-tag-face
720 jde-java-font-lock-link-face
721 jde-java-font-lock-bold-face
722 jde-java-font-lock-underline-face
723 jde-java-font-lock-pre-face
724 jde-java-font-lock-code-face)))")
726 (defun semantic-idle-summary-useful-context-p ()
727 "Non-nil if we should show a summary based on context."
728 (if (and (boundp 'font-lock-mode
)
730 (memq (get-text-property (point) 'face
)
731 semantic-idle-summary-out-of-context-faces
))
732 ;; The best I can think of at the moment is to disable
733 ;; in comments by detecting with font-lock.
737 (define-overloadable-function semantic-idle-summary-current-symbol-info
()
738 "Return a string message describing the current context.")
740 (make-obsolete-overload 'semantic-eldoc-current-symbol-info
741 'semantic-idle-summary-current-symbol-info
744 (defcustom semantic-idle-summary-mode-hook nil
745 "Hook run at the end of `semantic-idle-summary'."
749 (defun semantic-idle-summary-idle-function ()
750 "Display a tag summary of the lexical token under the cursor.
751 Call `semantic-idle-summary-current-symbol-info' for getting the
752 current tag to display information."
753 (or (eq major-mode
'emacs-lisp-mode
)
754 (not (semantic-idle-summary-useful-context-p))
755 (let* ((found (semantic-idle-summary-current-symbol-info))
756 (str (cond ((stringp found
) found
)
757 ((semantic-tag-p found
)
758 (funcall semantic-idle-summary-function
760 ;; Show the message with eldoc functions
761 (unless (and str
(boundp 'eldoc-echo-area-use-multiline-p
)
762 eldoc-echo-area-use-multiline-p
)
763 (let ((w (1- (window-width (minibuffer-window)))))
764 (if (> (length str
) w
)
765 (setq str
(substring str
0 w
)))))
766 ;; I borrowed some bits from eldoc to shorten the
768 (when semantic-idle-truncate-long-summaries
769 (let ((ea-width (1- (window-width (minibuffer-window))))
770 (strlen (length str
)))
771 (when (> strlen ea-width
)
772 (setq str
(substring str
0 ea-width
)))))
774 (eldoc-message str
))))
776 (define-minor-mode semantic-idle-summary-mode
777 "Toggle Semantic Idle Summary mode.
778 With ARG, turn Semantic Idle Summary mode on if ARG is positive,
781 When this minor mode is enabled, the echo area displays a summary
782 of the lexical token at point whenever Emacs is idle."
784 :group
'semantic-modes
785 (if semantic-idle-summary-mode
788 (unless (and (featurep 'semantic
) (semantic-active-p))
789 ;; Disable minor mode if semantic stuff not available
790 (setq semantic-idle-summary-mode nil
)
791 (error "Buffer %s was not set up for parsing"
794 (semantic-idle-scheduler-add 'semantic-idle-summary-idle-function
)
795 (add-hook 'pre-command-hook
'semantic-idle-summary-refresh-echo-area t
))
797 (semantic-idle-scheduler-remove 'semantic-idle-summary-idle-function
)
798 (remove-hook 'pre-command-hook
'semantic-idle-summary-refresh-echo-area t
)))
800 (defun semantic-idle-summary-refresh-echo-area ()
801 (and semantic-idle-summary-mode
803 (if (and (not executing-kbd-macro
)
804 (not (and (boundp 'edebug-active
) edebug-active
))
805 (not cursor-in-echo-area
)
806 (not (eq (selected-window) (minibuffer-window))))
807 (eldoc-message eldoc-last-message
)
808 (setq eldoc-last-message nil
))))
810 (semantic-add-minor-mode 'semantic-idle-summary-mode
"")
812 (define-minor-mode global-semantic-idle-summary-mode
813 "Toggle Global Semantic Idle Summary mode.
814 With ARG, turn Global Semantic Idle Summary mode on if ARG is
815 positive, off otherwise.
817 When this minor mode is enabled, `semantic-idle-summary-mode' is
818 turned on in every Semantic-supported buffer."
821 :group
'semantic-modes
822 (semantic-toggle-minor-mode-globally
823 'semantic-idle-summary-mode
824 (if global-semantic-idle-summary-mode
1 -
1)))
827 ;;; Current symbol highlight
829 ;; This mode will use context analysis to perform highlighting
830 ;; of all uses of the symbol that is under the cursor.
832 ;; This is to mimic the Eclipse tool of a similar nature.
833 (defface semantic-idle-symbol-highlight
834 '((t :inherit region
))
835 "Face used for highlighting local symbols."
836 :group
'semantic-faces
)
837 (defvar semantic-idle-symbol-highlight-face
'semantic-idle-symbol-highlight
838 "Face used for highlighting local symbols.")
839 (make-obsolete-variable 'semantic-idle-symbol-highlight-face
840 "customize the face `semantic-idle-symbol-highlight' instead" "24.4" 'set
)
842 (defun semantic-idle-symbol-maybe-highlight (tag)
843 "Perhaps add highlighting to the symbol represented by TAG.
844 TAG was found as the symbol under point. If it happens to be
845 visible, then highlight it."
847 (let* ((region (when (and (semantic-tag-p tag
)
848 (semantic-tag-with-position-p tag
))
849 (semantic-tag-overlay tag
)))
850 (file (when (and (semantic-tag-p tag
)
851 (semantic-tag-with-position-p tag
))
852 (semantic-tag-file-name tag
)))
853 (buffer (when file
(get-file-buffer file
)))
854 ;; We use pulse, but we don't want the flashy version,
855 ;; just the stable version.
858 (cond ((semantic-overlay-p region
)
859 (with-current-buffer (semantic-overlay-buffer region
)
861 (goto-char (semantic-overlay-start region
))
862 (when (pos-visible-in-window-p
863 (point) (get-buffer-window (current-buffer) 'visible
))
864 (if (< (semantic-overlay-end region
) (point-at-eol))
865 (pulse-momentary-highlight-overlay
866 region semantic-idle-symbol-highlight-face
)
868 (pulse-momentary-highlight-region
869 (semantic-overlay-start region
)
871 semantic-idle-symbol-highlight-face
))))
874 (let ((start (aref region
0))
875 (end (aref region
1)))
877 (when buffer
(set-buffer buffer
))
878 ;; As a vector, we have no filename. Perhaps it is a
880 (when (and (<= end
(point-max))
881 (pos-visible-in-window-p
882 start
(get-buffer-window (current-buffer) 'visible
)))
884 (when (re-search-forward
885 (regexp-quote (semantic-tag-name tag
))
887 ;; This is likely it, give it a try.
888 (pulse-momentary-highlight-region
889 start
(if (<= end
(point-at-eol)) end
891 semantic-idle-symbol-highlight-face
)))
895 (define-semantic-idle-service semantic-idle-local-symbol-highlight
896 "Highlight the tag and symbol references of the symbol under point.
897 Call `semantic-analyze-current-context' to find the reference tag.
898 Call `semantic-symref-hits-in-region' to identify local references."
900 (when (semantic-idle-summary-useful-context-p)
902 (semanticdb-without-unloaded-file-searches
903 (semantic-analyze-current-context)))
904 (Hbounds (when ctxt
(oref ctxt bounds
)))
905 (target (when ctxt
(car (reverse (oref ctxt prefix
)))))
906 (tag (semantic-current-tag))
907 ;; We use pulse, but we don't want the flashy version,
908 ;; just the stable version.
911 ;; Highlight the original tag? Protect against problems.
913 (semantic-idle-symbol-maybe-highlight target
)
915 ;; Identify all hits in this current tag.
916 (when (semantic-tag-p target
)
917 (require 'semantic
/symref
/filter
)
918 (semantic-symref-hits-in-region
919 target
(lambda (start end prefix
)
920 (when (/= start
(car Hbounds
))
921 (pulse-momentary-highlight-region
922 start end semantic-idle-symbol-highlight-face
))
923 (semantic-throw-on-input 'symref-highlight
)
925 (semantic-tag-start tag
)
926 (semantic-tag-end tag
)))
931 (define-minor-mode global-semantic-idle-scheduler-mode
932 "Toggle global use of option `semantic-idle-scheduler-mode'.
933 The idle scheduler will automatically reparse buffers in idle time,
934 and then schedule other jobs setup with `semantic-idle-scheduler-add'.
935 If ARG is positive or nil, enable, if it is negative, disable."
938 :group
'semantic-modes
939 ;; When turning off, disable other idle modes.
940 (when (null global-semantic-idle-scheduler-mode
)
941 (global-semantic-idle-summary-mode -
1)
942 (global-semantic-idle-local-symbol-highlight-mode -
1)
943 (global-semantic-idle-completions-mode -
1))
944 (semantic-toggle-minor-mode-globally
945 'semantic-idle-scheduler-mode
946 (if global-semantic-idle-scheduler-mode
1 -
1)))
949 ;;; Completion Popup Mode
951 ;; This mode uses tooltips to display a (hopefully) short list of possible
952 ;; completions available for the text under point. It provides
953 ;; NO provision for actually filling in the values from those completions.
954 (defun semantic-idle-completions-end-of-symbol-p ()
955 "Return non-nil if the cursor is at the END of a symbol.
956 If the cursor is in the middle of a symbol, then we shouldn't be
957 doing fancy completions."
958 (not (looking-at "\\w\\|\\s_")))
960 (defun semantic-idle-completion-list-default ()
961 "Calculate and display a list of completions."
962 (when (and (semantic-idle-summary-useful-context-p)
963 (semantic-idle-completions-end-of-symbol-p))
964 ;; This mode can be fragile, hence don't raise errors, and only
965 ;; report problems if semantic-idle-scheduler-verbose-flag is
966 ;; non-nil. If something doesn't do what you expect, run the
967 ;; below command by hand instead.
969 (semanticdb-without-unloaded-file-searches
971 (semantic-complete-analyze-inline-idle)
974 (when semantic-idle-scheduler-verbose-flag
975 (message " %s" (error-message-string err
)))))
978 (define-semantic-idle-service semantic-idle-completions
979 "Toggle Semantic Idle Completions mode.
980 With ARG, turn Semantic Idle Completions mode on if ARG is
981 positive, off otherwise.
983 This minor mode only takes effect if Semantic is active and
984 `semantic-idle-scheduler-mode' is enabled.
986 When enabled, Emacs displays a list of possible completions at
987 idle time. The method for displaying completions is given by
988 `semantic-complete-inline-analyzer-idle-displayor-class'; the
989 default is to show completions inline.
991 While a completion is displayed, RET accepts the completion; M-n
992 and M-p cycle through completion alternatives; TAB attempts to
993 complete as far as possible, and cycles if no additional
994 completion is possible; and any other command cancels the
997 \\{semantic-complete-inline-map}"
998 ;; Add the ability to override sometime.
999 (semantic-idle-completion-list-default))
1002 ;;; Breadcrumbs for tag under point
1004 ;; Service that displays a breadcrumbs indication of the tag under
1005 ;; point and its parents in the header or mode line.
1008 (defcustom semantic-idle-breadcrumbs-display-function
1009 #'semantic-idle-breadcrumbs--display-in-header-line
1010 "Function to display the tag under point in idle time.
1011 This function should take a list of Semantic tags as its only
1012 argument. The tags are sorted according to their nesting order,
1013 starting with the outermost tag. The function should call
1014 `semantic-idle-breadcrumbs-format-tag-list-function' to convert
1015 the tag list into a string."
1018 (const :tag
"Display in header line"
1019 semantic-idle-breadcrumbs--display-in-header-line
)
1020 (const :tag
"Display in mode line"
1021 semantic-idle-breadcrumbs--display-in-mode-line
)
1022 (function :tag
"Other function")))
1024 (defcustom semantic-idle-breadcrumbs-format-tag-list-function
1025 #'semantic-idle-breadcrumbs--format-linear
1026 "Function to format the list of tags containing point.
1027 This function should take a list of Semantic tags and an optional
1028 maximum length of the produced string as its arguments. The
1029 maximum length is a hint and can be ignored. When the maximum
1030 length is omitted, an unconstrained string should be
1031 produced. The tags are sorted according to their nesting order,
1032 starting with the outermost tag. Single tags should be formatted
1033 using `semantic-idle-breadcrumbs-format-tag-function' unless
1034 special formatting is required."
1037 (const :tag
"Format tags as list, innermost last"
1038 semantic-idle-breadcrumbs--format-linear
)
1039 (const :tag
"Innermost tag with details, followed by remaining tags"
1040 semantic-idle-breadcrumbs--format-innermost-first
)
1041 (function :tag
"Other function")))
1043 (defcustom semantic-idle-breadcrumbs-format-tag-function
1044 #'semantic-format-tag-abbreviate
1045 "Function to call to format information about tags.
1046 This function should take a single argument, a Semantic tag, and
1047 return a string to display.
1048 Some useful functions are found in `semantic-format-tag-functions'."
1050 :type semantic-format-tag-custom-list
)
1052 (defcustom semantic-idle-breadcrumbs-separator
'mode-specific
1053 "Specify how to separate tags in the breadcrumbs string.
1054 An arbitrary string or a mode-specific scope nesting
1055 string (like, for example, \"::\" in C++, or \".\" in Java) can
1059 (const :tag
"Use mode specific separator"
1061 (string :tag
"Specify separator string")))
1063 (defcustom semantic-idle-breadcrumbs-header-line-prefix
1064 semantic-stickyfunc-indent-string
;; TODO not optimal
1065 "String used to indent the breadcrumbs string.
1066 Customize this string to match the space used by scrollbars and
1071 (defvar semantic-idle-breadcrumbs-popup-menu nil
1072 "Menu used when a tag displayed by `semantic-idle-breadcrumbs-mode' is clicked.")
1074 (defun semantic-idle-breadcrumbs--popup-menu (event)
1075 "Popup a menu that displays things to do to the clicked tag.
1076 Argument EVENT describes the event that caused this function to
1079 (let ((old-window (selected-window))
1080 (window (semantic-event-window event
)))
1081 (select-window window t
)
1082 (semantic-popup-menu semantic-idle-breadcrumbs-popup-menu
)
1083 (select-window old-window
)))
1085 (defmacro semantic-idle-breadcrumbs--tag-function
(function)
1086 "Return lambda expression calling FUNCTION when called from a popup."
1089 (let* ((old-window (selected-window))
1090 (window (semantic-event-window event
))
1091 (column (car (nth 6 (nth 1 event
)))) ;; TODO semantic-event-column?
1093 (select-window window t
)
1095 (text-properties-at column header-line-format
)
1098 (select-window old-window
)))
1101 ;; TODO does this work for mode-line case?
1102 (defvar semantic-idle-breadcrumbs-popup-map
1103 (let ((map (make-sparse-keymap)))
1104 ;; mouse-1 goes to clicked tag
1106 [ header-line mouse-1
]
1107 (semantic-idle-breadcrumbs--tag-function
1108 semantic-go-to-tag
))
1109 ;; mouse-3 pops up a context menu
1111 [ header-line mouse-3
]
1112 'semantic-idle-breadcrumbs--popup-menu
)
1114 "Keymap for semantic idle breadcrumbs minor mode.")
1117 semantic-idle-breadcrumbs-popup-menu
1118 semantic-idle-breadcrumbs-popup-map
1119 "Semantic Breadcrumbs Mode Menu"
1125 (semantic-idle-breadcrumbs--tag-function
1128 :help
"Jump to this tag"))
1129 ;; TODO these entries need minor changes (optional tag argument) in
1130 ;; senator-copy-tag etc
1131 ;; (semantic-menu-item
1134 ;; (semantic-idle-breadcrumbs--tag-function
1135 ;; senator-copy-tag)
1137 ;; :help "Copy this tag"))
1138 ;; (semantic-menu-item
1141 ;; (semantic-idle-breadcrumbs--tag-function
1142 ;; senator-kill-tag)
1144 ;; :help "Kill tag text to the kill ring, and copy the tag to
1146 ;; (semantic-menu-item
1148 ;; "Copy Tag to Register"
1149 ;; (semantic-idle-breadcrumbs--tag-function
1150 ;; senator-copy-tag-to-register)
1152 ;; :help "Copy this tag"))
1153 ;; (semantic-menu-item
1156 ;; (semantic-idle-breadcrumbs--tag-function
1157 ;; senator-narrow-to-defun)
1159 ;; :help "Narrow to the bounds of the current tag"))
1160 ;; (semantic-menu-item
1163 ;; (semantic-idle-breadcrumbs--tag-function
1164 ;; senator-fold-tag-toggle)
1167 ;; :selected '(let ((tag (semantic-current-tag)))
1168 ;; (and tag (semantic-tag-folded-p tag)))
1169 ;; :help "Fold the current tag to one line"))
1173 "About this Header Line"
1176 (describe-function 'semantic-idle-breadcrumbs-mode
))
1178 :help
"Display help about this header line."))
1182 (define-semantic-idle-service semantic-idle-breadcrumbs
1183 "Display breadcrumbs for the tag under point and its parents."
1184 (let* ((scope (semantic-calculate-scope))
1186 ;; If there is a scope, extract the tag and its
1188 (append (oref scope parents
)
1189 (when (oref scope tag
)
1190 (list (oref scope tag
))))
1191 ;; Fall back to tags by overlay
1192 (semantic-find-tag-by-overlay))))
1193 ;; Display the tags.
1194 (funcall semantic-idle-breadcrumbs-display-function tag-list
)))
1196 (defun semantic-idle-breadcrumbs--display-in-header-line (tag-list)
1197 "Display the tags in TAG-LIST in the header line of their buffer."
1198 (let ((width (- (nth 2 (window-edges))
1199 (nth 0 (window-edges)))))
1200 ;; Format TAG-LIST and put the formatted string into the header
1202 (setq header-line-format
1203 (replace-regexp-in-string ;; Since % is interpreted in the
1204 "\\(%\\)" "%\\1" ;; mode/header line format, we
1205 (concat ;; have to escape all occurrences.
1206 semantic-idle-breadcrumbs-header-line-prefix
1208 (semantic-idle-breadcrumbs--format-tag-list
1211 (length semantic-idle-breadcrumbs-header-line-prefix
)))
1215 'font-lock-comment-face
))))))
1217 ;; Update the header line.
1218 (force-mode-line-update))
1220 (defun semantic-idle-breadcrumbs--display-in-mode-line (tag-list)
1221 "Display the tags in TAG-LIST in the mode line of their buffer.
1222 TODO THIS FUNCTION DOES NOT WORK YET."
1224 (error "This function does not work yet")
1226 (let ((width (- (nth 2 (window-edges))
1227 (nth 0 (window-edges)))))
1228 (setq mode-line-format
1229 (replace-regexp-in-string ;; see comment in
1230 "\\(%\\)" "%\\1" ;; `semantic-idle-breadcrumbs--display-in-header-line'
1231 (semantic-idle-breadcrumbs--format-tag-list tag-list width
))))
1233 (force-mode-line-update))
1235 (defun semantic-idle-breadcrumbs--format-tag-list (tag-list max-length
)
1236 "Format TAG-LIST using configured functions respecting MAX-LENGTH.
1237 If the initial formatting result is longer than MAX-LENGTH, it is
1238 shortened at the beginning."
1239 ;; Format TAG-LIST using the configured formatting function.
1240 (let* ((complete-format (funcall
1241 semantic-idle-breadcrumbs-format-tag-list-function
1242 tag-list max-length
))
1243 ;; Determine length of complete format.
1244 (complete-length (length complete-format
)))
1245 ;; Shorten string if necessary.
1246 (if (<= complete-length max-length
)
1251 (- complete-length
(- max-length
4))))))
1254 (defun semantic-idle-breadcrumbs--format-linear
1255 (tag-list &optional max-length
)
1256 "Format TAG-LIST as a linear list, starting with the outermost tag.
1257 MAX-LENGTH is not used."
1258 (require 'semantic
/analyze
/fcn
)
1259 (let* ((format-pieces (mapcar
1260 #'semantic-idle-breadcrumbs--format-tag
1262 ;; Format tag list, putting configured separators between the
1264 (complete-format (cond
1265 ;; Mode specific separator.
1266 ((eq semantic-idle-breadcrumbs-separator
1268 (semantic-analyze-unsplit-name format-pieces
))
1270 ;; Custom separator.
1271 ((stringp semantic-idle-breadcrumbs-separator
)
1275 semantic-idle-breadcrumbs-separator
)))))
1279 (defun semantic-idle-breadcrumbs--format-innermost-first
1280 (tag-list &optional max-length
)
1281 "Format TAG-LIST placing the innermost tag first, separated from its parents.
1282 If MAX-LENGTH is non-nil, the innermost tag is shortened."
1283 (let* (;; Separate and format remaining tags. Calculate length of
1284 ;; resulting string.
1285 (rest-tags (butlast tag-list
))
1286 (rest-format (if rest-tags
1289 (semantic-idle-breadcrumbs--format-linear
1292 (rest-length (length rest-format
))
1293 ;; Format innermost tag and calculate length of resulting
1295 (inner-format (semantic-idle-breadcrumbs--format-tag
1296 (car (last tag-list
))
1297 #'semantic-format-tag-prototype
))
1298 (inner-length (length inner-format
))
1299 ;; Calculate complete length and shorten string for innermost
1300 ;; tag if MAX-LENGTH is non-nil and the complete string is
1302 (complete-length (+ inner-length rest-length
))
1303 (inner-short (if (and max-length
1304 (<= complete-length max-length
))
1310 (- complete-length max-length
)
1313 ;; Concat both parts.
1314 (concat inner-short rest-format
))
1317 (defun semantic-idle-breadcrumbs--format-tag (tag &optional format-function
)
1318 "Format TAG using the configured function or FORMAT-FUNCTION.
1319 This function also adds text properties for help-echo, mouse
1320 highlighting and a keymap."
1321 (let ((formatted (funcall
1323 semantic-idle-breadcrumbs-format-tag-function
)
1325 (add-text-properties
1326 0 (length formatted
)
1334 mouse-1: jump to tag
1335 mouse-3: popup context menu"
1336 (semantic-tag-name tag
)
1337 (semantic-tag-class tag
))
1341 semantic-idle-breadcrumbs-popup-map
)
1346 (provide 'semantic
/idle
)
1349 ;; generated-autoload-file: "loaddefs.el"
1350 ;; generated-autoload-load-name: "semantic/idle"
1353 ;;; semantic/idle.el ends here