GNU Info

(forms)Format Description

---

Next: Modifying Forms Contents Prev: Control File Format Up: Top

---

Enter node , (file) or (file)node

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.  Note: 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.