This is Info file database.info, produced by Makeinfo-1.55 from the input file database.texi.  File: database.info, Node: Reading from disk, Prev: Nonregular file layout, Up: Database file layout What happens when a database is read in from disk ================================================= In brief, the following happens after you execute `db-find-file': 1. If the database is already read in and its buffer has not been killed, the buffer is simply selected. No other work is done. 2. Otherwise, the database file is inserted in a special buffer of its own. If the database is in EDB internal file layout (that is, if an identifying header is found), it is read in immediately. Otherwise, a new, empty database is created. In either case the dynamic variable `database' is bound; this makes it possible to refer to the database in the auxiliary and format files (even before it has been read in, if it is not in EDB internal file layout). 3. The format file is found (*note Auxiliary files::.), and the data display buffer is created. 4. The function `db-setup-format' is called; it performs the rest of the work necessary for setting up the data display buffer (everything up to the running of `db-before-read-hooks'). Its first action is to insert the format file's contents into the data display buffer. 5. The auxiliary file, if any, is loaded. This happens in the data display buffer, and the dynamic variable `database' and the buffer-local variable `dbc-database' are bound to the current database. For more information about how the auxiliary file is found and what it can do, see *Note Auxiliary files::. The auxiliary file is not read every time that `db-setup-format' is called, only when a database's primary display format is read. (The primary display format is the one initially selected when a database is first read in.) 6. The "Local Variables" section, if any, of the format file is executed; this may set variables and execute Emacs Lisp code, exactly analogously to the auxiliary file. EDB ignores the value of `inhibit-local-variables' when evaluating this code. This section is then deleted from the working copy of the file, so that it does not appear in the data display buffer when a user is viewing database records. For more information about the "Local Variables" section of a file, see *Note Variables: (emacs)File Variables. 7. Database information is propagated; for instance, the names of the database fields are known by now, and various other database slots are filled in depending on this information, if they haven't been set yet. 8. The format file is parsed, and literal text and formatting directives are distinguished from one another. This work is done by the `db-setup-format-parse-displayspecs' function. When that function is done, `db-setup-format' returns the database data display buffer as its result. 9. The hooks in `db-before-read-hooks' are run in the data display buffer. 10. If the database had already been read because it was stored in internal file layout, it is massaged a bit to get it into its final form; for instance, the backward links are added between adjacent records. Otherwise, the database is finally read; the values of the `recordsep' and `fieldsep' slots of the database determine whether the layout is regular or nonregular and direct the parsing. The `substitutions' slot and quotation slots (`quotation-char', `quotation-char-regexp', `quoted-regexp', and `quoted-strings') direct replacement of characters that could not be written into the file, and the `stored->actual' slot of each recordfieldspec completes the translation to the data's internal format from its file layout. 11. The hooks in `db-after-read-hooks' are run in the data display buffer. 12. The database has now been read and is in its final form. The first record of the database is displayed in the data display buffer, which is then placed in view mode and selected (made visible to the user).  File: database.info, Node: How information is displayed, Next: Customization, Prev: Database file layout, Up: Top How information is displayed **************************** The display of information, both on the screen (whether in the data display buffer, the summary buffer, or elsewhere) and in other output (such as reports), is controlled by formatting commands. We will discuss a data display buffer by way of example; the formatting specifications are the same for summary buffers and reports as well. Display types should not be confused with record field types; a display type is used to specify how a particular value is shown on the screen, but a record field type constrains the information actually contained in the record field. This chapter does not discuss record field specifications, which specify everything about a record field type except how it is displayed and parsed in output intended for humans to read. For more information about that, and about the distinction between record field types and displaytypes (the latter of which is described in this chapter), *note Record field types::.. A "display format" gives all of the information necessary to create a data display buffer; it consists of literal text that is displayed as is (and may not be edited by a user of the database) and of "display specification"s that instruct EDB how to display a particular field's contents. The display specifications do not appear in the data display buffer; they are replaced by fields' values, which may or may not be editable. An example of a display specification is `\name,width=16', which indicates that the `name' field of the database should be displayed (after being padded or truncated to exactly 16 characters). When a format is first specified, it is parsed and the formatting information specified in the display specification strings is used to create a displayspec structure. Users should never have to manipulate displayspecs directly. * Menu: * Display specifications:: Display specifications * Predefined displaytypes:: Predefined displaytypes * Enumeration displaytypes:: Enumeration types * Defining new displaytypes:: Defining new displaytypes * Display specification optional parameters:: Display specification optional parameters * Display specification abbreviations:: Display specification abbreviations  File: database.info, Node: Display specifications, Next: Predefined displaytypes, Up: How information is displayed Display specifications ====================== Here is a (quite complicated) example display format: \name,one-line-string,actual->display=upcase\ , \occupation' Pay: \\\salary,min-width=4: too much! Address: \addr,indent is home sweet home This display format is valid if the database contains fields called "name", "occupation", "salary", and "addr"; any other fields are ignored. Some typical records would be displayed like this: JOHN DOE, butcher Pay: \ 22: too much! Address: 123 Main St. Anyplace, USA is home sweet home JANE ROE, baker Pay: \4444444: too much! Address: 675 Massachusetts Avenue is home sweet home A display specification consists of a backslash; a fieldname indicating which field of the database record is to be inserted; optional comma-separated type and formatting information; and optionally a backslash followed by a space. A display specification abbreviation, which consists of a backslash and the abbreviation name (and so looks like a simple display specification in which no optional information is specified), can be used instead of a standard display specification; *Note Display specification abbreviations::. A display specification starts with a backslash to distinguish it from the surrounding text. To specify the backslash character in literal text, type it twice; when backslashes occur in pairs they do not indicate the start of a display specification. Display specifications continue as long as the text can be parsed as one. Almost any non-whitespace character may be used as part of a display specification. Whitespace is a good way of indicating the end of a field specification since it never appears in a display specification. A display specification can be terminated without indicating any literal text by placing a backslash and a space at its end; both of these characters will be ignored. This is useful when the literal text that follows the display specification happens to conform to the display specification syntax (is a letter, number, or almost any type of puntuation). The optional information includes the type of this display field and formatting directives for it; if the type is present, then it must come first among the displayspec's optional specifications. Each optional parameter is preceded by a comma to separate it from the preceding one (or from the fieldname, for the first optional parameter). The optional information is typically of the form "SLOTNAME=VALUE", which sets the specified slot to the given value, or "SLOTSETTER", which sets some slot to a particular value. Explicitly specified formatting information overrides any defaults. The display type can be specified by writing a typename (such as `string' or `integer') as the first optional parameter. A type abbreviation may be used instead of a typename; the defined type abbreviations are `#' for integer, `$' for number, `"' for string, and `'' for one-line-string, and they need not be preceded by a comma, though they may be. The display type specifies default values for the display specification (actually for the displayspec structure, which is derived from the display specification). It is rarely necessary even to specify the displaytype--most display specifications consist of simply a backslash and a fieldname--since if the displaytype is omitted then a displaytype with the same name as the record field type (actually the `type' slot of the recordfieldspec) will be used. This works because typically displaytypes and recordfieldtypes with the same names and complementary definitions are declared at the same time; displaytypes and recordfieldtypes are conceptually distinct, however. In particular, you must specify a displaytype that is compatible with the record field type; if you specify a displaytype of `integer' when the data is actually a string, an error will result. You can use function `database-set-fieldnames-to-list' to specify recordfieldtypes; *note The database structure::.. * Menu: * Predefined displaytypes:: Predefined displaytypes * Defining new displaytypes:: Defining new displaytypes * Display specification optional parameters:: Display specification optional parameters * Display specification abbreviations:: display specification abbreviations  File: database.info, Node: Predefined displaytypes, Next: Enumeration displaytypes, Prev: Display specifications, Up: How information is displayed Predefined displaytypes ======================= The file `db-types.el' defines the following displaytypes, corresponding recordfieldtypes, and some useful associated functions. Users can also define displaytypes; see *Note Defining new displaytypes::. integer Ordinary integers. integer-or-nil Integers or `nil', the empty value; `nil' is formatted as the empty string. number Ordinary numbers. A number is an integer or a floating-point number. number-or-nil Numbers or `nil', the empty value; `nil' is formatted as the empty string. yes-no This displayspec corresponds to the boolean recordfieldtype. The field is three characters long and contains "Yes" or "No ". string Ordinary strings. By default there is no maximum or minimum width or height, and subsequent lines are indented relative to the first character of the first line. one-line-string Strings which may not contain newlines. string-or-nil Either a string or the value `nil', which is displayed as the empty string. nil-or-string Either a string or the value `nil'. When the user enters the empty string as the field value, or when a new record is created, the value `nil' is used in preference to the empty string. one-line-string-or-nil Both a one-line-string and a string-or-nil. date A date which specifies zero or more of the year, month, and day. The date is formatted by `format-date' and parsed by `parse-date-string'; see below for details. time A time which specifies zero or more of the hour, minute, and second. The time is formatted by `format-time' and parsed by `parse-time-string'; see below for details. * Menu: * Date displaytype:: Date displaytype * Time displaytype:: Time displaytype  File: database.info, Node: Date displaytype, Next: Time displaytype, Up: Predefined displaytypes Date displaytype ---------------- EDB defines a date abstraction and a variety of useful operations upon it; the best way to learn about these features is to read `db-time.el' This section provides more detail about the date displaytype. A date specifies a year, month, and day (all integers); any or all of these components may be omitted. Dates are created by the constructor `make-date' and a date's components are retrieved using the selectors `date-year', `date-month', and `date-day'. `make-date' Make an EDB date object with arguments YEAR MONTH DAY. [[[Document parse-date-string, format-date, simple-format-date, def-xxx-type.]]] [[[ I added several useful (to me, anyway) displayspecs for various date types. These are meant to be used in a display spec, like: \datefield,date-mmddyy The displayspecs are implemented with similarly named formatting functions, which I also implemented. All of the new formatting functions are named format-date-XXX, where XXX are the various styles. ]]]  File: database.info, Node: Time displaytype, Prev: Date displaytype, Up: Predefined displaytypes Time displaytype ---------------- [[[Similarly to the above, for times.]]]  File: database.info, Node: Enumeration displaytypes, Next: Defining new displaytypes, Prev: Predefined displaytypes, Up: How information is displayed Enumeration types ================= An enumeration displaytype is used for fields whose values are one of a fixed set of alternatives. Each alternative may be a single character (say, M or F for gender) or specifyable by a single character (for example, if the first letters of the alternatives are unique); the user need only type a single character in order to select one of the alternatives. Another possiblity is that each alternative consists of an entire string entered with completion. (The string may consist of only a single character if desired, but the user must still type RET after entering the string.) The internal representation of the data--its recordtype--need have nothing to do with the way that the alternatives are specified. The next two sections describe the two types of enumeration displaytypes, which are nicknamed one-char-enum and (for the multicharacter alternative type) enum. * Menu: * One-character enumeration displaytypes:: One-character enumeration displaytypes * Multi-character enumeration displaytypes:: Multi-character enumeration displaytypes  File: database.info, Node: One-character enumeration displaytypes, Next: Multi-character enumeration displaytypes, Up: Enumeration displaytypes One-character enumeration displaytypes -------------------------------------- One-character enumeration displaytypes are not yet implemented. `define-one-char-enum-displaytype' Not documented.  File: database.info, Node: Multi-character enumeration displaytypes, Prev: One-character enumeration displaytypes, Up: Enumeration displaytypes Multi-character enumeration displaytypes ---------------------------------------- Multi-character enumeration displaytypes require a user to enter an entire string in order to specify one of the alternatives. This typing may be done with completion in the minibuffer, meaning keys such as TAB and ? will complete a partly-entered choice or list the remaining possibilities. (For more about completion, see *Note Completion: (emacs)Completion.) The internal, input, display, and file storage represenations of the value may all be different. Multi-character enumeration displaytypes (also known as enum displaytypes) are created by calling the following function, which also creates a corresponding recordfieldtype. `define-enum-type' Make TYPENAME (a symbol or string) an enumerated type. Both a displaytype and a recordfieldtype are created. ALTERNATIVES is a list. Each alternative is a list of up to four components: the internal representation, any constant Lisp object, often a string; the input representation typed by the user to specify this alternative, a string or list of strings (for multiple input representations); the display representation, a string; and the file storage representation, a string. If the input representation is omitted and the internal representation is a string, that string is used. If the display representation is omitted, it defaults to the first input representation. The display representation is automatically also a valid input representation. If the file storage representation is omitted, it defaults to the display representation. If all the other components are omitted, the internal representation string may be used in place of a one-element list containing just it. Optional argument OPTSTRING is a displayspec option string. When a record field's type is an enum type, both EDB and code written by the database designer may assume that the value in the record field is one of the valid representations. (Similarly, when a field's type is string, EDB can assume that the field content is actually a string.) This means that the empty string, `nil', and other special values must be specifically mentioned when the enumeration type is defined. Here is a way to define an enumeration type which is either a day of the week or the empty string: (define-enum-type 'workday '("Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "")) If it is possible for the field value to be `nil' (but not the empty string) after reading the database, and `nil' should be displayed as "Unknown" (and that string parsed into a value of `nil'), the following definition suffices: (define-enum-type 'workday '("Monday" "Tuesday" "Wednesday" "Thursday" "Friday" (nil "Unknown")))  File: database.info, Node: Defining new displaytypes, Next: Display specification optional parameters, Prev: Enumeration displaytypes, Up: How information is displayed Defining new displaytypes ========================= When you are about to type a complicated display specification--or a simple one more than once--consider defining and using a displaytype instead. Displaytypes are more concise (and so less cumbersome and less error-prone), easier to change (since a change to the displaytype can affect every display specification that uses it), and clearer (since a descriptive typename makes immediately clear what the intention is). Furthermore, displaytypes can be built up incrementally, with each one making a few changes to those from which it inherits defaults. There are two ways to define a new displaytype; each requires specifying the name of the displaytype and some formatting information to be associated with that displaytype. The first method permits a displaytype to be specified by the optional part of a display specification, which is a string consisting of comma-delimited optional parameters. The first optional parameter may be a type, in which case the defaults for values not explicitly set in the other parameters are taken from that type. `define-displaytype-from-optstring' Define a displaytype named TYPENAME according to OPTSTRING. tYPENAME is a symbol or string and OPTSTRING is the optional parameters part of a display specification string. The second method is more useful for complicated displaytypes; it is also somewhat more efficient, which is why the file `db-types.el' uses it to define the standard predefined types. This method is to create a displayspec directly, modify it as desired using the structure slot modifiers (i.e., `displayspec-set-'SLOTNAME; see *Note Display specification optional parameters::, for a list of slotnames), and then associate a typename with the displayspec. In fact, this is precisely what `define-displaytype-from-optstring' does. `define-displaytype-from-displayspec' Define a displaytype named TYPENAME (a symbol) with the default DISPLAYSPEC. DISPLAYSPEC may also be a typename symbol itself. `make-displayspec' Create and return a new displayspec. `displaytype->displayspec' Return a copy of the displayspec corresponding to string or symbol DISPLAYTYPE. Return `nil' if there's no corresponding displayspec.  File: database.info, Node: Display specification optional parameters, Next: Display specification abbreviations, Prev: Defining new displaytypes, Up: How information is displayed Display specification optional parameters ========================================= This section describes the display specification optional parameters, which correspond exactly to slots of the displayspec, EDB's internal representation of the display specification. Optional display specification parameters are separated only by commas; display specifications never contain whitespace. These parameters are of two forms: slotsetters, which are a single word and set a slot to a particular value; and slot assigners, which are of the form "SLOTNAME=VALUE" and set the slot to the value. Unless otherwise specified, each slot can be set by a slot assigner whose name is the same as that of the slot. An example of a display specification containing two optional parameters, one a slot assigner and one a slotsetter, is `\name,width=16,unreachable'. Display specification fields are processed in order, so only the last instance of a particular parameter has any effect. Any explicitly specified parameter overrides defaults, values inferred from the type, or previously specified parameters. If you find yourself repeatedly writing similar display specifications, or large, bulky display specifications, consider defining a new type to do some or all of the work for you; see *Note Defining new displaytypes::. `record-index' This integer is the field index in a database record of the value formatted by this displayspec. This is set by looking up the fieldname part of the displayspec. `indent' This a boolean value determines whether the second and subsequent lines should align with the beginning of the first one or should be flush left, in column 0. It is set and unset with the `indent' and `noindent' slotsetters. The first of the following displays has indent set, and the second does not: Name: John Doe Address: 123 Main St. Anyplace, USA Name: John Doe Address: 123 Main St. Anyplace, USA This causes alignment of the first character of subsequent lines with the first character of the first line; it does not do anything clever with whitespace in the field value, nor does it align different lines differently. `min-width' `max-width' These integers are the minimum and maximum widths which the display may occupy. If the formatted value is too short, the function in the `padding-action' slot is called to lengthen and/or justify it. If the formatted value is too long, the function in the `truncation-display-action' slot is called to shorten it; if that slot is empty, the field is simply truncated. The `width' slot assigner sets both the `min-width' and `max-width' displayspec slots. The `min-length', `max-length', and `length' slot specifiers are synonyms for the `min-width', `max-width', and `width' slot specifiers. `min-height' `max-height' These are analogous to `min-width' and `max-width', but for the number of lines occupied by the formatted value (actually, the number of newlines in the string, plus one). There is a `height' slot assigner which sets them both. `truncation-display-action' This function helps reduce the size of the formatted value when it is too large to fit in the specified displayspec size. It defaults to simply truncating the formatted field to the maximum permissible size. It may also be set with the `trunc-display' slot assigner. At present, this function is only called if the formatted value is too wide; there is no analogous function called when it is too tall. `padding-action' This function determines how a field that is too small for the displayspec (that is, the printed representation contains fewer characters than specified in the `min-width' slot) should be expanded to fit. The padding function takes three arguments: the minimum length, the unpadded display representation, and the length of that representation. The `padding-action' slot may also be set to a cons of a padding character and a padding direction: `nil' for left-justification (padding on the right), and non-`nil' for right-justification. (You cannot set the `padding-action' displayspec slot to a cons by using a display specification, since display specifications may not contain whitespace, so the easiest way to right-justify a single field is to use the `right-justify' slotsetter.) The default, which can also be obtained just by setting the slot to `nil', is to pad on the right with space characters. `actual->display' `display->actual' These functions actually do the work of converting between the data's internal representation and its displayed representation (a string). Other functions (such as those in the `truncation-display-action' and `padding-action' slots) may then be called on the result returned by the `actual->display' function. These slots may be set with the `a->d' and `d->a' slot assigners. The `display->actual' function takes either one argument or four arguments: either just the field text or the field text, the previous field value, the record being operated upon, and the record fieldnumber of the field in question. EDB ascertains at runtime how many arguments the function should be applied to. The old field value is passed in case it contains hidden (undisplayed) attributes that need to be preserved across changes. The other two arguments permit a particular `display->actual' function to be used for more than one field of a record, allow the field text parse to depend on other record field values, and provide for other complicated needs. Most `display->actual' functions can be specified to take a single argument. The `actual->display' function takes either one argument or three arguments: either just the field value or the field value, the record, and the record fieldnumber. EDB ascertains at runtime how many arguments the function should be applied to. The reasons the additional arguments may be specified are similar to those outlined above (for instance, to permit the displayed representation of a field to depend on other information in the record); most `actual->display' functions will just take one argument--for intance, `upcase' is a valid `actual->display' function. `match-actual->display' `match-display->actual' These functions are like `actual->display' and `display->actual', but are only invoked when reading a displaying a search specification. If they are not specified (as will usually be the case), then the ordinary (`match-'-less) versions are used for search specifications too. This is used, for instance, for the string type, so that `dbm-string-prefix-regexp' can be used to specify a regular expression search rather than a substring search. These slots should be set to symbols, not to functions proper; that is, to specify that function `foo' should be use, set the slot to `'foo', not to `(function foo)'. I don't know that these belong in the displayspec, but I don't quite know where they do belong. `truncation-editing-action' This function specifies what to do when a field being edited is too large for the specified displayspec size; this action may be different from that taken when simply displaying the offending value. It may also be set with the `trunc-edit' slot assigner. `reachablep' A Boolean value determining whether movement commands should skip this display field. The `reachable' and `unreachable' slotsetters are used to assign a value to this slot.  File: database.info, Node: Display specification abbreviations, Prev: Display specification optional parameters, Up: How information is displayed Display specification abbreviations =================================== Complicated display specifications--those which specify more than a few optional parameters--can clutter the display format, keeping it from looking like the data display buffer will when a database record is being displayed. The user may tolerate the complicated display specification, define a new displaytype (which would permit the display specification to consist of just the fieldname and displaytype), or use a field abbreviation which is defined elsewhere in the format file. The display specification abbreviation is a symbol which expands to a full display specification; when a field specification consisting of only the abbreviation is encountered, the expansion is substituted and processing continues. (Actually, a displayspec corresponding to the expansion is used, but since displayspecs are immutable, this doesn't make a difference.) Display specification abbreviations can be much more concise than ordinary display specifications, which contain at least a fieldname and often other information to boot. [[[How to define display specification abbreviations.]]] [[[Poorly-named variable dbf-fieldabbrevs controls this; it isn't getting set anywhere, though.]]]  File: database.info, Node: Customization, Next: Database representation, Prev: How information is displayed, Up: Top Customization ************* * Menu: * Auxiliary files:: Auxiliary and format files * Hooks and customization functions:: Hooks and customization functions * Local variables:: Local variables * Global variables:: Global variables  File: database.info, Node: Auxiliary files, Next: Hooks and customization functions, Up: Customization Auxiliary and format files ========================== A database designer can customize a database by providing code to be executed when the database is read in (*note Reading from disk::.). The optional auxiliary file usually contains the code specific to a particular database, but the format file, which specifies the on-screen arrangement of fields of a record, can also contain such code. Since the auxiliary file is read after the format file has been found but before it has been parsed, neither file can specify the other. The format file can, however, load arbitrary files, which is nearly as good as being able to specify an auxiliary file. The auxiliary file can be specified in the `aux-file' database slot; if it isn't, EDB looks for a file with the same name as the database file, but ending with one of the suffixes in `db-aux-file-suffixes'. `db-aux-file-suffixes' List of auxiliary file suffixes; the basename is that of the database file. The suffixes are tried in order; the default is (".dba" ".aux" "a"). The . that may precede the extension must be specified explicitly. `db-aux-file-path' List of directories (strings) to search, in order, for auxiliary files not found in the directory with their associated databases. The auxiliary file is evaluated in the data display buffer and so can set variables local to that buffer, such as hooks (*note Hooks and customization functions::.). The database itself can be manipulated via the dynamic variable `database' or the buffer-local variable `dbc-database'. For instance, auxiliary files often set the `print-name' slot of their associated databases. Code in an auxiliary file should be specific to the particular database; more general code is best placed in a separate file which is `load'ed (or, better, `require'd) by the auxiliary file. For instance, if you want to permit EDB to manipulate files of type Foo, you should put all Emacs Lisp code that applies to every Foo file in one file (`db-foo.el', say), and then put `(require 'db-foo)' in the auxiliary file associated with a particular Foo file. (Alternately, you may autoload a function that will be called in the auxiliary file; function `db-tagged-setup' is autoloaded from `db-tagged.el' in this manner.) Either technique keeps auxiliary files simple and small and makes Foo-specific code easier to debug, byte-compile, and load only once per session. These advantages easily outweigh the introduction of an extra file. Since the format file has not yet been interpreted, the auxiliary file could even change the contents of the buffer (and so the apparent contents of the format file); such extreme trickiness is only called for in special circumstances. The format file can contain Emacs Lisp code in its "Local Variables" section; that code can do anything that the code in the auxiliary file can do. If the format file is not named explicitly in the database (in the `default-format-file' slot), then function `db-file->format-file' tries to find one based on the database file name and the suffixes in `db-format-file-suffixes'; if that doesn't work either, the user is prompted for a display format to use. `db-format-file-suffixes' List of format file suffixes; the basename is that of the database file. The suffixes are tried in order; the default is (".dbf" ".fmt" "f"). The . that may precede the extension must be specified explicitly. `db-format-file-path' List of directories (strings) to search, in order, for format files not found in the directory with their associated databases. Code in the format file is useful for customizations specific to a particular format (such as setting variables which are local to the data display buffer); they can also be used for database-specific customizations if the database designer is sure that the file will always be the primary (first-selected) format for the database.  File: database.info, Node: Hooks and customization functions, Next: Local variables, Prev: Auxiliary files, Up: Customization Hooks and customization functions ================================= Hooks are variables whose values are "hook functions" (or lists of hook functions) which are called at particular times, such as when EDB has finished loading (to permit the user to load customization code) or when a value has just been changed. Since hook functions can contain arbitrary code, they permit very powerful customizations. Customization functions, like hooks, can call arbitrary code, but are single functions, never lists. Sometimes "hook" is used to mean either a hook or a customization function. The following sections describe EDB's hooks and customization functions. Many of these hooks are change hooks, which permit a function (or functions) to be run whenever a value changes. These change hooks may be divided into two basic types: format change hooks and recordfieldspec change hooks. The former are associated with a particular display format and are invoked when the value in a particular field, or in any field, changes. The latter (which are not yet implemented) are associated with a recordfieldspec and are invoked whenever a database record slot of a particular type is changed. * Menu: * Load and read hooks:: Load and read hooks * Database minor mode hooks:: Database minor mode hooks * Record display hooks:: Record display hooks * Edit mode hooks:: Edit mode hooks * Display format change hooks:: Display format change hooks * Recordfieldspec change hooks:: Recordfieldspec change hooks  File: database.info, Node: Load and read hooks, Next: Database minor mode hooks, Up: Hooks and customization functions Load and read hooks ------------------- After EDB has finished loading, the following hook is run. This permits user customizations to be loaded automatically when EDB is (rather than being loaded unconditionally in the `.emacs' file, for instance), and permits users to change the definitions of functions defined by EDB, if desired. `db-load-hooks' Function or list of functions run after loading EDB. You can use this to customize key bindings or load extensions. The following two hooks are useful for causing database values seen by EDB to be different than those in the database file. The first can be used to modify the database file before it is read in; the second can be used to modify the database after it has been read in but before the user has had a chance to see it. `db-before-read-hooks' Function or list of functions run immediately before a database is first read but after all local variables are set. The hooks are run in the data display buffer with variable database bound. Variable db-buffer is bound to a buffer containing the database file. This is a global variable. If you set it to be specific to a particular database (for instance, in the format or auxiliary file), then consider having its last action be to reset the variable to `nil'. `db-after-read-hooks' Function or list of functions run after a database is completely read. The hooks are run in the data display buffer with variable database bound. For databases with nonregular formats, you might put a call to `database-stored->actual' here, for instance. This is a global variable. If you set it to be specific to a particular database (for instance, in the format or auxiliary file), then consider having its last action be to reset the variable to `nil'.  File: database.info, Node: Database minor mode hooks, Next: Record display hooks, Prev: Load and read hooks, Up: Hooks and customization functions Database minor mode hooks ------------------------- EDB provides hooks that are run whenever the data display buffer is switched between view mode and edit mode and which are run when a summary buffer is created. `db-view-mode-hooks' Function or list of functions called when database view mode is entered. `db-edit-mode-hooks' Function or list of functions called when database edit mode is entered. `database-summary-mode-hooks' Function or list of functions run when switching to database summary mode.  File: database.info, Node: Record display hooks, Next: Edit mode hooks, Prev: Database minor mode hooks, Up: Hooks and customization functions Record display hooks -------------------- The following function is run by the `display-record' function, which places a record's values in a data display buffer, each time a record is about to be displayed. `dbf-before-display-record-function' A function called before a record is displayed by `display-record'. The function should take one argument, the record. This is a good place to put calls to `db-alternate-format'. Depending on your function's implementation, however, you may silently override any user calls to that function. Here is an example of how you might use this: (defun set-format-from-data (record) (if (< 0 (record-field record 'net-profit dbc-database)) (db-alternate-format "loss format" "~/acct/db/loss.fmt") (db-alternate-format "profit format" "~/acct/db/profit.fmt"))) (setq dbf-before-display-record-function 'set-format-from-data) This uses two different display formats, depending on the value of one field of a record. As the user moves from record to record in the database, each one is shown using the appropriate display format. A preferable implementation omits the filenames from the calls to `db-alternate-format' and instead uses, in the format or auxiliary file, (setq dbf-alternate-format-names '(("loss format" . "~/acct/db/loss.fmt") ("profit format" . "~/acct/db/profit.fmt"))) See the example file `arb-demo.dba' for an example of this. `dbf-alternate-format-names' need not specify the full pathnames if the format files are located in the same directory as the database or if `"~/acct/db"' is placed in `db-format-file-path'. It would also be profitable to set `dbf-format-name' to whichever the first format was (this could be done in the format file's "Local Variables" section so that the first-selected buffer wouldn't get read in twice (once when the database was read in and once when `display-record' was first called). Finally, the database designer would probably arrange for there to be a change hook on the net-profit field so that when its value changed, the record could be redisplayed in the appropriate format automatically.  File: database.info, Node: Edit mode hooks, Next: Display format change hooks, Prev: Record display hooks, Up: Hooks and customization functions Edit mode hooks --------------- This function is called whenever the user enters a field to edit it, which provides an easy way to customize the behavior of particular format fields. `dbf-enter-field-function' A function called whenever a display field is entered. The function takes the displayspec index as an argument, which is guaranteed to be `dbf-this-field-index'. It is sometimes advantageous to have a particular action happen only once per edit of a record. For instance, when a record's address, city, state, or zip-code fields are edited, we might like to copy all the values to the old-address, old-city, old-state, and old-zip-code fields. We only want this to happen once, however: if the user edits first the address, then the city, we don't want to repeat the process, because then the old-address field would get written over by the new value of the address field. One way to prevent this from happening more than once is to set a variable when the copying is done, and then don't do the copying if that variable is set. The variable would be reset whenever a new record was edited. The following variable, which contains a list of other variables to reset each time database edit mode is entered, can accomplish just what is desired, when combined with a judicious use of change hooks. `dbf-reset-on-edit-list' An alist of (variable-name . default-value) pairs. Every time Edit Mode is entered, these buffer-local variables are reset to their default values. This is good for making sure that something only happens once each time a record is edited.  File: database.info, Node: Display format change hooks, Next: Recordfieldspec change hooks, Prev: Edit mode hooks, Up: Hooks and customization functions Display format change hooks --------------------------- The following hook is run whenever a new record is created. `db-new-record-function' Function called on empty records before they're inserted in the database. Takes two arguments, the record and the database. A typical use is to set default information or add a timestamp. For instance: (defun set-update-date (record database) "Provide defaults for new records in the database." (record-set-field new-rec 'updatedate (parse-date-string (current-date)) database)) (setq db-new-record-function 'set-update-date) The display format change hooks are called when a user changes a record field value. There are separate change hooks that run the first time any field is modified, whenever any field is modified, and whenever a particular field is modified. They run in the order `dbf-first-change-function', `dbf-every-change-function', and finally one of the elements of `dbf-change-functions'. Each change hook is either `nil' or a function of three variables: the fieldname of the just-modified field (a symbol) and the pre- and post-modification field values. The function should return a boolean which determines whether the entire record should be redisplayed; it is useful to return `t' if the change hook modifies fields other than that named by its first argument, and `nil' otherwise. (This result is `or'ed into `dbf-redisplay-entire-record-p', which controls whether the record should be completely redisplayed after a field modification is done, and which may be set directly by the adventurous.) `dbf-first-change-function' A function called the first time a record field is modified, or `nil'. The function takes the fieldname and the old and new values as arguments, and returns `t' if the record should be redisplayed. Here is an example of code to update the last modification field of a record, assuming its type is date: (defun update-last-modified-date (fieldname oldvalue newvalue) "Put the current date in this record's `last modified' field." (dbf-this-record-set-field 'last-modified (parse-date-string (current-date)))) (setq dbf-first-change-function 'update-last-modified-date) `dbf-every-change-function' A function called whenever a record field is modified, or `nil'. The function takes the fieldname and the old and new values as arguments, and returns `t' if the record should be redisplayed. `dbf-change-functions' A vector of one function (or `nil') per record field (not display field). The functions take the fieldname and the old and new values as arguments, and return `t' if the record should be redisplayed. Use `dbf-set-change-function' to set the fields of this vector. `dbf-set-change-function' Set the change function for FIELDNAME to FUNCTION in the current database. FUNCTION should take the fieldname and the old and new values as arguments, and return `t' if the record should be redisplayed. It is easy to make a field's value dependent on that of another field. For instance, suppose a salesman's commission should be 10% of the selling price of an item, and both fields are of type number. The database designer might choose to make the commission field unreachable (*note Display specification optional parameters::.) and compute it whenever the selling price field varies. The latter operation could be done as follows: (defun set-commission-from-selling-price (fieldname oldvalue newvalue) ;; If we used (dbf-displayed-record-field 'selling-price) for newvalue, this ;; would work even if not called as a change function for selling-price. (dbf-displayed-record-set-field 'commission (/ newvalue 10))) (dbf-set-change-function 'selling-price 'set-commission-from-selling-price) The user may modify records explicitly by calling `dbf-displayed-record-set-field' (*note Manipulating records::.); when that is done, the following hook is invoked. It is different from the above functions in that they are called when the user edits a field, while it is called when Emacs Lisp code modifies a field (usually as a result of some user action). `dbf-set-this-record-modified-function' A function called every time the working copy `dbf-this-record' is created by `dbf-set-this-record-modified-p'. The function takes no arguments and its return value is ignored. It is called after `dbf-this-record-original' is copied to `dbf-this-record' and after `dbf-this-record-modified-p' is set to `t'. Another function is invoked when changes to a record are committed--that is, when changes to the record which is being displayed are copied back into its original in the database. `dbf-after-record-change-function' Function called whenever changes to a record are recorded semi-permanently by `dbf-process-current-record-maybe'. For convenience, the function takes the record as an argument, which is guaranteed to be `dbf-this-record'. Its return value is ignored.  File: database.info, Node: Recordfieldspec change hooks, Prev: Display format change hooks, Up: Hooks and customization functions Recordfieldspec change hooks ---------------------------- Recordfieldspec change hooks are not yet implemented.