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