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