Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume13/forms.el/part03

Text File | 1990-06-15 | 17.6 KB | 544 lines

Newsgroups: comp.sources.misc
subject: v13i051: Emacs forms mode 1.1 - part 03 of 03
from: [e-mail] (Johan Vromans)
Sender: [e-mail] (Brandon S. Allbery - comp.sources.misc)

Posting-number: Volume 13, Issue 51
Submitted-by: [e-mail] (Johan Vromans)
Archive-name: forms.el/part03

---- Cut Here and unpack ----
#!/bin/sh
# this is forms.03 (part 3 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file forms.ti continued
#
if touch 2>&1 | fgrep '[-amc]' > /dev/null
 then TOUCH=touch
 else TOUCH=true
fi
if test ! -r shar3_seq_.tmp; then
    echo "Please unpack part 1 first!"
    exit 1
fi
(read Scheck
 if test "$Scheck" != 3; then
    echo "Please unpack part $Scheck next!"
    exit 1
 else
    exit 0
 fi
) < shar3_seq_.tmp || exit 1
echo "x - Continuing file forms.ti"
sed 's/^X//' << 'SHAR_EOF' >> forms.ti &&
Xeach of which can be either a @code{string} or a @code{number}. The
Xformatting elements are processed in the order they appear in the list.
X
XA @code{string} formatting element is inserted in the forms ``as is''.
X
XA @code{number} element selects a field of the record. The contents of
Xthis field are inserted. The first field of the record has number 1
X(one).
X
XIf a record does not contain the number of fields as specified in
X@code{forms-number-of-fields}, a warning message will be printed. Excess
Xfields are ignored, missing fields are set to empty.
X
XThe control file which shows your @file{/etc/passwd} file as demonstrated
Xin the beginning of this document looks as follows:
X@example
X;; This demo visits /etc/passwd.
X
X(setq forms-file "/etc/passwd")
X(setq forms-number-of-fields 7)
X(setq forms-read-only t)                 ; to make sure
X(setq forms-field-sep ":")
X(setq forms-multi-line nil)              ; not allowed
X
X(setq forms-format-list
X     '("====== /etc/passwd ======\n\n"
X       "User : "    1
X       "   Uid: "   3
X       "   Gid: "   4
X       "\n\n"
X       "Name : "    5
X       "\n\n"
X       "Home : "    6
X       "\n\n"
X       "Shell: "    7
X       "\n"))
X@end example
X
XUpon startup, the contents of @code{forms-format-list} are
Xvalidated. If errors are encountered, processing is aborted with
Xan error message which includes a descriptive text. @xref{Error
XMessages}, for a detailed list of error messages.
X
X@node Modifying Forms Contents, Forms Mode Commands, Forms Format Description, Top
X@section Modifying The Forms Contents
X
XIf a forms is not read-only, it's contents can be modified.
X
XAll normal editor commands may be used to change the forms. There is no
Xdistinction between the ``fixed'' text and the text from the fields of
Xthe records. However, upon completion, the forms is parsed to extract
Xthe new contents of the fields. The ``fixed'' portions of the forms are
Xused to delimit the fields, these portions should therefore not be
Xmodified to avoid the risk that the field contents cannot be determined.
XMoreover, ambiguous field contents, which can not be discriminated from
X``fixed'' text, must be avoided.
X
XIf the contents of the forms cannot be recognized properly, this is
Xsignaled using a descriptive text. @xref{Error Messages}, for more info.
XThe cursor will indicate the last part of the forms which was
Xsuccessfully parsed.
X
X@node Forms Mode Commands, Key Bindings, Modifying Forms Contents, Top
X@section Forms mode commands
X
X@table @kbd
X@findex forms-find-file
X@item M-x forms-find-file @var{file}
X@end table
X
XVisits @var{file}, runs @code{eval-current-buffer} on it, and puts the
Xbuffer into forms-mode. The first record of the data file will be loaded
Xand shown.
X
XThe modeline will display the major mode @code{"Forms"} followed by the
Xminor mode @code{"View"} if the file is visited read-only.  The number
Xof the current record (@var{n}) and the total number of records
X(@var{t}) in the file is shown in the modeline as @code{"n/t"}.@*
XFor example:
X@example
X--%%-Emacs: passwd-demo          (Forms View 1/54)----All-------
X@end example
X
X@table @kbd
X@findex forms-find-file-other-window
X@item M-x forms-find-file-other-window @var{file}
X@end table
X
XThis command is similar to @code{forms-find-file}, but visits the file
Xin another window.
X
XIf the buffer is not read-only, you may change the buffer to modify the
Xfields in the record. When the current record is left, e.g. by switching
Xto another record, the contents of the buffer are parsed using the
Xspecifications in @code{forms-format-list}, and a new record is constructed
Xwhich replaces the current record in the data file. Fields of the record
Xwhich are not shown in the forms are not modified; they retain their
Xoriginal contents.
X
XMost forms mode commands are bound to keys, and are accessible with the
Xconventional @code{C-c} prefix. In read-only mode this prefix is not used.
X@xref{Key Bindings}, for the default key bindigs used by forms mode.
X
XThe following commands are available within forms mode.
X
X@table @kbd
X@findex forms-next-record
X@item forms-next-record
Xshows the next record. With a prefix argument, show the n-th next
Xrecord.
X
X@findex forms-prev-record
X@item forms-prev-record
Xshows the previous record. With a prefix argument, show the n-th previous
Xrecord.
X
X@findex forms-jump-record
X@item forms-jump-record
Xjumps to a record by number. A prefix argument is used for the record
Xnumber to jump to. If no prefix argument is supplied, a record number is
Xasked for in the minibuffer.@*
XIf an invalid record number is supplied, an error message is displayed
Xreading the offending record number, and the allowable range of numbers.
X
X@findex forms-first-record
X@item forms-first-record
Xjumps to the first record.
X
X@findex forms-last-record
X@item forms-last-record
Xjumps to the last record. Also re-counts the number of records in the data
Xfile.
X
X@findex forms-next-field
X@item forms-next-field
Xjumps to the next field in the forms. With a numeric argument: jumps
Xthat many fields, or to the first field if there are not that many
Xfields left.
X
XJumping to fields is implemented using @var{markers}, which are placed
Xin front of the fields. If the contents of the forms are modified, the
Xmarkers are adjusted. However, if text around a marker has been deleted
Xfrom the screen and inserted again it is possible that this marker no
Xlonger points at its field correctly.
X@xref{Markers,,Markers, emacs, the GNU Emacs Lisp Manual}, for more
Xinformation on markers.
X
X@findex forms-view-mode
X@item forms-view-mode
Xswitches to read-only mode. Forms mode commands may no longer be prefixed
Xwith @code{C-c}.
X
X@findex forms-edit-mode
X@item forms-edit-mode
Xswitches to edit mode. Forms mode commands must be prefixed with
X@code{C-c}.@*
XSwitching to edit mode is only possible if write access to the data
Xfile is allowed.
X
X@findex forms-insert-record
X@item forms-insert-record
Xcreate a new record, which is inserted before the current record. An
Xempty form is presented, which can be filled in using familiar editor
Xcommands. With a prefix argument: the new record is created @i{after} the
Xcurrent one.
X
X@findex forms-delete-record
X@item forms-delete-record
Xdeletes the current record. You are prompted for confirmation before the
Xrecord is deleted unless a prefix argument has been provided.
X
X@findex forms-search
X@item forms-search @var{regexp}
Xsearches for @var{regexp} in all records following this one. If found,
Xthis record is shown.@*
XThe next time it is invoked, the previous regexp is the default, so you
Xcan do repeated searches by simply pressing @key{RET} in response to the
Xprompt.
X
X@findex revert-buffer
X@item revert-buffer
Xreverts a possibly modified forms to its original state. It only affect
Xthe record currently in the forms.
X
X@findex forms-exit
X@item forms-exit
Xterminates forms processing. The data file is saved
Xif it has been modified.
X
X@findex forms-exit-no-save
X@item forms-exit-no-save
Xaborts forms processing. If the data file has been modified Emacs will
Xask questions.
X
X@findex describe-mode
X@item describe-mode
Xgives additional help.
X
X@findex save-buffer
X@item save-buffer
Xsaves the changes in the data file, if modified.
X
X@end table
X
X@vindex forms-forms-scroll
X@findex scroll-up
X@findex scroll-down
XIf the variable @code{forms-forms-scrolls} is set to a value other
Xthan @code{nil} (which it is, by default), the Emacs functions
X@code{scroll-up} and @code{scroll-down} will perform a
X@code{forms-next-record} and @code{forms-prev-record} when in forms
Xmode.  So you can use your favourite page commands to page through the
Xdata file.
X
X@vindex forms-forms-jump
X@findex beginning-of-buffer
X@findex end-of-buffer
XLikewise, if the variable @code{forms-forms-jump} is not @code{nil}
X(which it is, by default), Emacs functions @code{beginning-of-buffer}
Xand @code{end-of-buffer} will perform @code{forms-first-record} and
X@code{forms-last-record} when in forms mode.
X
X@vindex forms-mode-hooks
XAfter forms mode is entered, functions contained in
X@code{forms-mode-hooks} are executed to perform user defined customization.
X
X@node Key Bindings, Miscellaneous, Forms Mode Commands, Top
X@section Key bindings
X
XThis section describes the key bindings as they are defined when
Xinvoking forms mode.@*
XAll commands must be prefixed with @kbd{C-c} when editing a forms. If a
Xforms is read-only, @kbd{C-c} is not used.  The only exception to
Xthis rule is @code{forms-next-field}, which is bound to @kbd{TAB} in all
Xmaps.
X
X@table @kbd
X
X@itemx C-c @key{TAB}
X@code{forms-next-field}
X
X@itemx C-c @key{SPC}
X@code{forms-next-record}
X
X@itemx C-c <
X@code{forms-first-record}
X
X@itemx C-c >
X@code{forms-first-record}
X
Xv@itemx C-c d
X@code{forms-delete-record}
X
X@itemx C-c e
X@code{forms-edit-mode}
X
X@itemx C-c i
X@code{forms-insert-record}
X
X@itemx C-c j
X@code{forms-jump-record}
X
X@itemx C-c n
X@code{forms-next-record}
X
X@itemx C-c p
X@code{forms-prev-record}
X
X@itemx C-c q
X@code{forms-exit}
X
X@itemx C-c s @var{regexp}
X@code{forms-search}
X
X@itemx C-c v
X@code{forms-view-mode}
X
X@itemx C-c x
X@code{forms-exit-no-save}
X
X@itemx C-c ?
X@code{describe-mode}
X
X@itemx C-c @key{DEL}
X@code{forms-prev-record}
X
X@end table
X
X@node Miscellaneous, Error Messages, Key Bindings, Top
X@section Miscellaneous
X
X@vindex forms-version
XA global variable @var{forms-version} holds the version information of
Xthe current implementation of forms mode.
X
XCare has been taken to localize the current information of the forms
Xmode, so it is possible to visit multiple files in forms mode
Xsimultaneously, even if they have different properties.
X
XIf a control file is visited using the standard @code{find-file}
Xcommands, forms mode can be enabled with the command @code{M-x forms-mode}.@*
XForms mode will be automatically enabled if the file contains
Xthe string @code{"-*- forms -*-"} somewhere in the first line. However,
Xthis makes it hard to edit the control file itself so you'd better think
Xtwice before using this.
X
XThe default format for the data file, using @key{TAB} to separate fields
Xand @code{C-k} to separate multi-line fields, matches the file format of
Xsome popular Macintosh database programs, e.g. FileMaker. So
X@code{forms-mode} could decrease the need to use Apple computers.
X
X@node Error Messages, Credits, Miscellaneous, Top
X@section Error Messages
X
XThis section describes all error messages which can be generated by
Xforms mode.
X
X@table @code
X@item 'forms-file' has not been set
XThe variable @code{forms-file} was not set by the control file.
X
X@item 'forms-number-of-fields' has not been set
XThe variable @code{forms-number-of-fields} was not set by the control
Xfile.
X
X@item 'forms-number-of-fields' must be > 0
XThe variable @code{forms-number-of-fields} did not contain a positive
Xnumber.
X
X@item 'forms-field-sep' is not a string
X@itemx 'forms-multi-line' must be nil or a one-character string
XThe variable @code{forms-multe-line} was set to something other than
X@code{nil or} a single-character string.
X
X@item 'forms-multi-line' is equal to 'forms-field-sep'
XThe variable @code{forms-multi-line} may not be equal to
X@code{forms-field-sep} for this would make it impossible to distinguish
Xfields and the lines in the fields.
X
X@item 'forms-format-list' has not been set
X@itemx 'forms-format-list' is not a list
XThe variable @code{forms-format-list} was not set to a lisp @code{list}
Xby the control file.
X
X@item forms error: field number @var{XX} out of range 1..@var{NN}
XA field number was supplied with a value of @var{XX}, which was not
Xgreater that zero and smaller than or equal to the number of fields in the
Xforms, @var{NN}.
X
X@item invalid element in 'forms-format-list': @var{XX}
XA list element was supplied in @var{forms-format-list} which was not a
X@code{string} nor a @code{number}.
X
X@item forms--make-format failed at @var{XX} [of @var{YY}]
XAn internal error caused the generation of the format routine to fail.
X
X@item parse error: not looking at "@var{TEXT}"
XWhen re-parsing the contents of a forms, the text @var{TEXT}, which
Xstarts the forms, could not be found.
X
X@item parse error: cannot find "@var{TEXT}"
XWhen re-parsing the contents of a forms, the text @var{TEXT}, which
Xseparates two fields, could not be found.
X
X@item parse error: cannot parse adjacent fields @var{XX} and @var{YY}
XFields @var{XX} and @var{YY} were not separated by text, so could not be
Xparsed again.
X
X@item forms--make-parser failed - field @var{XX} pending
X@itemx forms--make-parser failed - text @var{TEXT} pending
X@itemx forms--make-parser failed at @var{XX} [of @var{YY}]
XAn internal error caused the generation of the format routine to fail.
X
X@item Record has @var{XX} fields instead of @var{YY}
XThe number of fields in this record in the data file did not match
X@code{forms-number-of-fields}. Missing fields will be set to empty.
X
X@item Multi-line fields in this record - update refused!
XThe current record contains newline characters, hance can not be written
Xback to the data file, for it would corrupt it.@*
Xprobably a field was set to a multi-line value, while the setting of
X@code{forms-multi-line} prohibited this.
X
X@item Record number @var{XX} out of range 1..@var{YY}
XA jump was made to non-existing record @var{XX}. @var{YY} denotes the
Xnumber of records in the file.
X
X@item Stuck at record @var{XX}
XAn internal error prevented a specific record from being retrieved.
X
X@end table
X
X@node Credits, Concept Index, Error Messages, Top
X@section Credits
X
XForms mode is developed by Johan Vromans @code{<jv@@mh.nl>} at Multihouse
XReseach in Gouda, the Netherlands.
X
XThis documentation was slightly inspired by the documentation of ``rolo
Xmode'' by Paul Davis at Schlumberger Cambridge Research
X@code{<davis%scrsu1%sdr.slb.com@@relay.cs.net>}.
X
XNone of this would have been possible without GNU Emacs of the Free
XSoftware Foundation. Thanks, Richard!
X
X@node Concept Index, Variable Index, Credits, Top
X@unnumbered Concept Index
X@printindex cp
X
X@node Variable Index, Function Index, Concept Index, Top
X@unnumbered Variable Index
X@printindex vr
X
X@node Function Index, , Variable Index, Top
X@unnumbered Function Index
X@printindex fn
X
X@contents
X@bye
SHAR_EOF
echo "File forms.ti is complete" &&
$TOUCH -am 0610122090 forms.ti &&
chmod 0444 forms.ti ||
echo "restore of forms.ti failed"
set `wc -c forms.ti`;Wc_c=$1
if test "$Wc_c" != "21254"; then
    echo original size 21254, current size $Wc_c
fi
# ============= demo1 ==============
echo "x - extracting demo1 (Text)"
sed 's/^X//' << 'SHAR_EOF' > demo1 &&
X;; demo for forms-mode
X;;
X;; This demo visits /etc/passwd.
X
X(setq forms-file "/etc/passwd")
X(setq forms-read-only t)        ; to make sure
X(setq forms-field-sep ":")
X(setq forms-number-of-fields 7)
X(setq forms-format-list
X     '("====== Visiting /etc/passwd ======\n\n"
X       "User : "    1
X       "   Uid: "    3
X       "   Gid: "    4
X       "\n\n"
X       "Name : "    5
X       "\n\n"
X       "Home : "    6
X       "\n\n"
X       "Shell: "    7
X       "\n"))
SHAR_EOF
$TOUCH -am 0307144790 demo1 &&
chmod 0644 demo1 ||
echo "restore of demo1 failed"
set `wc -c demo1`;Wc_c=$1
if test "$Wc_c" != "436"; then
    echo original size 436, current size $Wc_c
fi
# ============= demo2 ==============
echo "x - extracting demo2 (Text)"
sed 's/^X//' << 'SHAR_EOF' > demo2 &&
X;; test forms-mode    -*- emacs-lisp -*-
X;;
X(setq forms-file "demo2.dat")
X(setq forms-number-of-fields 11)
X(setq forms-format-list
X     '(
X       "====== Public Domain Software Archive ======\n\n"    5
X       " - "            8
X       "\n\n"
X       "Article: "        1
X       "/"            4
X       "    Issue: "        3
X       "    Date: "        10
X       "\n\n"
X       "Submitted by: "        7
X       "\n\n"
X       "Keywords: "        9
X       "\n\n"
X       "Parts: "        6
X       "\n\n====== Remarks ======\n\n"        11
X     ))
SHAR_EOF
$TOUCH -am 0307144790 demo2 &&
chmod 0644 demo2 ||
echo "restore of demo2 failed"
set `wc -c demo2`;Wc_c=$1
if test "$Wc_c" != "475"; then
    echo original size 475, current size $Wc_c
fi
# ============= demo2.dat ==============
echo "x - extracting demo2.dat (Text)"
sed 's/^X//' << 'SHAR_EOF' > demo2.dat &&
Xcomp.sources.unix        v11i008    269    getty-enable    1    [e-mail] (Ronald S. Karr)    Getty on/off programs for 4.[23] BSD        890505
Xcomp.sources.unix    11    v11i022    283    syslog    1    emory!arnold (Arnold D. Robbins {EUCC})    Development version of syslog(3), for ATT, too        28/08/1987
Xcomp.sources.unix    11    v11i033    290    less3    3    sun!intsc!convgt!mark    The 'less' pager        02/09/1987
Xcomp.sources.unix    11    v11i036    293    test.el    3    "Mark A. Ardis" <[e-mail]>    Test system for GNU Emacs        10/09/1987
SHAR_EOF
$TOUCH -am 0307144790 demo2.dat &&
chmod 0644 demo2.dat ||
echo "restore of demo2.dat failed"
set `wc -c demo2.dat`;Wc_c=$1
if test "$Wc_c" != "476"; then
    echo original size 476, current size $Wc_c
fi
rm -f shar3_seq_.tmp
echo "You have unpacked the last part"
exit 0