Commentary

Bitcoin donations gratefully accepted: 1AmWPmshr6i9gajMi1yqHgx7BYzpPKuzMz

Introduction

This library can be used to display a buffer containing a call tree for functions in source code files. You can easily & quickly navigate the call tree, displaying the code in another window, and apply query-replace or other commands to individual functions.

When the command `simple-call-tree-display-buffer’ or `simple-call-tree-current-function’ is executed a call tree for the functions in the current buffer will be created, and in the latter case the point in the call tree is placed on the header closest to its position in the original buffer. If called with a prefix arg the user is also prompted for other files to include in the call tree. By default the call tree is displayed in a buffer called Simple Call Tree: <BUFNAME>, where <BUFNAME> is the name of the buffer that the call tree was created from. There is a dedicated menu in the menu-bar showing various commands and their keybindings. Most of these commands are self explanatory so try them out.

Navigation

You can navigate the call tree either by moving through consecutive headers (n/p or N/P keys) or by jumping to main branches (j for branch corresponding to function at point, and J to prompt for a function). When you jump to a branch, it is added to `simple-call-tree-jump-ring’, and you can navigate your jump history using the </> keys. You can also add the function under point to the jump-ring with the . key. If you use a negative prefix (e.g. C–) before pressing j then the branch jumped to will not be added to the jump-ring. If you have fm.el (available here: http://www.damtp.cam.ac.uk/user/sje30/emacs/fm.el) you can press f to toggle follow mode on/off.

Display

Normally child branches correspond to functions/variables called by the parent branch. However, if you invert the tree by pressing i then the child branches will correspond to functions that call the parent branch. You can sort the tree in various different ways, and change the depth of the tree. You can also narrow the tree to the function at point by pressing / You can display extra information such as docstrings next to each item in the tree by pressing C-c C-n, and customize the types of information that can be displayed (see simple-call-tree-notes-functions).

Refactoring

You can perform `query-replace’ or `query-replace-regexp’ on the function at point by pressing % or C-%, or any other arbitrary command by pressing ! This may be useful when refactoring.

Exporting

The tree can be exported in its current state with the `simple-call-tree-export-org-tree’ command, and you can alter the TODO state and types of links using options `simple-call-tree-org-todo-state’, and `simple-call-tree-org-link-style’. This may be useful for project management.

Commands & keybindings

Below is a complete list of commands:

• simple-call-tree-mode : The major-mode for the one-key menu buffer.
  Keybinding: M-x simple-call-tree-mode
• simple-call-tree-next-todo : Move to next todo state for current function.
  Keybinding: <S-right>
• simple-call-tree-prev-todo : Move to previous todo state for current function.
  Keybinding: <S-left>
• simple-call-tree-up-priority : Change current function to the next priority level.
  Keybinding: <S-up>
• simple-call-tree-down-priority : Change current function to the previous priority level.
  Keybinding: <S-down>
• simple-call-tree-add-tags : Add tags in VALUE to the function(s) FUNCS.
  Keybinding: C-c C-a
• simple-call-tree-build-tree : Build the simple-call-tree and display it in the ”Simple Call Tree” buffer.
  Keybinding: R
• simple-call-tree-current-function : Display call tree at location for for function at point.
• simple-call-tree-export-org-tree : Create an org-tree from the currently visible items, and put it in an org buffer.
  Keybinding: M-x simple-call-tree-export-org-tree
• simple-call-tree-export-items : Export the currently visible items into a buffer.
  Keybinding: M-x simple-call-tree-export-items
• simple-call-tree-reverse : Reverse the order of the branches & sub-branches in - simple-call-tree-alist : and - simple-call-tree-inverted-alist :.
  Keybinding: r
• simple-call-tree-sort-by-num-descendants : Sort the branches in the Simple Call Tree buffer by the number of descendants to depth DEPTH.
  Keybinding: d
• simple-call-tree-sort-by-name : Sort the functions in the Simple Call Tree buffer alphabetically.
  Keybinding: n
• simple-call-tree-sort-by-position : Sort the functions in the Simple Call Tree buffer by position.
  Keybinding: p
• simple-call-tree-sort-by-face : Sort the items in the Simple Call Tree buffer according to the display face name.
  Keybinding: f
• simple-call-tree-sort-by-todo : Sort the items in the Simple Call Tree buffer by TODO state.
  Keybinding: T
• simple-call-tree-sort-by-priority : Sort the items in the Simple Call Tree buffer by priority level.
  Keybinding: P
• simple-call-tree-sort-by-size : Sort the items in the Simple Call Tree buffer by size.
  Keybinding: s
• simple-call-tree-sort-by-mark : Sort the marked items in the Simple Call Tree buffer before the unmarked ones.
  Keybinding: *
• simple-call-tree-quit : Quit the Simple Call Tree buffer.
  Keybinding: q
• simple-call-tree-invert-buffer : Invert the tree in Simple Call Tree buffer.
  Keybinding: i
• simple-call-tree-change-maxdepth : Alter the maximum tree depth in the Simple Call Tree buffer.
  Keybinding: M-x simple-call-tree-change-maxdepth
• simple-call-tree-change-default-view Change the values of `simple-call-tree-default-view’ and `simple-call-tree-default-recenter’. Keybinding: C-c C-v
• simple-call-tree-view-function : Display the source code corresponding to current header.
  Keybinding: C-o
• simple-call-tree-jump-prev : Jump to the previous function in the - simple-call-tree-jump-ring :.
  Keybinding: <
• simple-call-tree-jump-next : Jump to the next function in the - simple-call-tree-jump-ring :.
  Keybinding: >
• simple-call-tree-jump-ring-add : Add the function at point to the jump-ring.
  Keybinding: .
• simple-call-tree-jump-ring-remove : Remove the current item from the jump-ring.
  Keybinding: -
• simple-call-tree-jump-to-function : Move cursor to the line corresponding to the function header with name FNSTR.
  Keybinding: j
• simple-call-tree-move-top : Move cursor to the parent of this function.
  Keybinding: ^
• simple-call-tree-move-next : Move cursor to the next item.
  Keybinding: M-x simple-call-tree-move-next
• simple-call-tree-move-prev : Move cursor to the previous item.
  Keybinding: M-x simple-call-tree-move-prev
• simple-call-tree-move-next-samelevel : Move cursor to the next item at the same level as the current one, and recenter window.
  Keybinding: C-f
• simple-call-tree-move-prev-samelevel : Move cursor to the previous item at the same level as the current one, and recenter window.
  Keybinding: C-b
• simple-call-tree-move-next-marked : Move cursor to the next marked item.
  Keybinding: M-n
• simple-call-tree-move-prev-marked : Move cursor to the next marked item.
  Keybinding: M-p
• simple-call-tree-toggle-narrowing : Toggle narrowing of Simple Call Tree buffer.
  Keybinding: /
• simple-call-tree-display-notes : Append NOTES to FUNCS in Simple Call Tree buffer. Keybinding: C-c C-n
• simple-call-tree-toggle-duplicates : Toggle the inclusion of duplicate sub-branches in the call tree.
  Keybinding: D
• simple-call-tree-apply-command : Apply command CMD on function(s) FUNCS.
  Keybinding: !
• simple-call-tree-query-replace : Perform query-replace on the marked items or the item at point in the Simple Call Tree buffer.
  Keybinding: %
• simple-call-tree-query-replace-regexp : Perform - query-replace-regexp : on the marked items or the item at point in the Simple Call Tree buffer.
  Keybinding: C-%
• simple-call-tree-bookmark : Set bookmarks the marked items or the item at point in the Simple Call Tree buffer.
  Keybinding: M-x simple-call-tree-bookmark
• simple-call-tree-delete-other-windows : Make the Simple Call Tree buffer fill the frame.
  Keybinding: 1
• simple-call-tree-mark : Mark the item named FUNC.
  Keybinding: m
• simple-call-tree-unmark : Unmark the item named FUNC.
  Keybinding: u
• simple-call-tree-unmark-all : Unmark all items.
  Keybinding: U
• simple-call-tree-toggle-marks : Toggle marks (unmarked become marked and marked become unmarked).
  Keybinding: M-x simple-call-tree-toggle-marks
• simple-call-tree-mark-by-name : Mark all items with names matching regular expression REGEX.
  Keybinding: M-x simple-call-tree-mark-by-name
• simple-call-tree-mark-by-source : Mark all items with source code matching regular expression REGEX.
  Keybinding: M-x simple-call-tree-mark-by-source
• simple-call-tree-mark-by-tag-match : Mark all items with code matching regular expression REGEX.
  Keybinding: t
• simple-call-tree-mark-by-priority : Mark all items with priority VALUE.
  Keybinding: M-x simple-call-tree-mark-by-priority
• simple-call-tree-mark-by-todo : Mark all items with TODO state matching regular expression REGEX.
  Keybinding: M-x simple-call-tree-mark-by-todo
• simple-call-tree-mark-by-face : Mark all items with display face FACE.
  Keybinding: M-x simple-call-tree-mark-by-face
• simple-call-tree-mark-by-buffer : Mark all items corresponding to source code in buffer BUF.
  Keybinding: b
• simple-call-tree-kill-marked : Remove all marked items from the Simple Call Tree buffer.
  Keybinding: k
• simple-call-tree-revert : Redisplay the Simple Call Tree buffer.
  Keybinding: g

Customizable Options

Below is a list of customizable options:

• simple-call-tree-default-recenter : How to recenter the window after moving to another function in the ”Simple Call Tree” buffer.
  default value: (quote middle)
• simple-call-tree-default-view How to recenter the window after viewing a toplevel header.
  default = (quote middle)
• simple-call-tree-window-splits Alist of items containing info about how to split the window when viewing code (e.g. in follow mode).
• simple-call-tree-default-valid-fonts : List of fonts to use for finding objects to include in the call tree.
  default value: (quote (font-lock-function-name-face font-lock-variable-name-face))
• simple-call-tree-default-invalid-fonts : List of fonts that should not be in the text property of any valid token.
  default value: (quote (font-lock-comment-face font-lock-string-face font-lock-doc-face font-lock-keyword-face font-lock-warning-face ...))
• simple-call-tree-default-sort-method : The default sort method to use when a call tree is newly created.
  default value: (quote position)
• simple-call-tree-default-maxdepth : The depth at which new call trees should be displayed.
  default value: 2
• simple-call-tree-major-mode-alist : Alist of major modes, and information to use for identifying objects for the simple call tree.
  default value: (quote ((emacs-lisp-mode ... nil ... nil ...) (cperl-mode nil nil ... nil ...) (haskell-mode nil ... ... ... ...) (perl-mode nil nil ... nil ...) (python-mode ... nil ... nil ...) ...))
• simple-call-tree-org-link-style : Style used for links of child headers when exporting org tree using - simple-call-tree-export-org-tree :.
  default value: (quote radio)
• simple-call-tree-org-todo-keywords : List of different TODO keywords, if nil then the keywords in - org-todo-keywords : will be used.
  default value: nil
• simple-call-tree-org-not-done-keywords : List of TODO keywords representing not done states.
  default value: (quote ("TODO" "STARTED" "WAITING" "CHECK"))
• simple-call-tree-org-highest-priority : See - org-highest-priority :.
  default value: org-highest-priority
• simple-call-tree-org-lowest-priority : See - org-lowest-priority :.
  default value: org-lowest-priority
• simple-call-tree-org-tag-alist : See - org-tag-alist :.
  default value: org-tag-alist
• simple-call-tree-notes-functions : Alist of (DESCRIPTION . NOTES) used for selecting the NOTES arg of ‘simple-call-tree-display-notes’.
• simple-call-tree-mark-face : Face to use for marked items in the Simple Call Tree buffer.
  default value: (if (featurep (quote dired+)) diredp-flag-mark-line (quote highlight))
• simple-call-tree-jump-ring-max : Maximum number of elements in - simple-call-tree-jump-ring :, before old elements are removed.
  default value: 20

Installation

Put simple-call-tree.el in a directory in your load-path, e.g. ~/.emacs.d/ You can add a directory to your load-path with the following line in ~/.emacs (add-to-list ‘load-path (expand-file-name “~/elisp”)) where ~/elisp is the directory you want to add (you don’t need to do this for ~/.emacs.d - it’s added by default).

Add the following to your ~/.emacs startup file.

(require ‘simple-call-tree+)

You might also want to define a key for creating the call tree, e.g. like this:

(global-set-key (kbd “C-c S”) ‘simple-call-tree-current-function)