Commit | Line | Data |
---|---|---|
4009494e GM |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c documentation for forms-mode | |
3 | @c Written by Johan Vromans, and edited by Richard Stallman | |
4 | ||
5 | @comment %**start of header (This is for running Texinfo on a region.) | |
db78a8cb | 6 | @setfilename ../../info/forms |
4009494e GM |
7 | @settitle Forms Mode User's Manual |
8 | @syncodeindex vr cp | |
9 | @syncodeindex fn cp | |
10 | @syncodeindex ky cp | |
11 | @iftex | |
12 | @finalout | |
13 | @setchapternewpage odd | |
14 | @end iftex | |
15 | @c @smallbook | |
16 | @comment %**end of header (This is for running Texinfo on a region.) | |
17 | ||
18 | @copying | |
19 | This file documents Forms mode, a form-editing major mode for GNU Emacs. | |
20 | ||
21 | Copyright @copyright{} 1989, 1997, 2001, 2002, 2003, 2004, | |
6ed161e1 | 22 | 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. |
4009494e GM |
23 | |
24 | @quotation | |
25 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 26 | under the terms of the GNU Free Documentation License, Version 1.3 or |
4009494e | 27 | any later version published by the Free Software Foundation; with no |
debf4439 GM |
28 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' |
29 | and with the Back-Cover Texts as in (a) below. A copy of the license | |
30 | is included in the section entitled ``GNU Free Documentation License''. | |
4009494e | 31 | |
6f093307 GM |
32 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
33 | modify this GNU manual. Buying copies from the FSF supports it in | |
34 | developing GNU and promoting software freedom.'' | |
4009494e GM |
35 | @end quotation |
36 | @end copying | |
37 | ||
38 | @dircategory Emacs | |
39 | @direntry | |
40 | * Forms: (forms). Emacs package for editing data bases | |
41 | by filling in forms. | |
42 | @end direntry | |
43 | ||
44 | @titlepage | |
45 | @sp 6 | |
46 | @center @titlefont{Forms Mode User's Manual} | |
47 | @sp 4 | |
48 | @center Forms-Mode version 2 | |
49 | @sp 1 | |
50 | @center for GNU Emacs 22.1 | |
51 | @sp 1 | |
52 | @center April 2007 | |
53 | @sp 5 | |
54 | @center Johan Vromans | |
55 | @center @i{jvromans@@squirrel.nl} | |
56 | @page | |
57 | @vskip 0pt plus 1filll | |
58 | @insertcopying | |
59 | @end titlepage | |
60 | ||
61 | @ifnottex | |
62 | @node Top | |
63 | @top Forms Mode | |
64 | ||
65 | Forms mode is an Emacs major mode for working with simple textual data | |
66 | bases in a forms-oriented manner. In Forms mode, the information in | |
67 | these files is presented in an Emacs window in a user-defined format, | |
68 | one record at a time. The user can view records or modify their | |
69 | contents. | |
70 | ||
71 | Forms mode is not a simple major mode, but requires two files to do its | |
72 | job: a control file and a data file. The data file holds the | |
73 | actual data to be presented. The control file describes | |
74 | how to present it. | |
75 | ||
76 | @menu | |
77 | * Forms Example:: An example: editing the password data base. | |
78 | * Entering and Exiting Forms Mode:: | |
79 | How to visit a file in Forms mode. | |
80 | * Forms Commands:: Special commands to use while in Forms mode. | |
81 | * Data File Format:: How to format the data file. | |
82 | * Control File Format:: How to control forms mode. | |
83 | * Format Description:: How to define the forms layout. | |
84 | * Modifying Forms Contents:: How to modify. | |
85 | * Miscellaneous:: Forms mode messages and other remarks. | |
86 | * Error Messages:: List of error messages forms mode can produce. | |
87 | * Long Example:: A more complex control file example. | |
88 | * GNU Free Documentation License:: The license for this documentation. | |
89 | * Credits:: Thanks everyone. | |
90 | * Index:: Index to this manual. | |
91 | @end menu | |
92 | @end ifnottex | |
93 | ||
94 | @node Forms Example | |
95 | @chapter Forms Example | |
96 | ||
97 | Let's illustrate Forms mode with an example. Suppose you are looking at | |
98 | the @file{/etc/passwd} file, and the screen looks like this: | |
99 | ||
100 | @example | |
101 | ====== /etc/passwd ====== | |
102 | ||
103 | User : root Uid: 0 Gid: 1 | |
104 | ||
105 | Name : Super User | |
106 | ||
107 | Home : / | |
108 | ||
109 | Shell: /bin/sh | |
110 | @end example | |
111 | ||
112 | As you can see, the familiar fields from the entry for the super user | |
113 | are all there, but instead of being colon-separated on one single line, | |
114 | they make up a forms. | |
115 | ||
116 | The contents of the forms consist of the contents of the fields of the | |
117 | record (e.g. @samp{root}, @samp{0}, @samp{1}, @samp{Super User}) | |
118 | interspersed with normal text (e.g @samp{User : }, @samp{Uid: }). | |
119 | ||
120 | If you modify the contents of the fields, Forms mode will analyze your | |
121 | changes and update the file appropriately. You cannot modify the | |
122 | interspersed explanatory text (unless you go to some trouble about it), | |
123 | because that is marked read-only (@pxref{Text Properties,,, elisp, The | |
124 | Emacs Lisp Reference Manual}). | |
125 | ||
126 | The Forms mode control file specifies the relationship between the | |
127 | format of @file{/etc/passwd} and what appears on the screen in Forms | |
128 | mode. @xref{Control File Format}. | |
129 | ||
130 | @node Entering and Exiting Forms Mode | |
131 | @chapter Entering and Exiting Forms Mode | |
132 | ||
133 | @table @kbd | |
134 | @findex forms-find-file | |
135 | @item M-x forms-find-file @key{RET} @var{control-file} @key{RET} | |
136 | Visit a database using Forms mode. Specify the name of the | |
137 | @strong{control file}, not the data file! | |
138 | ||
139 | @findex forms-find-file-other-window | |
140 | @item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET} | |
141 | Similar, but displays the file in another window. | |
142 | @end table | |
143 | ||
144 | The command @code{forms-find-file} evaluates the file | |
145 | @var{control-file}, and also visits it in Forms mode. What you see in | |
146 | its buffer is not the contents of this file, but rather a single record | |
147 | of the corresponding data file that is visited in its own buffer. So | |
148 | there are two buffers involved in Forms mode: the @dfn{forms buffer} | |
149 | that is initially used to visit the control file and that shows the | |
150 | records being browsed, and the @dfn{data buffer} that holds the data | |
151 | file being visited. The latter buffer is normally not visible. | |
152 | ||
153 | Initially, the first record is displayed in the forms buffer. | |
154 | The mode line displays the major mode name @samp{Forms}, followed by the | |
155 | minor mode @samp{View} if the data base is read-only. The number of the | |
156 | current record (@var{n}) and the total number of records in the | |
157 | file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}. For | |
158 | example: | |
159 | ||
160 | @example | |
161 | --%%-Emacs: passwd-demo (Forms View 1/54)----All------- | |
162 | @end example | |
163 | ||
164 | If the buffer is not read-only, you may change the buffer to modify the | |
165 | fields in the record. When you move to a different record, the contents | |
166 | of the buffer are parsed using the specifications in | |
167 | @code{forms-format-list}, and the data file is updated. If the record | |
168 | has fields that aren't included in the display, they are not changed. | |
169 | ||
170 | @vindex forms-mode-hooks | |
171 | Entering Forms mode runs the normal hook @code{forms-mode-hooks} to | |
172 | perform user-defined customization. | |
173 | ||
174 | To save any modified data, you can use @kbd{C-x C-s} | |
175 | (@code{forms-save-buffer}). This does not save the forms buffer (which would | |
176 | be rather useless), but instead saves the buffer visiting the data file. | |
177 | ||
178 | To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer}) | |
179 | and then kill the forms buffer. However, the data buffer will still | |
180 | remain. If this is not desired, you have to kill this buffer too. | |
181 | ||
182 | @node Forms Commands | |
183 | @chapter Forms Commands | |
184 | ||
185 | The commands of Forms mode belong to the @kbd{C-c} prefix, with one | |
186 | exception: @key{TAB}, which moves to the next field. Forms mode uses | |
187 | different key maps for normal mode and read-only mode. In read-only | |
188 | Forms mode, you can access most of the commands without the @kbd{C-c} | |
189 | prefix, but you must type ordinary letters instead of control | |
190 | characters; for example, type @kbd{n} instead of @kbd{C-c C-n}. | |
191 | ||
192 | If your Emacs has been built with X-toolkit support, Forms mode will | |
193 | provide its own menu with a number of Forms mode commands. | |
194 | ||
195 | @table @kbd | |
196 | @findex forms-next-record | |
197 | @kindex C-c C-n | |
198 | @item C-c C-n | |
199 | Show the next record (@code{forms-next-record}). With a numeric | |
200 | argument @var{n}, show the @var{n}th next record. | |
201 | ||
202 | @findex forms-prev-record | |
203 | @kindex C-c C-p | |
204 | @item C-c C-p | |
205 | Show the previous record (@code{forms-prev-record}). With a numeric | |
206 | argument @var{n}, show the @var{n}th previous record. | |
207 | ||
208 | @findex forms-jump-record | |
209 | @kindex C-c C-l | |
210 | @item C-c C-l | |
211 | Jump to a record by number (@code{forms-jump-record}). Specify | |
212 | the record number with a numeric argument. | |
213 | ||
214 | @findex forms-first-record | |
215 | @kindex C-c < | |
216 | @item C-c < | |
217 | Jump to the first record (@code{forms-first-record}). | |
218 | ||
219 | @findex forms-last-record | |
220 | @kindex C-c > | |
221 | @item C-c > | |
222 | Jump to the last record (@code{forms-last-record}). This command also | |
223 | recalculates the number of records in the data file. | |
224 | ||
225 | @findex forms-next-field | |
226 | @kindex TAB | |
227 | @item @key{TAB} | |
228 | @kindex C-c TAB | |
229 | @itemx C-c @key{TAB} | |
230 | Jump to the next field in the current record (@code{forms-next-field}). | |
231 | With a numeric argument @var{n}, jump forward @var{n} fields. If this command | |
232 | would move past the last field, it wraps around to the first field. | |
233 | ||
234 | @findex forms-toggle-read-only | |
235 | @kindex C-c C-q | |
236 | @item C-c C-q | |
237 | Toggles read-only mode (@code{forms-toggle-read-only}). In read-only | |
238 | Forms mode, you cannot edit the fields; most Forms mode commands can be | |
239 | accessed without the prefix @kbd{C-c} if you use the normal letter | |
240 | instead (for example, type @kbd{n} instead of @kbd{C-c C-n}). In edit | |
241 | mode, you can edit the fields and thus change the contents of the data | |
242 | base; you must begin Forms mode commands with @code{C-c}. Switching | |
243 | to edit mode is allowed only if you have write access to the data file. | |
244 | ||
245 | @findex forms-insert-record | |
246 | @kindex C-c C-o | |
247 | @item C-c C-o | |
248 | Create a new record and insert it before the current record | |
249 | (@code{forms-insert-record}). It starts out with empty (or default) | |
250 | contents for its fields; you can then edit the fields. With a numeric | |
251 | argument, the new record is created @emph{after} the current one. | |
252 | See also @code{forms-modified-record-filter} in @ref{Modifying Forms | |
253 | Contents}. | |
254 | ||
255 | @findex forms-delete-record | |
256 | @kindex C-c C-k | |
257 | @item C-c C-k | |
258 | Delete the current record (@code{forms-delete-record}). You are | |
259 | prompted for confirmation before the record is deleted unless a numeric | |
260 | argument has been provided. | |
261 | ||
262 | @findex forms-search-forward | |
263 | @kindex C-c C-s @var{regexp} @key{RET} | |
264 | @item C-c C-s @var{regexp} @key{RET} | |
265 | Search forward for @var{regexp} in all records following this one | |
266 | (@code{forms-search-forward}). If found, this record is shown. | |
267 | If you give an empty argument, the previous regexp is used again. | |
268 | ||
269 | @findex forms-search-backward | |
270 | @kindex C-c C-r @var{regexp} @key{RET} | |
271 | @item C-c C-r @var{regexp} @key{RET} | |
272 | Search backward for @var{regexp} in all records following this one | |
273 | (@code{forms-search-backward}). If found, this record is shown. | |
274 | If you give an empty argument, the previous regexp is used again. | |
275 | ||
276 | @ignore | |
277 | @findex forms-exit | |
278 | @kindex C-c C-x | |
279 | @item C-c C-x | |
280 | Terminate Forms mode processing (@code{forms-exit}). The data file is | |
281 | saved if it has been modified. | |
282 | ||
283 | @findex forms-exit-no-save | |
284 | @item M-x forms-exit-no-save | |
285 | Terminates forms mode processing without saving modified data first. | |
286 | @end ignore | |
287 | ||
288 | @findex forms-prev-field | |
289 | @item M-x forms-prev-field | |
290 | Similar to @code{forms-next-field} but moves backwards. | |
291 | ||
292 | @findex forms-save-buffer | |
293 | @item M-x forms-save-buffer | |
294 | @kindex C-x C-s | |
295 | @itemx C-x C-s | |
296 | Forms mode replacement for @code{save-buffer}. When executed in the | |
297 | forms buffer it will save the contents of the (modified) data buffer | |
298 | instead. In Forms mode this function will be bound to @kbd{C-x C-s}. | |
299 | ||
300 | @findex forms-print | |
301 | @item M-x forms-print | |
302 | This command can be used to make a formatted print | |
303 | of the contents of the data file. | |
304 | ||
305 | @end table | |
306 | ||
307 | In addition the command @kbd{M-x revert-buffer} is useful in Forms mode | |
308 | just as in other modes. | |
309 | ||
310 | @ignore | |
311 | @vindex forms-forms-scroll | |
312 | @findex scroll-up | |
313 | @findex scroll-down | |
314 | If the variable @code{forms-forms-scrolls} is set to a value other | |
315 | than @code{nil} (which it is, by default), the Emacs functions | |
316 | @code{scroll-up} and @code{scroll-down} will perform a | |
317 | @code{forms-next-record} and @code{forms-prev-record} when in forms | |
318 | mode. So you can use your favorite page commands to page through the | |
319 | data file. | |
320 | ||
321 | @vindex forms-forms-jump | |
322 | @findex beginning-of-buffer | |
323 | @findex end-of-buffer | |
324 | Likewise, if the variable @code{forms-forms-jump} is not @code{nil} | |
325 | (which it is, by default), Emacs functions @code{beginning-of-buffer} | |
326 | and @code{end-of-buffer} will perform @code{forms-first-record} and | |
327 | @code{forms-last-record} when in forms mode. | |
328 | @end ignore | |
329 | ||
330 | The following function key definitions are set up in Forms mode | |
331 | (whether read-only or not): | |
332 | ||
333 | @table @kbd | |
334 | @kindex next | |
335 | @item next | |
336 | forms-next-record | |
337 | ||
338 | @kindex prior | |
339 | @item prior | |
340 | forms-prev-record | |
341 | ||
342 | @kindex begin | |
343 | @item begin | |
344 | forms-first-record | |
345 | ||
346 | @kindex end | |
347 | @item end | |
348 | forms-last-record | |
349 | ||
350 | @kindex S-Tab | |
351 | @findex forms-prev-field | |
352 | @item S-Tab | |
353 | forms-prev-field | |
354 | @end table | |
355 | ||
356 | @node Data File Format | |
357 | @chapter Data File Format | |
358 | ||
359 | @cindex record | |
360 | @cindex field | |
361 | @vindex forms-field-sep | |
362 | Files for use with Forms mode are very simple---each @dfn{record} | |
363 | (usually one line) forms the contents of one form. Each record consists | |
364 | of a number of @dfn{fields}, which are separated by the value of the | |
365 | string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default. | |
366 | ||
367 | @vindex forms-read-file-filter | |
368 | @vindex forms-write-file-filter | |
369 | If the format of the data file is not suitable enough you can define the | |
370 | filter functions @code{forms-read-file-filter} and | |
371 | @code{forms-write-file-filter}. @code{forms-read-file-filter} is called | |
372 | when the data file is read from disk into the data buffer. It operates | |
373 | on the data buffer, ignoring read-only protections. When the data file | |
374 | is saved to disk @code{forms-write-file-filter} is called to cancel the | |
375 | effects of @code{forms-read-file-filter}. After being saved, | |
376 | @code{forms-read-file-filter} is called again to prepare the data buffer | |
377 | for further processing. | |
378 | ||
379 | @cindex pseudo-newline | |
380 | @vindex forms-multi-line | |
381 | Fields may contain text which shows up in the forms in multiple lines. | |
382 | These lines are separated in the field using a ``pseudo-newline'' | |
383 | character which is defined by the value of the string | |
384 | @code{forms-multi-line}. Its default value is @code{"\^k"} (a Control-K | |
385 | character). If it is | |
386 | set to @code{nil}, multiple line fields are prohibited. | |
387 | ||
388 | If the data file does not exist, it is automatically created. | |
389 | ||
390 | @node Control File Format | |
391 | @chapter Control File Format | |
392 | ||
393 | @cindex control file | |
394 | The Forms mode @dfn{control file} serves two purposes. First, it names | |
395 | the data file to use, and defines its format and properties. Second, | |
396 | the Emacs buffer it occupies is used by Forms mode to display the forms. | |
397 | ||
398 | The contents of the control file are evaluated as a Lisp program. It | |
399 | should set the following Lisp variables to suitable values: | |
400 | ||
401 | @table @code | |
402 | @vindex forms-file | |
403 | @item forms-file | |
404 | This variable specifies the name of the data file. Example: | |
405 | ||
406 | @example | |
407 | (setq forms-file "my/data-file") | |
408 | @end example | |
409 | ||
410 | If the control file doesn't set @code{forms-file}, Forms mode | |
411 | reports an error. | |
412 | ||
413 | @vindex forms-format-list | |
414 | @item forms-format-list | |
415 | This variable describes the way the fields of the record are formatted on | |
416 | the screen. For details, see @ref{Format Description}. | |
417 | ||
418 | @vindex forms-number-of-fields | |
419 | @item forms-number-of-fields | |
420 | This variable holds the number of fields in each record of the data | |
421 | file. Example: | |
422 | ||
423 | @example | |
424 | (setq forms-number-of-fields 10) | |
425 | @end example | |
426 | @end table | |
427 | ||
428 | If the control file does not set @code{forms-format-list} a default | |
429 | format is used. In this situation, Forms mode will deduce the number of | |
430 | fields from the data file providing this file exists and | |
431 | @code{forms-number-of-records} has not been set in the control file. | |
432 | ||
433 | The control file can optionally set the following additional Forms mode | |
434 | variables. Most of them have default values that are good for most | |
435 | applications. | |
436 | ||
437 | @table @code | |
438 | @vindex forms-field-sep | |
439 | @item forms-field-sep | |
440 | This variable may be used to designate the string which separates the | |
441 | fields in the records of the data file. If not set, it defaults to the | |
442 | string @code{"\t"} (a Tab character). Example: | |
443 | ||
444 | @example | |
445 | (setq forms-field-sep "\t") | |
446 | @end example | |
447 | ||
448 | @vindex forms-read-only | |
449 | @item forms-read-only | |
450 | If the value is non-@code{nil}, the data file is treated read-only. (Forms | |
451 | mode also treats the data file as read-only if you don't have access to | |
452 | write it.) Example: | |
453 | ||
454 | @example | |
455 | (set forms-read-only t) | |
456 | @end example | |
457 | ||
458 | @vindex forms-multi-line | |
459 | @item forms-multi-line | |
460 | This variable specifies the @dfn{pseudo newline} separator that allows | |
461 | multi-line fields. This separator goes between the ``lines'' within a | |
462 | field---thus, the field doesn't really contain multiple lines, but it | |
463 | appears that way when displayed in Forms mode. If the value is | |
464 | @code{nil}, multi-line text fields are prohibited. The pseudo newline | |
465 | must not be a character contained in @code{forms-field-sep}. | |
466 | ||
467 | The default value is @code{"\^k"}, the character Control-K. Example: | |
468 | ||
469 | @example | |
470 | (setq forms-multi-line "\^k") | |
471 | @end example | |
472 | ||
473 | @ignore | |
474 | @vindex forms-forms-scroll | |
475 | @item forms-forms-scroll | |
476 | @xref{Forms Mode Commands}, for details. | |
477 | ||
478 | @vindex forms-forms-jump | |
479 | @item forms-forms-jump | |
480 | @xref{Forms Mode Commands}, for details. | |
481 | @end ignore | |
482 | ||
483 | @findex forms-read-file-filter | |
484 | @item forms-read-file-filter | |
485 | This variable holds the name of a function to be called after the data | |
486 | file has been read in. This can be used to transform the contents of the | |
487 | data file into a format more suitable for forms processing. | |
488 | If it is @code{nil}, no function is called. For example, to maintain a | |
489 | gzipped database: | |
490 | ||
491 | @example | |
492 | (defun gzip-read-file-filter () | |
493 | (shell-command-on-region (point-min) (point-max) | |
494 | "gzip -d" t t)) | |
495 | (setq forms-read-file-filter 'gzip-read-file-filter) | |
496 | @end example | |
497 | ||
498 | @findex forms-write-file-filter | |
499 | @item forms-write-file-filter | |
500 | This variable holds the name of a function to be called before writing | |
501 | out the contents of the data file. | |
502 | This can be used to undo the effects of @code{forms-read-file-filter}. | |
503 | If it is @code{nil}, no function is called. Example: | |
504 | ||
505 | @example | |
506 | (defun gzip-write-file-filter () | |
507 | (make-variable-buffer-local 'require-final-newline) | |
508 | (setq require-final-newline nil) | |
509 | (shell-command-on-region (point-min) (point-max) | |
510 | "gzip" t t)) | |
511 | (setq forms-write-file-filter 'gzip-write-file-filter) | |
512 | @end example | |
513 | ||
514 | @findex forms-new-record-filter | |
515 | @item forms-new-record-filter | |
516 | This variable holds a function to be called whenever a new record is created | |
517 | to supply default values for fields. If it is @code{nil}, no function is | |
518 | called. | |
519 | @xref{Modifying Forms Contents}, for details. | |
520 | ||
521 | @findex forms-modified-record-filter | |
522 | @item forms-modified-record-filter | |
523 | This variable holds a function to be called whenever a record is | |
524 | modified, just before updating the Forms data file. If it is | |
525 | @code{nil}, no function is called. | |
526 | @xref{Modifying Forms Contents}, for details. | |
527 | ||
528 | @findex forms-insert-after | |
529 | @item forms-insert-after | |
530 | If this variable is not @code{nil}, new records are created @emph{after} the | |
531 | current record. Also, upon visiting a file, the initial position will be | |
532 | at the last record instead of the first one. | |
533 | ||
534 | @findex forms-check-number-of-fields | |
535 | @item forms-check-number-of-fields | |
536 | Normally each record is checked to contain the correct number of fields. | |
537 | Under certain circumstances, this can be undesirable. | |
538 | If this variable is set to @code{nil}, these checks will be bypassed. | |
539 | @end table | |
540 | ||
541 | @node Format Description | |
542 | @chapter The Format Description | |
543 | ||
544 | @vindex forms-format-list | |
545 | The variable @code{forms-format-list} specifies the format of the data | |
546 | in the data file, and how to convert the data for display in Forms mode. | |
547 | Its value must be a list of Forms mode @dfn{formatting elements}, each | |
548 | of which can be a string, a number, a Lisp list, or a Lisp symbol that | |
549 | evaluates to one of those. The formatting elements are processed in the | |
550 | order they appear in the list. | |
551 | ||
552 | @table @var | |
553 | @item string | |
554 | A string formatting element is inserted in the forms ``as is,'' as text | |
555 | that the user cannot alter. | |
556 | ||
557 | @item number | |
558 | A number element selects a field of the record. The contents of this | |
559 | field are inserted in the display at this point. Field numbers count | |
560 | starting from 1 (one). | |
561 | ||
562 | @item list | |
563 | A formatting element that is a list specifies a function call. This | |
564 | function is called every time a record is displayed, and its result, | |
565 | which must be a string, is inserted in the display text. The function | |
566 | should do nothing but returning a string. | |
567 | ||
568 | @vindex forms-fields | |
569 | The function you call can access the fields of the record as a list in | |
570 | the variable | |
571 | @code{forms-fields}. | |
572 | ||
573 | @item symbol | |
574 | A symbol used as a formatting element should evaluate to a string, number, | |
575 | or list; the value is interpreted as a formatting element, as described | |
576 | above. | |
577 | @end table | |
578 | ||
579 | If a record does not contain the number of fields as specified in | |
580 | @code{forms-number-of-fields}, a warning message will be printed. Excess | |
581 | fields are ignored, missing fields are set to empty. | |
582 | ||
583 | The control file which displays @file{/etc/passwd} file as demonstrated | |
584 | in the beginning of this manual might look as follows: | |
585 | ||
586 | @example | |
587 | ;; @r{This demo visits @file{/etc/passwd}.} | |
588 | ||
589 | (setq forms-file "/etc/passwd") | |
590 | (setq forms-number-of-fields 7) | |
591 | (setq forms-read-only t) ; @r{to make sure} | |
592 | (setq forms-field-sep ":") | |
593 | ;; @r{Don't allow multi-line fields.} | |
594 | (setq forms-multi-line nil) | |
595 | ||
596 | (setq forms-format-list | |
597 | (list | |
598 | "====== /etc/passwd ======\n\n" | |
599 | "User : " 1 | |
600 | " Uid: " 3 | |
601 | " Gid: " 4 | |
602 | "\n\n" | |
603 | "Name : " 5 | |
604 | "\n\n" | |
605 | "Home : " 6 | |
606 | "\n\n" | |
607 | "Shell: " 7 | |
608 | "\n")) | |
609 | @end example | |
610 | ||
611 | When you construct the value of @code{forms-format-list}, you should | |
612 | usually either quote the whole value, like this, | |
613 | ||
614 | @example | |
615 | (setq forms-format-list | |
616 | '( | |
617 | "====== " forms-file " ======\n\n" | |
618 | "User : " 1 | |
619 | (make-string 20 ?-) | |
620 | @dots{} | |
621 | )) | |
622 | @end example | |
623 | ||
624 | @noindent | |
625 | or quote the elements which are lists, like this: | |
626 | ||
627 | @example | |
628 | (setq forms-format-list | |
629 | (list | |
630 | "====== " forms-file " ======\n\n" | |
631 | "User : " 1 | |
632 | '(make-string 20 ?-) | |
633 | @dots{} | |
634 | )) | |
635 | @end example | |
636 | ||
637 | Forms mode validates the contents of @code{forms-format-list} when you | |
638 | visit a database. If there are errors, processing is aborted with an | |
639 | error message which includes a descriptive text. @xref{Error Messages}, | |
640 | for a detailed list of error messages. | |
641 | ||
642 | If no @code{forms-format-list} is specified, Forms mode will supply a | |
643 | default format list. This list contains the name of the file being | |
644 | visited, and a simple label for each field indicating the field number. | |
645 | ||
646 | @node Modifying Forms Contents | |
647 | @chapter Modifying The Forms Contents | |
648 | ||
649 | If @code{forms-read-only} is @code{nil}, the user can modify the fields | |
650 | and records of the database. | |
651 | ||
652 | All normal editing commands are available for editing the contents of the | |
653 | displayed record. You cannot delete or modify the fixed, explanatory | |
654 | text that comes from string formatting elements, but you can modify the | |
655 | actual field contents. | |
656 | ||
657 | @ignore | |
658 | @c This is for the Emacs 18 version only. | |
659 | If the contents of the forms cannot be recognized properly, this is | |
660 | signaled using a descriptive text. @xref{Error Messages}, for more info. | |
661 | The cursor will indicate the last part of the forms which was | |
662 | successfully parsed. It's important to avoid entering field contents | |
663 | that would cause confusion with the field-separating fixed text. | |
664 | @end ignore | |
665 | ||
666 | If the variable @code{forms-modified-record-filter} is non-@code{nil}, | |
667 | it is called as a function before the new data is written to the data | |
668 | file. The function receives one argument, a vector that contains the | |
669 | contents of the fields of the record. | |
670 | ||
671 | The function can refer to fields with @code{aref} and modify them with | |
672 | @code{aset}. The first field has number 1 (one); thus, element 0 of the | |
673 | vector is not used. The function should return the same vector it was | |
674 | passed; the (possibly modified) contents of the vector determine what is | |
675 | actually written in the file. Here is an example: | |
676 | ||
677 | @example | |
678 | (defun my-modified-record-filter (record) | |
679 | ;; @r{Modify second field.} | |
680 | (aset record 2 (current-time-string)) | |
681 | ;; @r{Return the field vector.} | |
682 | record) | |
683 | ||
684 | (setq forms-modified-record-filter 'my-modified-record-filter) | |
685 | @end example | |
686 | ||
687 | If the variable @code{forms-new-record-filter} is non-@code{nil}, its | |
688 | value is a function to be called to fill in default values for the | |
689 | fields of a new record. The function is passed a vector of empty | |
690 | strings, one for each field; it should return the same vector, with | |
691 | the desired field values stored in it. Fields are numbered starting | |
692 | from 1 (one). Example: | |
693 | ||
694 | @example | |
695 | (defun my-new-record-filter (fields) | |
696 | (aset fields 5 (login-name)) | |
697 | (aset fields 1 (current-time-string)) | |
698 | fields) | |
699 | ||
700 | (setq forms-new-record-filter 'my-new-record-filter) | |
701 | @end example | |
702 | ||
703 | @node Miscellaneous | |
704 | @chapter Miscellaneous | |
705 | ||
706 | @vindex forms-version | |
707 | The global variable @code{forms-version} holds the version information | |
708 | of the Forms mode software. | |
709 | ||
710 | @findex forms-enumerate | |
711 | It is very convenient to use symbolic names for the fields in a record. | |
712 | The function @code{forms-enumerate} provides an elegant means to define | |
713 | a series of variables whose values are consecutive integers. The | |
714 | function returns the highest number used, so it can be used to set | |
715 | @code{forms-number-of-fields} also. For example: | |
716 | ||
717 | @example | |
718 | (setq forms-number-of-fields | |
719 | (forms-enumerate | |
720 | '(field1 field2 field3 @dots{}))) | |
721 | @end example | |
722 | ||
723 | This sets @code{field1} to 1, @code{field2} to 2, and so on. | |
724 | ||
725 | Care has been taken to keep the Forms mode variables buffer-local, so it | |
726 | is possible to visit multiple files in Forms mode simultaneously, even | |
727 | if they have different properties. | |
728 | ||
729 | @findex forms-mode | |
730 | If you have visited the control file in normal fashion with | |
731 | @code{find-file} or a like command, you can switch to Forms mode with | |
732 | the command @code{M-x forms-mode}. If you put @samp{-*- forms -*-} in | |
733 | the first line of the control file, then visiting it enables Forms mode | |
734 | automatically. But this makes it hard to edit the control file itself, | |
735 | so you'd better think twice before using this. | |
736 | ||
737 | The default format for the data file, using @code{"\t"} to separate | |
738 | fields and @code{"\^k"} to separate lines within a field, matches the | |
739 | file format of some popular database programs, e.g. FileMaker. So | |
740 | @code{forms-mode} can decrease the need to use proprietary software. | |
741 | ||
742 | @node Error Messages | |
743 | @chapter Error Messages | |
744 | ||
745 | This section describes all error messages which can be generated by | |
746 | forms mode. Error messages that result from parsing the control file | |
747 | all start with the text @samp{Forms control file error}. Messages | |
748 | generated while analyzing the definition of @code{forms-format-list} | |
749 | start with @samp{Forms format error}. | |
750 | ||
751 | @table @code | |
752 | @item Forms control file error: `forms-file' has not been set | |
753 | The variable @code{forms-file} was not set by the control file. | |
754 | ||
755 | @item Forms control file error: `forms-number-of-fields' has not been set | |
756 | The variable @code{forms-number-of-fields} was not set by the control | |
757 | file. | |
758 | ||
759 | @item Forms control file error: `forms-number-of-fields' must be a number > 0 | |
760 | The variable @code{forms-number-of-fields} did not contain a positive | |
761 | number. | |
762 | ||
763 | @item Forms control file error: `forms-field-sep' is not a string | |
764 | @itemx Forms control file error: `forms-multi-line' must be nil or a one-character string | |
765 | The variable @code{forms-multi-line} was set to something other than | |
766 | @code{nil} or a single-character string. | |
767 | ||
768 | @item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep' | |
769 | The variable @code{forms-multi-line} may not be equal to | |
770 | @code{forms-field-sep} for this would make it impossible to distinguish | |
771 | fields and the lines in the fields. | |
772 | ||
773 | @item Forms control file error: `forms-new-record-filter' is not a function | |
774 | @itemx Forms control file error: `forms-modified-record-filter' is not a function | |
775 | The variable has been set to something else than a function. | |
776 | ||
777 | @item Forms control file error: `forms-format-list' is not a list | |
778 | The variable @code{forms-format-list} was not set to a Lisp list | |
779 | by the control file. | |
780 | ||
781 | @item Forms format error: field number @var{xx} out of range 1..@var{nn} | |
782 | A field number was supplied in @code{forms-format-list} with a value of | |
783 | @var{xx}, which was not greater than zero and smaller than or equal to | |
784 | the number of fields in the forms, @var{nn}. | |
785 | ||
786 | @item Forms format error: @var{fun} is not a function | |
787 | The first element of a list which is an element of | |
788 | @code{forms-format-list} was not a valid Lisp function. | |
789 | ||
790 | @item Forms format error: invalid element @var{xx} | |
791 | A list element was supplied in @code{forms-format-list} which was not a | |
792 | string, number or list. | |
793 | ||
794 | @ignore | |
795 | @c This applies to Emacs 18 only. | |
796 | @c Error messages generated while a modified form is being analyzed. | |
797 | ||
798 | @item Parse error: not looking at `...' | |
799 | When re-parsing the contents of a forms, the text shown could not | |
800 | be found. | |
801 | ||
802 | @item Parse error: cannot find `...' | |
803 | When re-parsing the contents of a forms, the text shown, which | |
804 | separates two fields, could not be found. | |
805 | ||
806 | @item Parse error: cannot parse adjacent fields @var{xx} and @var{yy} | |
807 | Fields @var{xx} and @var{yy} were not separated by text, so could not be | |
808 | parsed again. | |
809 | @end ignore | |
810 | ||
811 | @item Warning: this record has @var{xx} fields instead of @var{yy} | |
812 | The number of fields in this record in the data file did not match | |
813 | @code{forms-number-of-fields}. Missing fields will be made empty. | |
814 | ||
815 | @item Multi-line fields in this record - update refused! | |
816 | The current record contains newline characters, hence can not be written | |
817 | back to the data file, for it would corrupt it. Probably you inserted a | |
818 | newline in a field, while @code{forms-multi-line} was @code{nil}. | |
819 | ||
820 | @item Field separator occurs in record - update refused! | |
821 | The current record contains the field separator string inside one of the | |
822 | fields. It can not be written back to the data file, for it would | |
823 | corrupt it. Probably you inserted the field separator string in a field. | |
824 | ||
825 | @item Record number @var{xx} out of range 1..@var{yy} | |
826 | A jump was made to non-existing record @var{xx}. @var{yy} denotes the | |
827 | number of records in the file. | |
828 | ||
829 | @item Stuck at record @var{xx} | |
830 | An internal error prevented a specific record from being retrieved. | |
831 | ||
832 | @item No write access to @code{"}@var{file}@code{"} | |
833 | An attempt was made to enable edit mode on a file that has been write | |
834 | protected. | |
835 | ||
836 | @item Search failed: @var{regexp} | |
837 | The @var{regexp} could not be found in the data file. Forward searching | |
838 | is done from the current location until the end of the file, then | |
839 | retrying from the beginning of the file until the current location. | |
840 | Backward searching is done from the current location until the beginning | |
841 | of the file, then retrying from the end of the file until the current | |
842 | location. | |
843 | ||
844 | @item Wrapped | |
845 | A search completed successfully after wrapping around. | |
846 | ||
847 | @item Warning: number of records changed to @var{nn} | |
848 | Forms mode's idea of the number of records has been adjusted to the | |
849 | number of records actually present in the data file. | |
850 | ||
851 | @item Problem saving buffers? | |
852 | An error occurred while saving the data file buffer. Most likely, Emacs | |
853 | did ask to confirm deleting the buffer because it had been modified, and | |
854 | you said `no'. | |
855 | @end table | |
856 | ||
857 | @node Long Example | |
858 | @chapter Long Example | |
859 | ||
860 | The following example exploits most of the features of Forms mode. | |
861 | This example is included in the distribution as file @file{forms-d2.el}. | |
862 | ||
863 | @example | |
864 | ;; demo2 -- demo forms-mode -*- emacs-lisp -*- | |
865 | ||
866 | ;; @r{This sample forms exploit most of the features of forms mode.} | |
867 | ||
868 | ;; @r{Set the name of the data file.} | |
869 | (setq forms-file "forms-d2.dat") | |
870 | ||
871 | ;; @r{Use @code{forms-enumerate} to set field names and number thereof.} | |
872 | (setq forms-number-of-fields | |
873 | (forms-enumerate | |
874 | '(arch-newsgroup ; 1 | |
875 | arch-volume ; 2 | |
876 | arch-issue ; and ... | |
877 | arch-article ; ... so | |
878 | arch-shortname ; ... ... on | |
879 | arch-parts | |
880 | arch-from | |
881 | arch-longname | |
882 | arch-keywords | |
883 | arch-date | |
884 | arch-remarks))) | |
885 | ||
886 | ;; @r{The following functions are used by this form for layout purposes.} | |
887 | ;; | |
888 | (defun arch-tocol (target &optional fill) | |
889 | "Produces a string to skip to column TARGET. | |
890 | Prepends newline if needed. | |
891 | The optional FILL should be a character, used to fill to the column." | |
892 | (if (null fill) | |
893 | (setq fill ? )) | |
894 | (if (< target (current-column)) | |
895 | (concat "\n" (make-string target fill)) | |
896 | (make-string (- target (current-column)) fill))) | |
897 | ;; | |
898 | (defun arch-rj (target field &optional fill) | |
899 | "Produces a string to skip to column TARGET\ | |
900 | minus the width of field FIELD. | |
901 | Prepends newline if needed. | |
902 | The optional FILL should be a character, | |
903 | used to fill to the column." | |
904 | (arch-tocol (- target (length (nth field forms-fields))) fill)) | |
905 | ||
906 | ;; @r{Record filters.} | |
907 | ;; | |
908 | (defun new-record-filter (the-record) | |
909 | "Form a new record with some defaults." | |
910 | (aset the-record arch-from (user-full-name)) | |
911 | (aset the-record arch-date (current-time-string)) | |
912 | the-record) ; return it | |
913 | (setq forms-new-record-filter 'new-record-filter) | |
914 | ||
915 | ;; @r{The format list.} | |
916 | (setq forms-format-list | |
917 | (list | |
918 | "====== Public Domain Software Archive ======\n\n" | |
919 | arch-shortname | |
920 | " - " arch-longname | |
921 | "\n\n" | |
922 | "Article: " arch-newsgroup | |
923 | "/" arch-article | |
924 | " " | |
925 | '(arch-tocol 40) | |
926 | "Issue: " arch-issue | |
927 | " " | |
928 | '(arch-rj 73 10) | |
929 | "Date: " arch-date | |
930 | "\n\n" | |
931 | "Submitted by: " arch-from | |
932 | "\n" | |
933 | '(arch-tocol 79 ?-) | |
934 | "\n" | |
935 | "Keywords: " arch-keywords | |
936 | "\n\n" | |
937 | "Parts: " arch-parts | |
938 | "\n\n====== Remarks ======\n\n" | |
939 | arch-remarks | |
940 | )) | |
941 | ||
942 | ;; @r{That's all, folks!} | |
943 | @end example | |
944 | ||
945 | @node Credits | |
946 | @chapter Credits | |
947 | ||
948 | Bug fixes and other useful suggestions were supplied by | |
949 | Harald Hanche-Olsen (@code{hanche@@imf.unit.no}), | |
950 | @code{cwitty@@portia.stanford.edu}, | |
951 | Jonathan I. Kamens, | |
952 | Per Cederqvist (@code{ceder@@signum.se}), | |
953 | Michael Lipka (@code{lipka@@lip.hanse.de}), | |
954 | Andy Piper (@code{ajp@@eng.cam.ac.uk}), | |
955 | Frederic Pierresteguy (@code{F.Pierresteguy@@frcl.bull.fr}), | |
956 | Ignatios Souvatzis | |
957 | and Richard Stallman (@code{rms@@gnu.org}). | |
958 | ||
959 | This documentation was slightly inspired by the documentation of ``rolo | |
960 | mode'' by Paul Davis at Schlumberger Cambridge Research | |
961 | (@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}). | |
962 | ||
963 | None of this would have been possible without GNU Emacs of the Free | |
964 | Software Foundation. Thanks, Richard! | |
965 | ||
966 | @node GNU Free Documentation License | |
967 | @appendix GNU Free Documentation License | |
968 | @include doclicense.texi | |
969 | ||
970 | @node Index | |
971 | @unnumbered Index | |
972 | @printindex cp | |
973 | ||
974 | @contents | |
975 | @bye | |
976 | ||
977 | @ignore | |
978 | arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed | |
979 | @end ignore |