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