lisp/cedet/semantic/symref/list.el

   1 ;;; semantic/symref/list.el --- Symref Output List UI.
   2
   3 ;; Copyright (C) 2008-2014 Free Software Foundation, Inc.
   4
   5 ;; Author: Eric M. Ludlam <eric@siege-engine.com>
   6
   7 ;; This file is part of GNU Emacs.
   8
   9 ;; GNU Emacs is free software: you can redistribute it and/or modify
  10 ;; it under the terms of the GNU General Public License as published by
  11 ;; the Free Software Foundation, either version 3 of the License, or
  12 ;; (at your option) any later version.
  13
  14 ;; GNU Emacs is distributed in the hope that it will be useful,
  15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ;; GNU General Public License for more details.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 ;;; Commentary:
  23 ;;
  24 ;; Provide a simple user facing API to finding symbol references.
  25 ;;
  26 ;; This UI is the base of some refactoring tools.  For any refactor,
  27 ;; the user will execute `semantic-symref' in a tag.
  28 ;; Once that data is collected, the output will be listed in a buffer.
  29 ;; In the output buffer, the user can then initiate different
  30 ;; refactoring operations.
  31 ;;
  32 ;; NOTE: Need to add some refactoring tools.
  33
  34 (require 'semantic/symref)
  35 (require 'semantic/complete)
  36 (require 'semantic/senator)
  37 (require 'pulse)
  38
  39 ;;; Code:
  40
  41 ;;;###autoload
  42 (defun semantic-symref ()
  43   "Find references to the current tag.
  44 This command uses the currently configured references tool within the
  45 current project to find references to the current tag.  The
  46 references are organized by file and the name of the function
  47 they are used in.
  48 Display the references in `semantic-symref-results-mode'."
  49   (interactive)
  50   (semantic-fetch-tags)
  51   (let ((ct (semantic-current-tag)))
  52     ;; Must have a tag...
  53     (when (not ct) (error "Place cursor inside tag to be searched for"))
  54     ;; Check w/ user.
  55     (when (not (y-or-n-p (format "Find references for %s? "
  56                                  (semantic-tag-name ct))))
  57       (error "Quit"))
  58     ;; Gather results and tags
  59     (message "Gathering References...")
  60     (let* ((name (semantic-tag-name ct))
  61            (res (semantic-symref-find-references-by-name name)))
  62       (semantic-symref-produce-list-on-results res name))))
  63
  64 ;;;###autoload
  65 (defun semantic-symref-symbol (sym)
  66   "Find references to the symbol SYM.
  67 This command uses the currently configured references tool within the
  68 current project to find references to the input SYM.  The
  69 references are organized by file and the name of the function
  70 they are used in.
  71 Display the references in `semantic-symref-results-mode'."
  72   (interactive (list (semantic-tag-name (semantic-complete-read-tag-project
  73                                          "Symrefs for: "))))
  74   (semantic-fetch-tags)
  75   ;; Gather results and tags
  76   (message "Gathering References...")
  77   (let ((res (semantic-symref-find-references-by-name sym)))
  78     (semantic-symref-produce-list-on-results res sym)))
  79
  80 ;;;###autoload
  81 (defun semantic-symref-regexp (sym)
  82   "Find references to the a symbol regexp SYM.
  83 This command uses the currently configured references tool within the
  84 current project to find references to the input SYM.  The
  85 references are the organized by file and the name of the function
  86 they are used in.
  87 Display the references in`semantic-symref-results-mode'."
  88   (interactive (list (semantic-tag-name (semantic-complete-read-tag-buffer-deep
  89                                          "Symrefs for: "))))
  90   (semantic-fetch-tags)
  91   (message "Gathering References...")
  92   ;; Gather results and tags
  93   (let ((res (semantic-symref-find-text sym)))
  94     (semantic-symref-produce-list-on-results res sym)))
  95
  96 ;;; RESULTS MODE
  97 ;;
  98 (defgroup semantic-symref-results-mode nil
  99   "Symref Results group."
 100   :group 'semantic)
 101
 102 (defvar semantic-symref-results-mode-map
 103   (let ((km (make-sparse-keymap)))
 104     (suppress-keymap km)
 105     (define-key km "\C-i" 'forward-button)
 106     (define-key km "\M-C-i" 'backward-button)
 107     (define-key km " " 'push-button)
 108     (define-key km "-" 'semantic-symref-list-toggle-showing)
 109     (define-key km "=" 'semantic-symref-list-toggle-showing)
 110     (define-key km "+" 'semantic-symref-list-toggle-showing)
 111     (define-key km "n" 'semantic-symref-list-next-line)
 112     (define-key km "p" 'semantic-symref-list-prev-line)
 113     (define-key km "q" 'semantic-symref-hide-buffer)
 114     (define-key km "\C-c\C-e" 'semantic-symref-list-expand-all)
 115     (define-key km "\C-c\C-r" 'semantic-symref-list-contract-all)
 116     (define-key km "R" 'semantic-symref-list-rename-open-hits)
 117     (define-key km "(" 'semantic-symref-list-create-macro-on-open-hit)
 118     (define-key km "E" 'semantic-symref-list-call-macro-on-open-hits)
 119     km)
 120   "Keymap used in `semantic-symref-results-mode'.")
 121
 122 (defvar semantic-symref-list-menu-entries
 123   (list
 124    "Symref"
 125    (semantic-menu-item
 126     ["Toggle Line Open"
 127      semantic-symref-list-toggle-showing
 128      :active t
 129      :help "Toggle the current line open or closed."
 130      ])
 131    (semantic-menu-item
 132     ["Expand All Entries"
 133      semantic-symref-list-expand-all
 134      :active t
 135      :help "Expand every expandable entry."
 136      ])
 137    (semantic-menu-item
 138     ["Contract All Entries"
 139      semantic-symref-list-contract-all
 140      :active t
 141      :help "Close every expandable entry."
 142      ])
 143    (semantic-menu-item
 144     ["Rename Symbol in Open hits"
 145      semantic-symref-list-rename-open-hits
 146      :active t
 147      :help "Rename the searched for symbol in all hits that are currently open."
 148      ])
 149    )
 150   "Menu entries for the Semantic Symref list mode.")
 151
 152 (defvar semantic-symref-list-menu nil
 153   "Menu keymap build from `semantic-symref-results-mode'.")
 154
 155 (easy-menu-define semantic-symref-list-menu
 156   semantic-symref-results-mode-map
 157   "Symref Mode Menu"
 158   semantic-symref-list-menu-entries)
 159
 160 (defcustom semantic-symref-auto-expand-results nil
 161   "Non-nil to expand symref results on buffer creation."
 162   :type 'boolean)
 163
 164 (defcustom semantic-symref-results-mode-hook nil
 165   "Hook run when `semantic-symref-results-mode' starts."
 166   :type 'hook)
 167
 168 (defvar semantic-symref-current-results nil
 169   "The current results in a results mode buffer.")
 170
 171 (defun semantic-symref-produce-list-on-results (res str)
 172   "Produce a symref list mode buffer on the results RES."
 173   (when (not res) (error "No references found"))
 174   (semantic-symref-result-get-tags res t)
 175   (message "Gathering References...done")
 176   ;; Build a references buffer.
 177   (let ((buff (get-buffer-create (format "*Symref %s" str))))
 178     (switch-to-buffer-other-window buff)
 179     (set-buffer buff)
 180     (semantic-symref-results-mode)
 181     (set (make-local-variable 'semantic-symref-current-results) res)
 182     (semantic-symref-results-dump res)
 183     (goto-char (point-min))))
 184
 185 (define-derived-mode semantic-symref-results-mode nil "Symref"
 186   "Major-mode for displaying Semantic Symbol Reference results."
 187   (buffer-disable-undo)
 188   ;; FIXME: Why bother turning off font-lock?
 189   (set (make-local-variable 'font-lock-global-modes) nil)
 190   (font-lock-mode -1))
 191
 192 (defun semantic-symref-hide-buffer ()
 193   "Hide buffer with semantic-symref results."
 194   (interactive)
 195   (bury-buffer))
 196
 197 (defcustom semantic-symref-results-summary-function 'semantic-format-tag-prototype
 198   "Function to use when creating items in Imenu.
 199 Some useful functions are found in `semantic-format-tag-functions'."
 200   :type semantic-format-tag-custom-list)
 201
 202 (defun semantic-symref-results-dump (results)
 203   "Dump the RESULTS into the current buffer."
 204   ;; Get ready for the insert.
 205   (let ((inhibit-read-only t))
 206     (erase-buffer)
 207     ;; Insert the contents.
 208     (let ((lastfile nil))
 209       (dolist (T (oref results :hit-tags))
 210         (unless (equal lastfile (semantic-tag-file-name T))
 211           (setq lastfile (semantic-tag-file-name T))
 212           (insert-button lastfile
 213                          'mouse-face 'custom-button-pressed-face
 214                          'action 'semantic-symref-rb-goto-file
 215                          'tag T)
 216           (insert "\n"))
 217         (insert "  ")
 218         (insert-button "[+]"
 219                        'mouse-face 'highlight
 220                        'face nil
 221                        'action 'semantic-symref-rb-toggle-expand-tag
 222                        'tag T
 223                        'state 'closed)
 224         (insert " ")
 225         (insert-button (funcall semantic-symref-results-summary-function
 226                                 T nil t)
 227                        'mouse-face 'custom-button-pressed-face
 228                        'face nil
 229                        'action 'semantic-symref-rb-goto-tag
 230                        'tag T)
 231         (insert "\n")))
 232     ;; Auto expand
 233     (when semantic-symref-auto-expand-results
 234       (semantic-symref-list-expand-all)))
 235     ;; Clean up the mess
 236   (set-buffer-modified-p nil))
 237
 238 ;;; Commands for semantic-symref-results
 239 ;;
 240 (defun semantic-symref-list-toggle-showing ()
 241   "Toggle showing the contents below the current line."
 242   (interactive)
 243   (beginning-of-line)
 244   (when (re-search-forward "\\[[-+]\\]" (point-at-eol) t)
 245     (forward-char -1)
 246     (push-button)))
 247
 248 (defun semantic-symref-rb-toggle-expand-tag (&optional button)
 249   "Go to the file specified in the symref results buffer.
 250 BUTTON is the button that was clicked."
 251   (interactive)
 252   (let* ((tag (button-get button 'tag))
 253          (buff (semantic-tag-buffer tag))
 254          (hits (semantic--tag-get-property tag :hit))
 255          (state (button-get button 'state))
 256          (text nil))
 257     (cond
 258      ((eq state 'closed)
 259       (with-current-buffer buff
 260         (dolist (H hits)
 261           (goto-char (point-min))
 262           (forward-line (1- H))
 263           (beginning-of-line)
 264           (back-to-indentation)
 265           (setq text (cons (buffer-substring (point) (point-at-eol)) text)))
 266         (setq text (nreverse text)))
 267       (goto-char (button-start button))
 268       (forward-char 1)
 269       (let ((inhibit-read-only t))
 270         (delete-char 1)
 271         (insert "-")
 272         (button-put button 'state 'open)
 273         (save-excursion
 274           (end-of-line)
 275           (while text
 276             (insert "\n")
 277             (insert "    ")
 278             (insert-button (car text)
 279                            'mouse-face 'highlight
 280                            'face nil
 281                            'action 'semantic-symref-rb-goto-match
 282                            'tag tag
 283                            'line (car hits))
 284             (setq text (cdr text)
 285                   hits (cdr hits))))))
 286      ((eq state 'open)
 287       (let ((inhibit-read-only t))
 288         (button-put button 'state 'closed)
 289         ;; Delete the various bits.
 290         (goto-char (button-start button))
 291         (forward-char 1)
 292         (delete-char 1)
 293         (insert "+")
 294         (save-excursion
 295           (end-of-line)
 296           (forward-char 1)
 297           (delete-region (point)
 298                          (save-excursion
 299                            (forward-char 1)
 300                            (forward-line (length hits))
 301                            (point)))))))))
 302
 303 (defun semantic-symref-rb-goto-file (&optional button)
 304   "Go to the file specified in the symref results buffer.
 305 BUTTON is the button that was clicked."
 306   (let* ((tag (button-get button 'tag))
 307          (buff (semantic-tag-buffer tag))
 308          (win (selected-window))
 309          )
 310     (switch-to-buffer-other-window buff)
 311     (pulse-momentary-highlight-one-line (point))
 312     (when (eq last-command-event ?\s) (select-window win))
 313     ))
 314
 315
 316 (defun semantic-symref-rb-goto-tag (&optional button)
 317   "Go to the file specified in the symref results buffer.
 318 BUTTON is the button that was clicked."
 319   (interactive)
 320   (let* ((tag (button-get button 'tag))
 321          (buff (semantic-tag-buffer tag))
 322          (win (selected-window))
 323          )
 324     (switch-to-buffer-other-window buff)
 325     (semantic-go-to-tag tag)
 326     (pulse-momentary-highlight-one-line (point))
 327     (when (eq last-command-event ?\s) (select-window win))
 328     )
 329   )
 330
 331 (defun semantic-symref-rb-goto-match (&optional button)
 332   "Go to the file specified in the symref results buffer.
 333 BUTTON is the button that was clicked."
 334   (interactive)
 335   (let* ((tag (button-get button 'tag))
 336          (line (button-get button 'line))
 337          (buff (semantic-tag-buffer tag))
 338          (win (selected-window))
 339          )
 340     (switch-to-buffer-other-window buff)
 341     (goto-char (point-min))
 342     (forward-line (1- line))
 343     (pulse-momentary-highlight-one-line (point))
 344     (when (eq last-command-event ?\s) (select-window win))
 345     )
 346   )
 347
 348 (defun semantic-symref-list-next-line ()
 349   "Next line in `semantic-symref-results-mode'."
 350   (interactive)
 351   (forward-line 1)
 352   (back-to-indentation))
 353
 354 (defun semantic-symref-list-prev-line ()
 355   "Next line in `semantic-symref-results-mode'."
 356   (interactive)
 357   (forward-line -1)
 358   (back-to-indentation))
 359
 360 (defun semantic-symref-list-expand-all ()
 361   "Expand all the nodes in the current buffer."
 362   (interactive)
 363   (let ((start (make-marker)))
 364     (move-marker start (point))
 365     (goto-char (point-min))
 366     (while (re-search-forward "\\[[+]\\]" nil t)
 367       (semantic-symref-list-toggle-showing))
 368     ;; Restore position
 369     (goto-char start)))
 370
 371 (defun semantic-symref-list-contract-all ()
 372   "Expand all the nodes in the current buffer."
 373   (interactive)
 374   (let ((start (make-marker)))
 375     (move-marker start (point))
 376     (goto-char (point-min))
 377     (while (re-search-forward "\\[[-]\\]" nil t)
 378       (semantic-symref-list-toggle-showing))
 379     ;; Restore position
 380     (goto-char start)))
 381
 382 ;;; UTILS
 383 ;;
 384 ;; List mode utils for understanding the current line
 385
 386 (defun semantic-symref-list-on-hit-p ()
 387   "Return the line number if the cursor is on a buffer line with a hit.
 388 Hits are the line of code from the buffer, not the tag summar or file lines."
 389   (save-excursion
 390     (end-of-line)
 391     (let* ((ol (car (semantic-overlays-at (1- (point)))))) ;; trust this for now
 392       (when ol (semantic-overlay-get ol 'line)))))
 393
 394
 395 ;;; Keyboard Macros on a Hit
 396 ;;
 397 ;; Record a macro on a hit, and store in a special way for execution later.
 398 (defun semantic-symref-list-create-macro-on-open-hit ()
 399   "Record a keyboard macro at the location of the hit in the current list.
 400 Under point should be one hit for the active keyword.  Move
 401 cursor to the beginning of that symbol, then record a macro as if
 402 `kmacro-start-macro' was pressed.  Use `kmacro-end-macro',
 403 {kmacro-end-macro} to end the macro, and return to the symbol found list."
 404   (interactive)
 405   (let* ((oldsym (oref (oref semantic-symref-current-results
 406                             :created-by)
 407                       :searchfor))
 408          (ol (save-excursion
 409                (end-of-line)
 410                (car (semantic-overlays-at (1- (point))))))
 411          (tag (when ol (semantic-overlay-get ol 'tag)))
 412          (line (when ol (semantic-overlay-get ol 'line))))
 413     (when (not line)
 414       (error "Cannot create macro on a non-hit line"))
 415     ;; Go there, and do something useful.
 416     (switch-to-buffer-other-window (semantic-tag-buffer tag))
 417     (goto-char (point-min))
 418     (forward-line (1- line))
 419     (when (not (re-search-forward (regexp-quote oldsym) (point-at-eol) t))
 420       (error "Cannot find hit.  Cannot record macro"))
 421     (goto-char (match-beginning 0))
 422     ;; Cursor is now in the right location.  Start recording a macro.
 423     (kmacro-start-macro nil)
 424     ;; Notify the user
 425     (message "Complete with C-x ).  Use E in the symref buffer to call this macro.")))
 426
 427 (defun semantic-symref-list-call-macro-on-open-hits ()
 428   "Call the most recently created keyboard macro on each hit.
 429 Cursor is placed at the beginning of the symbol found, even if
 430 there is more than one symbol on the current line.  The
 431 previously recorded macro is then executed."
 432   (interactive)
 433   (save-window-excursion
 434     (let ((count (semantic-symref-list-map-open-hits
 435                   (lambda ()
 436                     (switch-to-buffer (current-buffer))
 437                     (kmacro-call-macro nil)))))
 438       (semantic-symref-list-update-open-hits)
 439       (message "Executed Macro %d times." count))))
 440
 441 ;;; REFACTORING EDITS
 442 ;;
 443 ;; Utilities and features for refactoring across a list of hits.
 444 ;;
 445 (defun semantic-symref-list-rename-open-hits (newname)
 446   "Rename the discovered symbol references to NEWNAME.
 447 Only renames the locations that are open in the symref list.
 448 Closed items will be skipped."
 449   (interactive
 450    (list (read-string "Rename to: "
 451                       (oref (oref semantic-symref-current-results
 452                                   :created-by)
 453                             :searchfor))))
 454   (let ((count (semantic-symref-list-map-open-hits
 455                 (lambda () (replace-match newname nil t)))))
 456     (semantic-symref-list-update-open-hits)
 457     (message "Renamed %d occurrences." count)))
 458
 459 ;;; REFACTORING UTILITIES
 460 ;;
 461 ;; Refactoring tools want to operate on only the "good" stuff the
 462 ;; user selected.
 463 (defun semantic-symref-list-map-open-hits (function)
 464   "For every open hit in the symref buffer, perform FUNCTION.
 465 The `match-data' will be set to a successful hit of the searched for symbol.
 466 Return the number of occurrences FUNCTION was operated upon."
 467
 468   ;; First Pass in this function - a straight rename.
 469   ;; Second Pass - Allow context specification based on
 470   ;;               class members. (Not Done)
 471
 472   (let ((oldsym (oref (oref semantic-symref-current-results
 473                             :created-by)
 474                       :searchfor))
 475         (count 0))
 476     (save-excursion
 477       (goto-char (point-min))
 478       (while (not (eobp))
 479         ;; Is this line a "hit" line?
 480         (let* ((ol (car (semantic-overlays-at (1- (point))))) ;; trust this for now
 481                (tag (when ol (semantic-overlay-get ol 'tag)))
 482                (line (when ol (semantic-overlay-get ol 'line))))
 483           (when line
 484             ;; The "line" means we have an open hit.
 485             (with-current-buffer (semantic-tag-buffer tag)
 486               (goto-char (point-min))
 487               (forward-line (1- line))
 488               (beginning-of-line)
 489               (while (re-search-forward (regexp-quote oldsym) (point-at-eol) t)
 490                 (setq count (1+ count))
 491                 (save-excursion ;; Leave cursor after the matched name.
 492                   (goto-char (match-beginning 0)) ;; Go to beginning of that sym
 493                   (funcall function))))))
 494         ;; Go to the next line
 495         (forward-line 1)
 496         (end-of-line)))
 497     count))
 498
 499 (defun semantic-symref-list-update-open-hits ()
 500   "Update the text for all the open hits in the symref list."
 501   (save-excursion
 502     (goto-char (point-min))
 503     (while (re-search-forward "\\[-\\]" nil t)
 504       (end-of-line)
 505       (let* ((ol (car (semantic-overlays-at (1- (point))))) ;; trust this for now
 506              (tag (when ol (semantic-overlay-get ol 'tag))))
 507         ;; If there is a tag, then close/open it.
 508         (when tag
 509           (semantic-symref-list-toggle-showing)
 510           (semantic-symref-list-toggle-showing))))))
 511
 512 (provide 'semantic/symref/list)
 513
 514 ;; Local variables:
 515 ;; generated-autoload-file: "../loaddefs.el"
 516 ;; generated-autoload-load-name: "semantic/symref/list"
 517 ;; End:
 518
 519 ;;; semantic/symref/list.el ends here