Commit | Line | Data |
---|---|---|
26d654ec | 1 | ;;; hideshow.el --- minor mode cmds to selectively display code/comment blocks |
6da7653c | 2 | |
034babe1 | 3 | ;; Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 |
114f9c96 | 4 | ;; 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. |
b578f267 | 5 | |
9b4a7800 | 6 | ;; Author: Thien-Thi Nguyen <ttn@gnu.org> |
26a0b399 | 7 | ;; Dan Nicolaescu <dann@ics.uci.edu> |
b7c09257 | 8 | ;; Keywords: C C++ java lisp tools editing comments blocks hiding outlines |
a5b101dc | 9 | ;; Maintainer-Version: 5.65.2.2 |
b578f267 EN |
10 | ;; Time-of-Day-Author-Most-Likely-to-be-Recalcitrant: early morning |
11 | ||
12 | ;; This file is part of GNU Emacs. | |
13 | ||
b1fc2b50 | 14 | ;; GNU Emacs is free software: you can redistribute it and/or modify |
b578f267 | 15 | ;; it under the terms of the GNU General Public License as published by |
b1fc2b50 GM |
16 | ;; the Free Software Foundation, either version 3 of the License, or |
17 | ;; (at your option) any later version. | |
b578f267 EN |
18 | |
19 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
20 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
22 | ;; GNU General Public License for more details. | |
23 | ||
24 | ;; You should have received a copy of the GNU General Public License | |
b1fc2b50 | 25 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
b578f267 | 26 | |
6da7653c TTN |
27 | ;;; Commentary: |
28 | ||
26a0b399 | 29 | ;; * Commands provided |
aaa114d0 | 30 | ;; |
a23c5037 | 31 | ;; This file provides Hideshow Minor Mode. When active, nine commands |
1a8e83dc | 32 | ;; are available, implementing block hiding and showing. They (and their |
26a0b399 | 33 | ;; keybindings) are: |
aaa114d0 | 34 | ;; |
60470e65 TTN |
35 | ;; hs-hide-block C-c @ C-h |
36 | ;; hs-show-block C-c @ C-s | |
37 | ;; hs-hide-all C-c @ C-M-h | |
38 | ;; hs-show-all C-c @ C-M-s | |
39 | ;; hs-hide-level C-c @ C-l | |
40 | ;; hs-toggle-hiding C-c @ C-c | |
26d654ec | 41 | ;; hs-mouse-toggle-hiding [(shift mouse-2)] |
26a0b399 | 42 | ;; hs-hide-initial-comment-block |
b578f267 | 43 | ;; |
26a0b399 TTN |
44 | ;; Blocks are defined per mode. In c-mode, c++-mode and java-mode, they |
45 | ;; are simply text between curly braces, while in Lisp-ish modes parens | |
46 | ;; are used. Multi-line comment blocks can also be hidden. Read-only | |
47 | ;; buffers are not a problem, since hideshow doesn't modify the text. | |
48 | ;; | |
49 | ;; The command `M-x hs-minor-mode' toggles the minor mode or sets it | |
50 | ;; (similar to other minor modes). | |
b578f267 | 51 | |
26d654ec TTN |
52 | ;; * Suggested usage |
53 | ;; | |
54 | ;; First make sure hideshow.el is in a directory in your `load-path'. | |
55 | ;; You can optionally byte-compile it using `M-x byte-compile-file'. | |
56 | ;; Then, add the following to your ~/.emacs: | |
57 | ;; | |
58 | ;; (load-library "hideshow") | |
59 | ;; (add-hook 'X-mode-hook ; other modes similarly | |
aa7d6700 | 60 | ;; (lambda () (hs-minor-mode 1))) |
26d654ec TTN |
61 | ;; |
62 | ;; where X = {emacs-lisp,c,c++,perl,...}. You can also manually toggle | |
63 | ;; hideshow minor mode by typing `M-x hs-minor-mode'. After hideshow is | |
64 | ;; activated or deactivated, `hs-minor-mode-hook' is run w/ `run-hooks'. | |
65 | ;; | |
66 | ;; Additionally, Joseph Eydelnant writes: | |
67 | ;; I enjoy your package hideshow.el Ver. 5.24 2001/02/13 | |
68 | ;; a lot and I've been looking for the following functionality: | |
69 | ;; toggle hide/show all with a single key. | |
70 | ;; Here are a few lines of code that lets me do just that. | |
71 | ;; | |
72 | ;; (defvar my-hs-hide nil "Current state of hideshow for toggling all.") | |
73 | ;; ;;;###autoload | |
74 | ;; (defun my-toggle-hideshow-all () "Toggle hideshow all." | |
75 | ;; (interactive) | |
76 | ;; (setq my-hs-hide (not my-hs-hide)) | |
77 | ;; (if my-hs-hide | |
78 | ;; (hs-hide-all) | |
79 | ;; (hs-show-all))) | |
80 | ;; | |
81 | ;; [Your hideshow hacks here!] | |
82 | ||
26a0b399 TTN |
83 | ;; * Customization |
84 | ;; | |
85 | ;; You can use `M-x customize-variable' on the following variables: | |
86 | ;; | |
9b4a7800 TTN |
87 | ;; - hs-hide-comments-when-hiding-all -- self-explanatory! |
88 | ;; - hs-hide-all-non-comment-function -- if non-nil, when doing a | |
89 | ;; `hs-hide-all', this function | |
90 | ;; is called w/ no arguments | |
91 | ;; - hs-isearch-open -- what kind of hidden blocks to | |
26a0b399 TTN |
92 | ;; open when doing isearch |
93 | ;; | |
9b4a7800 TTN |
94 | ;; Some languages (e.g., Java) are deeply nested, so the normal behavior |
95 | ;; of `hs-hide-all' (hiding all but top-level blocks) results in very | |
96 | ;; little information shown, which is not very useful. You can use the | |
97 | ;; variable `hs-hide-all-non-comment-function' to implement your idea of | |
98 | ;; what is more useful. For example, the following code shows the next | |
99 | ;; nested level in addition to the top-level: | |
100 | ;; | |
101 | ;; (defun ttn-hs-hide-level-1 () | |
102 | ;; (hs-hide-level 1) | |
103 | ;; (forward-sexp 1)) | |
104 | ;; (setq hs-hide-all-non-comment-function 'ttn-hs-hide-level-1) | |
105 | ;; | |
26a0b399 TTN |
106 | ;; Hideshow works w/ incremental search (isearch) by setting the variable |
107 | ;; `hs-headline', which is the line of text at the beginning of a hidden | |
108 | ;; block that contains a match for the search. You can have this show up | |
109 | ;; in the mode line by modifying the variable `mode-line-format'. For | |
110 | ;; example, the following code prepends this info to the mode line: | |
aaa114d0 | 111 | ;; |
26a0b399 TTN |
112 | ;; (unless (memq 'hs-headline mode-line-format) |
113 | ;; (setq mode-line-format | |
114 | ;; (append '("-" hs-headline) mode-line-format))) | |
aaa114d0 | 115 | ;; |
26a0b399 | 116 | ;; See documentation for `mode-line-format' for more info. |
aaa114d0 TTN |
117 | ;; |
118 | ;; Hooks are run after some commands: | |
119 | ;; | |
120 | ;; hs-hide-hook in hs-hide-block, hs-hide-all, hs-hide-level | |
9b4a7800 | 121 | ;; hs-show-hook hs-show-block, hs-show-all |
aaa114d0 | 122 | ;; |
9b4a7800 TTN |
123 | ;; One of `hs-hide-hook' or `hs-show-hook' is run for the toggling |
124 | ;; commands when the result of the toggle is to hide or show blocks, | |
125 | ;; respectively. All hooks are run w/ `run-hooks'. See docs for each | |
126 | ;; variable or hook for more info. | |
26a0b399 TTN |
127 | ;; |
128 | ;; Normally, hideshow tries to determine appropriate values for block | |
129 | ;; and comment definitions by examining the buffer's major mode. If | |
130 | ;; there are problems, hideshow will not activate and in that case you | |
131 | ;; may wish to override hideshow's heuristics by adding an entry to | |
132 | ;; variable `hs-special-modes-alist'. Packages that use hideshow should | |
133 | ;; do something like: | |
134 | ;; | |
aa7d6700 | 135 | ;; (add-to-list 'hs-special-modes-alist '(my-mode "{{" "}}" ...)) |
26a0b399 TTN |
136 | ;; |
137 | ;; If you have an entry that works particularly well, consider | |
138 | ;; submitting it for inclusion in hideshow.el. See docstring for | |
139 | ;; `hs-special-modes-alist' for more info on the entry format. | |
dfdc1af2 TTN |
140 | ;; |
141 | ;; See also variable `hs-set-up-overlay' for per-block customization of | |
142 | ;; appearance or other effects associated with overlays. For example: | |
143 | ;; | |
144 | ;; (setq hs-set-up-overlay | |
145 | ;; (defun my-display-code-line-counts (ov) | |
146 | ;; (when (eq 'code (overlay-get ov 'hs)) | |
147 | ;; (overlay-put ov 'display | |
148 | ;; (propertize | |
149 | ;; (format " ... <%d>" | |
150 | ;; (count-lines (overlay-start ov) | |
151 | ;; (overlay-end ov))) | |
152 | ;; 'face 'font-lock-type-face))))) | |
b578f267 | 153 | |
26a0b399 TTN |
154 | ;; * Bugs |
155 | ;; | |
156 | ;; (1) Hideshow does not work w/ emacs 18 because emacs 18 lacks the | |
157 | ;; function `forward-comment' (among other things). If someone | |
158 | ;; writes this, please send me a copy. | |
159 | ;; | |
160 | ;; (2) Sometimes `hs-headline' can become out of sync. To reset, type | |
26d654ec | 161 | ;; `M-x hs-minor-mode' twice (that is, deactivate then re-activate |
26a0b399 | 162 | ;; hideshow). |
aaa114d0 | 163 | ;; |
26d654ec | 164 | ;; (3) Hideshow 5.x is developed and tested on GNU Emacs 20.7. |
26a0b399 | 165 | ;; XEmacs compatibility may have bitrotted since 4.29. |
aaa114d0 | 166 | ;; |
9b4a7800 TTN |
167 | ;; (4) Some buffers can't be `byte-compile-file'd properly. This is because |
168 | ;; `byte-compile-file' inserts the file to be compiled in a temporary | |
169 | ;; buffer and switches `normal-mode' on. In the case where you have | |
170 | ;; `hs-hide-initial-comment-block' in `hs-minor-mode-hook', the hiding of | |
171 | ;; the initial comment sometimes hides parts of the first statement (seems | |
172 | ;; to be only in `normal-mode'), so there are unbalanced "(" and ")". | |
173 | ;; | |
174 | ;; The workaround is to clear `hs-minor-mode-hook' when byte-compiling: | |
175 | ;; | |
176 | ;; (defadvice byte-compile-file (around | |
177 | ;; byte-compile-file-hideshow-off | |
178 | ;; act) | |
179 | ;; (let ((hs-minor-mode-hook nil)) | |
180 | ;; ad-do-it)) | |
26d654ec TTN |
181 | ;; |
182 | ;; (5) Hideshow interacts badly with Ediff and `vc-diff'. At the moment, the | |
183 | ;; suggested workaround is to turn off hideshow entirely, for example: | |
184 | ;; | |
26d654ec TTN |
185 | ;; (add-hook 'ediff-prepare-buffer-hook 'turn-off-hideshow) |
186 | ;; (add-hook 'vc-before-checkin-hook 'turn-off-hideshow) | |
187 | ;; | |
188 | ;; In the case of `vc-diff', here is a less invasive workaround: | |
189 | ;; | |
190 | ;; (add-hook 'vc-before-checkin-hook | |
aa7d6700 TTN |
191 | ;; (lambda () |
192 | ;; (goto-char (point-min)) | |
193 | ;; (hs-show-block))) | |
26d654ec TTN |
194 | ;; |
195 | ;; Unfortunately, these workarounds do not restore hideshow state. | |
196 | ;; If someone figures out a better way, please let me know. | |
9b4a7800 | 197 | |
26d654ec TTN |
198 | ;; * Correspondance |
199 | ;; | |
26a0b399 | 200 | ;; Correspondance welcome; please indicate version number. Send bug |
9b4a7800 | 201 | ;; reports and inquiries to <ttn@gnu.org>. |
b578f267 | 202 | |
26a0b399 | 203 | ;; * Thanks |
aaa114d0 | 204 | ;; |
26a0b399 TTN |
205 | ;; Thanks go to the following people for valuable ideas, code and |
206 | ;; bug reports. | |
aaa114d0 | 207 | ;; |
2bbf1842 TTN |
208 | ;; Dean Andrews, Alf-Ivar Holm, Holger Bauer, Christoph Conrad, Dave Love, |
209 | ;; Dirk Herrmann, Gael Marziou, Jan Djarv, Guillaume Leray, Moody Ahmad, | |
210 | ;; Preston F. Crow, Lars Lindberg, Reto Zimmermann, Keith Sheffield, | |
211 |