;;; forms.el -- Forms mode: edit a file as a form to fill in.
;;; Copyright (C) 1991, 1993 Free Software Foundation, Inc.
-;;; Author: Johan Vromans
+;; Author: Johan Vromans <jv@mh.nl>
+;; Version: 1.2.13
;; This file is part of GNU Emacs.
;;; separated by a newline, the fields are separated by a user-defined
;;; field separater (default: TAB).
;;; When shown, a record is transferred to an emacs buffer and
-;;; presented using a user-defined form. One record is shown at a
+;;; presented using a user-defined form. One record is shown at a
;;; time.
;;;
-;;; Forms mode is a composite mode. It involves two files, and two
+;;; Forms mode is a composite mode. It involves two files, and two
;;; buffers.
;;; The first file, called the control file, defines the name of the
-;;; data file and the forms format. This file buffer will be used to
+;;; data file and the forms format. This file buffer will be used to
;;; present the forms.
-;;; The second file holds the actual data. The buffer of this file
+;;; The second file holds the actual data. The buffer of this file
;;; will be buried, for it is never accessed directly.
;;;
;;; Forms mode is invoked using "forms-find-file control-file".
;;;
;;; - a string, e.g. "hello" (which is inserted \"as is\"),
;;;
-;;; - an integer, denoting a field number. The contents of the field
+;;; - an integer, denoting a field number. The contents of the field
;;; are inserted at this point.
;;; The first field has number one.
;;;
-;;; - a function call, e.g. (insert "text"). This function call is
-;;; dynamically evaluated and should return a string. It should *NOT*
+;;; - a function call, e.g. (insert "text"). This function call is
+;;; dynamically evaluated and should return a string. It should *NOT*
;;; have side-effects on the forms being constructed.
;;; The current fields are available to the function in the variable
;;; forms-fields, they should *NOT* be modified.
;;;
;;; forms-field-sep [string, default TAB]
;;; The field separator used to separate the
-;;; fields in the data file. It may be a string.
+;;; fields in the data file. It may be a string.
;;;
;;; forms-read-only [bool, default nil]
;;; 't' means that the data file is visited read-only.
;;; contain fields which span multiple lines in
;;; the form.
;;; This variable denoted the separator character
-;;; to be used for this purpose. Upon display, all
+;;; to be used for this purpose. Upon display, all
;;; occurrencies of this character are translated
-;;; to newlines. Upon storage they are translated
+;;; to newlines. Upon storage they are translated
;;; back to the separator.
;;;
;;; forms-forms-scroll [bool, default t]
;;; forms-new-record-filter [symbol, no default]
;;; If defined: this should be the name of a
;;; function that is called when a new
-;;; record is created. It can be used to fill in
+;;; record is created. It can be used to fill in
;;; the new record with default fields, for example.
;;; Instead of the name of the function, it may
;;; be the function itself.
;;; forms-modified-record-filter [symbol, no default]
;;; If defined: this should be the name of a
;;; function that is called when a record has
-;;; been modified. It is called after the fields
-;;; are parsed. It can be used to register
+;;; been modified. It is called after the fields
+;;; are parsed. It can be used to register
;;; modification dates, for example.
;;; Instead of the name of the function, it may
;;; be the function itself.
;;; the records.
;;;
;;; When a form is changed the record is updated as soon as this form
-;;; is left. The contents of the form are parsed using forms-format-list,
-;;; and the fields which are deduced from the form are modified. So,
+;;; is left. The contents of the form are parsed using forms-format-list,
+;;; and the fields which are deduced from the form are modified. So,
;;; fields not shown on the forms retain their origional values.
;;; The newly formed record and replaces the contents of the
;;; old record in forms--file-buffer.
;;; the records.
;;;
;;; Two exit functions exist: forms-exit (which saves) and forms-exit-no-save
-;;; (which doesn't). However, if forms-exit-no-save is executed and the file
+;;; (which doesn't). However, if forms-exit-no-save is executed and the file
;;; buffer has been modified, emacs will ask questions.
;;;
;;; Other functions are:
;;; The bindings of standard functions scroll-up, scroll-down,
;;; beginning-of-buffer and end-of-buffer are locally replaced with
;;; forms mode functions next/prev record and first/last
-;;; record. Buffer-local variables forms-forms-scroll and
+;;; record. Buffer-local variables forms-forms-scroll and
;;; forms-forms-jump (default: t) may be set to nil to inhibit
;;; rebinding.
;;;
(provide 'forms) ;;; official
(provide 'forms-mode) ;;; for compatibility
-(defconst forms-version "1.2.11"
+(defconst forms-version "1.2.13"
"Version of forms-mode implementation.")
(defvar forms-mode-hooks nil
(defvar forms-number-of-fields nil
"Number of fields per record.")
-
\f
;;; Optional variables with default values
"Read-only mode (defaults to the write access on the data file).")
(defvar forms-multi-line "\C-k"
- "Character to separate multi-line fields (default C-k)")
+ "Character to separate multi-line fields (default C-k).")
(defvar forms-forms-scroll t
"*Non-nil means replace scroll-up/down commands in Forms mode.
"Internal - holds dynamic text to insert between fields.")
(defvar forms-fields nil
- "List with fields of the current forms. First field has number 1.")
+ "List with fields of the current forms. First field has number 1.")
(defvar forms-new-record-filter
"The name of a function that is called when a new record is created.")
\f
;;; forms-mode
;;;
-;;; This is not a simple major mode, as usual. Therefore, forms-mode
+;;; This is not a simple major mode, as usual. Therefore, forms-mode
;;; takes an optional argument 'primary' which is used for the initial
-;;; set-up. Normal use would leave 'primary' to nil.
+;;; set-up. Normal use would leave 'primary' to nil.
;;;
;;; A global buffer-local variable 'forms--mode-setup' has the same effect
;;; but makes it possible to auto-invoke forms-mode using find-file.
;;; Note: although it seems logical to have (make-local-variable) executed
;;; where the variable is first needed, I deliberately placed all calls
;;; in the forms-mode function.
-
+
+;;;###autoload
(defun forms-mode (&optional primary)
"Major mode to visit files in a field-structured manner using a form.
- Commands (prefix with C-c if not in read-only mode):
- \\{forms-mode-map}"
+Commands (prefix with C-c if not in read-only mode):
+\\{forms-mode-map}"
(interactive) ; no - 'primary' is not prefix arg
;; and clean it
(erase-buffer)))
- ;; Make more local variables
+ ;; Make more local variables.
(make-local-variable 'forms--file-buffer)
(make-local-variable 'forms--total-records)
(make-local-variable 'forms--current-record)
;; initialization done
(setq forms--mode-setup t))
-
\f
;;; forms-process-format-list
;;;
;;; Validates forms-format-list.
-;;;
;;; Sets forms--number-of-markers and forms--markers.
(defun forms--process-format-list ()
'forms--number-of-markers)
(setq forms--markers (make-vector forms--number-of-markers nil)))
-
-
\f
;;; Build the format routine from forms-format-list.
;;;
;;;
(defun forms--make-format ()
- "Generate format function for forms"
+ "Generate format function for forms."
(setq forms--format (forms--format-maker forms-format-list))
(forms--debug 'forms--format))
(defun forms--format-maker (the-format-list)
- "Returns the parser function for forms"
+ "Returns the parser function for forms."
(let ((the-marker 0))
(` (lambda (arg)
(setq forms--dynamic-text nil)
)))))
(defun forms--concat-adjacent (the-list)
- "Concatenate adjacent strings in the-list and return the resulting list"
+ "Concatenate adjacent strings in the-list and return the resulting list."
(if (consp the-list)
(let ((the-rest (forms--concat-adjacent (cdr the-list))))
(if (and (stringp (car the-list)) (stringp (car the-rest)))
;;;
(defun forms--make-parser ()
- "Generate parser function for forms"
+ "Generate parser function for forms."
(setq forms--parser (forms--parser-maker forms-format-list))
(forms--debug 'forms--parser))
(defun forms--parser-maker (the-format-list)
- "Returns the parser function for forms"
+ "Returns the parser function for forms."
(let ((the-field nil)
(seen-text nil)
the--format-list)
(setq the-field nil)))
))
\f
-
(defun forms--set-minor-mode ()
(setq minor-mode-alist
(if forms-read-only
(define-key (current-local-map) "\t" 'forms-next-field)))
(defun forms--mode-commands (map)
- "Fill map with all commands."
+ "Fill map with all Forms mode commands."
(define-key map "\t" 'forms-next-field)
(define-key map " " 'forms-next-record)
(define-key map "d" 'forms-delete-record)
)
\f
;;; Changed functions
-;;;
-;;; Emacs (as of 18.55) lacks the functionality of buffer-local
-;;; funtions. Therefore we save the original meaning of some handy
-;;; functions, and replace them with a wrapper.
(defun forms--change-commands ()
- "Localize some commands."
+ "Localize some commands for Forms mode."
;;
;; scroll-down -> forms-prev-record
;; scroll-up -> forms-next-record
t))))
(defun forms--help ()
- "Initial help."
+ "Initial help for Forms mode."
;; We should use
;;(message (substitute-command-keys (concat
;;"\\[forms-next-record]:next"
(message "C-c n:next C-c p:prev C-c <:first C-c >:last C-c ?:help C-c q:exit")))
(defun forms--trans (subj arg rep)
- "Translate in SUBJ all chars ARG into char REP. ARG and REP should
+ "Translate in SUBJ all chars ARG into char REP. ARG and REP should
be single-char strings."
(let ((i 0)
(x (length subj))
(goto-char here))))
(defun forms--show-record (the-record)
- "Format THE-RECORD according to forms-format-list,
- and display it in the current buffer."
+ "Format THE-RECORD and display it in the current buffer."
;; split the-record
(let (the-result
;; The contents of the form are parsed, and a new list of strings
;; is constructed.
;; A vector with the strings from the original record is
- ;; constructed, which is updated with the new contents. Therefore
+ ;; constructed, which is updated with the new contents. Therefore
;; fields which were not in the form are not modified.
;; Finally, the vector is transformed into a list for further processing.
(append the-recordv nil))))
(defun forms--update ()
- "Update current record with contents of form. As a side effect: sets
-forms--the-record-list ."
+ "Update current record with contents of form.
+As a side effect: sets forms--the-record-list ."
+
(if forms-read-only
(progn
(message "Read-only buffer!")
(save-excursion
(set-buffer forms--file-buffer)
- ;; Insert something before kill-line is called. See kill-line
- ;; doc. Bugfix provided by Ignatios Souvatzis.
+ ;; Insert something before kill-line is called. See kill-line
+ ;; doc. Bugfix provided by Ignatios Souvatzis.
(insert "*")
(beginning-of-line)
(kill-line nil)
(forms--update)
(set-buffer-modified-p nil)
(goto-char here))))
-
\f
;;; Start and exit
+
+;;;###autoload
(defun forms-find-file (fn)
- "Visit file FN in forms mode"
+ "Visit a file in Forms mode."
(interactive "fForms file: ")
(find-file-read-only fn)
(or forms--mode-setup (forms-mode t)))
+;;;###autoload
(defun forms-find-file-other-window (fn)
- "Visit file FN in form mode in other window"
+ "Visit a file in Forms mode in other window."
(interactive "fFbrowse file in other window: ")
(find-file-other-window fn)
(eval-current-buffer)
(or forms--mode-setup (forms-mode t)))
(defun forms-exit (query)
- "Normal exit. Modified buffers are saved."
+ "Normal exit from Forms mode. Modified buffers are saved."
(interactive "P")
(forms--exit query t))
(defun forms-exit-no-save (query)
- "Exit without saving buffers."
+ "Exit from Forms mode without saving buffers."
(interactive "P")
(forms--exit query nil))
-
\f
;;; Navigating commands
(forms-jump-record 1))
(defun forms-last-record ()
- "Jump to last record. As a side effect: re-calculates the number
- of records in the data file."
+ "Jump to last record.
+As a side effect: re-calculates the number of records in the data file."
(interactive)
(let
((numrec
(setq forms--total-records numrec)
(message "Number of records reset to %d." forms--total-records)))
(forms-jump-record forms--total-records))
-
\f
;;; Other commands
+
(defun forms-view-mode ()
"Visit buffer read-only."
(interactive)
;; (setq forms-new-record-filter 'my-new-record-filter)
(defun forms-insert-record (arg)
- "Create a new record before the current one. With ARG: store the
- record after the current one.
- If a function forms-new-record-filter is defined, or forms-new-record-filter
- contains the name of a function, it is called to
- fill (some of) the fields with default values."
+ "Create a new record before the current one.
+With ARG: store the record after the current one.
+If a function forms-new-record-filter is defined, or
+forms-new-record-filter contains the name of a function,
+it is called to fill (some of) the fields with default values."
; The above doc is not true, but for documentary purposes only
(interactive "P")
(forms-jump-record forms--current-record))
(defun forms-delete-record (arg)
- "Deletes a record. With ARG: don't ask."
+ "Deletes a record. With a prefix argument: don't ask."
(interactive "P")
(forms--checkmod)
(if (or arg
;;; Special service
;;;
(defun forms-enumerate (the-fields)
- "Take a quoted list of symbols, and set their values to the numbers
-1, 2 and so on. Returns the higest number.
+ "Take a quoted list of symbols, and set their values to sequential numbers.
+The first symbol gets number 1, the second 2 and so on.
+It returns the higest number.
Usage: (setq forms-number-of-fields
(forms-enumerate
the-index))
\f
;;; Debugging
-;;;
+
(defvar forms--debug nil
"*Enables forms-mode debugging if not nil.")
(defun forms--debug (&rest args)
- "Internal - debugging routine"
+ "Internal debugging routine."
(if forms--debug
(let ((ret nil))
(while args
projects / emacs.git / commitdiff