Next: Modifying Forms Contents, Previous: Control File Format, Up: Top [Contents][Index]

## 6 The Format Description

The variable `forms-format-list` specifies the format of the data in the data file, and how to convert the data for display in Forms mode. Its value must be a list of Forms mode formatting elements, each of which can be a string, a number, a Lisp list, or a Lisp symbol that evaluates to one of those. The formatting elements are processed in the order they appear in the list.

string

  A string formatting element is inserted in the forms “as is,” as text that the user cannot alter.

number

  A number element selects a field of the record. The contents of this field are inserted in the display at this point. Field numbers count starting from 1 (one).

list

  A formatting element that is a list specifies a function call. This function is called every time a record is displayed, and its result, which must be a string, is inserted in the display text. The function should do nothing but returning a string.

  The function you call can access the fields of the record as a list in the variable `forms-fields`.

symbol

  A symbol used as a formatting element should evaluate to a string, number, or list; the value is interpreted as a formatting element, as described above.

If a record does not contain the number of fields as specified in `forms-number-of-fields`, a warning message will be printed. Excess fields are ignored, missing fields are set to empty.

The control file which displays `/etc/passwd` file as demonstrated in the beginning of this manual might look as follows:

    ;; This demo visits /etc/passwd.

    (setq forms-file "/etc/passwd")
    (setq forms-number-of-fields 7)
    (setq forms-read-only t)                 ; to make sure
    (setq forms-field-sep ":")
    ;; Don’t allow multi-line fields.
    (setq forms-multi-line nil)

    (setq forms-format-list
          (list
           "====== /etc/passwd ======\n\n"
           "User : "    1
           "   Uid: "   3
           "   Gid: "   4
           "\n\n"
           "Name : "    5
           "\n\n"
           "Home : "    6
           "\n\n"
           "Shell: "    7
           "\n"))

When you construct the value of `forms-format-list`, you should usually either quote the whole value, like this,

    (setq forms-format-list
         '(
           "====== " forms-file " ======\n\n"
           "User : "    1
           (make-string 20 ?-)
           …
          ))

or quote the elements which are lists, like this:

    (setq forms-format-list
          (list
           "====== " forms-file " ======\n\n"
           "User : "    1
           '(make-string 20 ?-)
           …
          ))

Forms mode validates the contents of `forms-format-list` when you visit a database. If there are errors, processing is aborted with an error message which includes a descriptive text. See Error Messages, for a detailed list of error messages.

If no `forms-format-list` is specified, Forms mode will supply a default format list. This list contains the name of the file being visited, and a simple label for each field indicating the field number.

Next: Modifying Forms Contents, Previous: Control File Format, Up: Top [Contents][Index]