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