lisp/cedet/semantic/symref/list.el

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