InfoMagic Source Code 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / perl / scripts-osu / forms-1.0.shar.1 < prev next >

Wrap

Text File | 1992-04-13 | 21.4 KB | 591 lines

Newsgroups: comp.lang.perl Path: cis.ohio-state.edu!zaphod.mps.ohio-state.edu!qt.cs.utexas.edu!cs.utexas.edu!uunet!snorkelwacker.mit.edu!bloom-picayune.mit.edu!math.mit.edu!drw From: drw@kronecker.mit.edu (Dale R. Worley) Subject: Forms-oriented input system, documentation Message-ID: <DRW.92Apr14115354@kronecker.mit.edu> Sender: news@athena.mit.edu (News system) Nntp-Posting-Host: kronecker.mit.edu Organization: MIT Dept. of Tetrapilotomy, Cambridge, MA, USA Date: Tue, 14 Apr 1992 16:53:54 GMT Lines: 578 Forms system version 1.0 Design 1. Form A "form" consists of a sequence of "fields". Each field contains the information necessary to display and input one value. 2. Input commands At any time, form input is either editing the value of a particular field ("in a field"), or it is transitting between fields ("out of a field"). Entry into a field is done only when a command is executed which would change the value of the field; bringing the cursor to rest on a particular field is not sufficient to enter the field. Conversely, exiting a field is done only when some command is executed which would transit to another field, or exit the form entirely. However, exiting a field causes its value to be checked for validity, and if the validity check fails, the command that caused exiting of the field is not performed. The commands which are executed out of a field are: LFD accept contents of form (also C-j) C-c abort the form (exits the current field, if any, with C-y, and thus never fails) RET go to next field TAB go to previous field The commands which are executed in a field are: C-y restore previous value of the field and exit from field (bypasses validity check on previous value) C-v perform validity check on field C-v C-v exit from field, if it is valid C-u clear field C-k clear to end of field C-r clear to beginning of field C-a go to beginning of field C-e go to end of field C-b go back one character C-f go forward one character C-d delete next character DEL delete previous character (also C-h) The help commands are: C-p give help on current field C-p C-p show help screen describing all commands The help command (C-p) gives help on the field the cursor is in (whether or not it has been entered) by displaying its help_message attribute value in the field named MSG. However, if there is no such attribute or no field named MSG, or if there is no current field (because no visible field is writeable), it behaves like C-p C-p. In addition, all printing characters (SPC through ~) are commands to insert the character into the field value. Note, however, that the exact meaning of the in-field commands is determined by the field definition. The function keys can also be used as commands. See the section titled "function keys". 3. Attributes Each field is described by a set of "attributes". A form is stored in an associative array, and the attributes of the fields are stored in elements of the associative array: The value of the attribute $attr of field $field in form $form is stored in $form{$field,$attr}. Certain attributes are used by the forms system as a whole, and are stored with the null string as field name. The forms system reserves the package name "forms" for its data and subroutines. In addition, the package "forms_user" is used for storing code and data used by user-written routines. Names of the form "forms_generated_0000" are generated by the forms system, and so should be avoided, both in the two packages and as field names. 4. Values A value is represented in three distinct ways. While this may seem excessively complicated, it appears to be the only general framework that handles the myriad possible ways of displaying and inputting field values in a reasonably extensible way. The forms of a value are: Attribute "value": The actual value of the field, considered the output of the form when it is successfully executed, and the input, when the fields are pre-loaded before the form is executed. This value can be any Perl value that can be stored in a scalar. Attribute "displayed_value": The field, interpreted as a set of characters. For example, if the value is to be a number, the displayed value may be a character representation of the number. In addition, if, say, -1 is a special value of the number, the displayed value may code it as a particular character string, say, "Unknown". Attribute "displayed_field": The field, as displayed on the screen. This attribute is always exactly as long as the field length (attribute "field"length"), and is what is displayed on the screen. The translation between these forms is as follows: The translation value -> displayed_value is done by the function stored in attribute construct_displayed_value. It is called with two arguments, the field name and the value, and returns the displayed value. The translation displayed_value -> displayed_field is done by the function stored in attribute initialize_displayed_field. It is called with two arguments, the field name and the displayed value, and returns the displayed_field. In addition, it sets the variable $forms'cursor_location to the correct initial location of the cursor. (Cursor locations are relative to the beginning of the field, which is location 0.) This function is always called upon entry to a field, thus it may set additional attributes for the field for the user of the editing functions for the field. The displayed value and displayed field are both edited by the function stored in attributes "edit" and "insert". They are called with two arguments, the field name and the character typed. The character is either a printing character (in which case "insert" is called) or a non-printing character that is not one of the out-field input command characters listed above (in which case "edit" is called). The functions are responsible for updating the displayed value, the displayed field, and $forms'cursor_location appropriately, and must also report erroneous input characters. When the field is exited, two further attribute functions are called: The attribute "validate_displayed_value" is called with two arguments, the field name and the displayed value. It returns true if the value of the field is considered valid, and false if it is not. If it returns false, exit from the field is blocked. If it returns true, the function stored in attribute "interpret_displayed_value" is called with the field name and the displayed value as arguments. It returns the value. Since interpret_displayed_value is always called immediately after a successful call to validate_displayed_value, the latter may set global variables for the former. (This is the only circumstance where user functions can safely set its own global variables.) 5. Formatting attributes Attribute "label": The text of the label to be applied to the field. Attribute "label_location": Two numbers, seperated by commas, giving the location of the first character of the label. (Locations are always given in the order "row,column", both of which are 0-origin, with the 0 row being the top row and the 0 column the leftmost column.) Attribute "field_length": The number of characters to be allocated to the field. If this attribute is undefined or 0, the field has no input area, and only its label is relevant. Attribute "field_location": The location of the field. Attribute "read_only": If true, the field may not be entered in. The RET and TAB commands skip over the field. Attribute "invisible": If true, the field and its label are not displayed and cannot be altered. Attribute "initially_invisible": Set from attribute "invisible" when the form array is constructed, and used to restore attribute "invisible". Attribute "canonicalize": If true, when the field is exited, the value that was created is used to re-calculate the displayed value and the displayed field. Attribute "help_message": Displayed by the C-p command when the cursor is in the field. In addition, there are several attributes that apply to the form as a whole: Attribute "fields": A comma-separated list of the field names, in their natural order. A field's position in the natural order is determined by the location in which it was first given an attribute. RET cycles through the fields in the natural order, and TAB cycles through them in the reverse of the natural order. Attribute "initialize": A function to be executed once the form is set up but before any forms processing is performed. Attribute "finalize": A function to be executed when the form is accepted with LFD. If it returns false, the accept is rejected. Attribute "forms_version": This attribute declares that the form structure conforms to a particular version of the forms package, and all upward-compatible extensions of it. If provided, the forms system checks that it is capable of processing the given version of the forms structure. This document describes version 1.0. The field MSG is used to display help messages for fields (via the C-p command and the help_message attribute) and other messages (via the report_error and report_message functions). If it is not present, these messages are not displayed. 6. Manipulating other fields The edit_field function or other functions of a field may need to alter the value or visibility of a field. If it does so, it should call the appropriate function: $forms'changed_value($field) is used to signal that the value attribute of the given field has been changed, and the displayed value and displayed field should be updated. $forms'changed_visibility($field) is used to signal that the invisible attribute of the given field has been changed, and the screen should be updated appropriately. (It should not be called if the invisible attribute has not been changed, unless the user makes sure that no overlapping fields are visible.) The user is responsible for making sure that the fields that are visible at a given moment do not overlap. If a field that is being made invisible and a field that is being made visible overlap, the user should be sure to make the one field invisible before making the other field visible. 7. Input representation A form can be represented as a sequence of lines of text, or more exactly, as an array of strings. (Ending linefeeds on the strings are ignored.) The representation gives the values of the attributes in a straightforward way: field.attribute = value Whitespace around the field and attribute names and the "=" are ignored; leading and trailing whitespace around the value is also ignored. Lines that are entirely whitespace, or whose first non-whitespace character is "#" are ignored. Attributes of the form as a whole are set in the expected manner: .attribute = value A line of the form field: is used to provide a default field name for succeeding attributes. The default field name is invoked by omitting the "field." part of the attribute setting line: user_name: field_location = 2,5 field_length = 8 A line of the form : provides a generated field name as the default field name. It is most often used for fields that have labels but no value. Values are usually interpreted as character strings. However, certain values are interpreted differently: &name This value is interpreted as "*forms_user'name", which is the correct way to represent functions as attributes. &package'name This value is interpreted as "*package'name". @name This value is interpreted as "*forms'name". (More exactly, the three above forms are evaluated directly, after replacing the first character with "*". If the first character is "&", it is evaluated in package forms_user; if it is "@", it is evaluated in package forms. Thus, "&" is used for functions defined by the user, and "@" is used for functions supplied by forms. * expression This value is interpreted by evaluating "expression", in the package forms_user. "text" This value is interpreted as "text", allowing characters that would otherwise be interpreted specially. field.attribute = { text }; This value is used to construct a subroutine in the forms_user package. The value itself is interpreted as "*forms_user'<subroutine_name>". The text of the subroutine is terminated by a line consisting of "};", possibly with leading and trailing whitespace. Interspersed with the attribute values can be sets of lines with the format sub name { text }; These forms are used to define subroutines. They are evaluated in the forms_user package. In addition, there can be lines with the format * expression The expression is evaluated in the package forms_user. Note that "* expression" constructions and subroutines defined in the forms description are evaluated in the order that they are in the forms description, at the time that the representation is processed by &forms'process_representation. The input representation of a form is transformed into an array with the function: &forms'process_representation(*array, @representation) where the form attributes will be stored in the associative array %array, and the representation is taken from @representation. The function returns true if no error is found and false if an error was found. The error message is stored in $forms'error. The function can be used to process input representations from files: &forms'process_representation(*array, <FILE>); and from here-documents: &forms'process_representation(*array, split(/\n/, <<'EOF')) text... EOF If the input representation is in a file, a more convenient form can be used: &forms'process_representation_from_file(*array, $file_name, $inc) This function reads the representation from the given file and processes it. In addition, if $inc is true, @INC is searched for $file_name, just as require does. If the file does not exist, the function aborts execution. These functions set certain attributes in addition to those that are mentioned in the input representation: "initially_invisible" is set from "invisible", and "fields" is set to be the list of fields in the form. 8. Processing forms Several functions are used to process forms: &forms'clear_values(*array) This function clears (sets to undef) all of the value attributes of the given form. It is used to clear a form in preparation for further input. &forms'clear_values_and_redisplay This function is used during forms input to clear all of the value attributes and force redisplay of all the fields (via &forms'changed_value). &forms'reset_visibility(*array) This function sets the invisible attributes from the initially_invisible attributes. &forms'process_form(*array) This form displays the given form and gets the user's input. Initially displayed values are obtained from the value attributes of the form, and the returned values are returned in the value attributes. The function returns true if the form as accepted and false if it was aborted. During execution of the form, %forms'form is aliased to %array. &forms'process_form is not intended to be executed recursively. &forms'dump_form(*array, filehandle) Prints out all of the attributes in a form. If filehandle is omitted, STDOUT is used. 9. Service routines &forms'report_message(text) is used to display a message in the field named MSG (if there is one). &forms'report_error(text) is used to display an error message in the MSG field. (It performs a report_message and then rings the bell.) 10. Function keys The function keys can be used as commands if they are defined by a form. Function keys are typed as: ESC single optional 'O' or '[' zero or more characters in the range '!' to '?' one character '@' or greater (This should probably be changed to a more flexible system.) They are translated into function key identifications (F1 through F10) by the table %forms'function_key. The function key identifications for F1 to F9 are loaded from the 'k1' through 'k9' capabilities from the termcap entry, and the F10 identification is taken from the 'k;' capability (or if it is not present, the 'k0' capability). In addition, several standard function key codes are loaded: Key Sun Sun VT100 Manual typing Termcap F1 \e[224z \e[11~ \eOP \e1f \e1F k1 F2 \e[225z \e[12~ \eOQ \e2f \e2F k2 F3 \e[226z \e[13~ \eOR \e3f \e3F k3 F4 \e[227z \e[14~ \eOS \e4f \e4F k4 F5 \e[228z \e[15~ \e5f \e5F k5 F6 \e[229z \e[17~ \e6f \e6F k6 F7 \e[230z \e[18~ \e7f \e7F k7 F8 \e[231z \e[19~ \e8f \e8F k8 F9 \e[232z \e[20~ \e9f \e9F k9 F10 \e[-1z \e[21~ \e0f \e0F k; or k0 \e10f \e10F A function key is considered "local" if the cursor is sitting in a field and that field has an attribute "F1" (or whatever). A function key is considered "global" if it is not local and there is a global attribute "F1" (or whatever). Escape sequences that are neither local nor global produce an error message. If a local function key is given, the field is enterd (if it has not been) and the function named by the attribute is executed. If a global function key is given, the field is exited (if it has not been) and the function named by the attribute is executed. 11. Problem with curseperl Curseperl has an ugly problem. The following program does not do what is expected (clear the screen) when $ARGV[0] is true: $ENV{'TERM'} = 'vt100'; &initscr; if ($ARGV[0]) { &getcap('k1'); &getcap('k2'); &getcap('k3'); &getcap('k4'); } &clear; &refresh; &getch; (This is using BSD curseperl on a Sun4 with SunOS 4.1.1) getcap is just a wrapper for termcap's tgetstr, *using a fixed internal buffer to collect the results from tgetstr*. It appears that this internal buffer has a finite size, and each successive return value is written after the previous one, so if you do a few too many getcap's, you write off the end of the buffer... A solution which appears to work is to change the interface for &getcap to call tgetstr directly, but to supply a new buffer each time. The patch for this is follows. It is necessary to install this patch, because forms.pl uses getcap() when it is loaded. If this patch can't be installed, you have to comment out the calls to &'getcap in subroutine load_function_keys. This may disable the function keys defined in the termcap entry for the user's terminal. *** bsdcurses.mus.old Thu Apr 9 16:40:41 1992 --- bsdcurses.mus Thu Apr 9 16:41:18 1992 *************** *** 476,484 **** CASE int erasechar END ! CASE char* getcap ! I char* str ! END case US_getyx: if (items != 3) --- 476,493 ---- CASE int erasechar END ! case US_getcap: ! if (items != 1) ! fatal("Usage: &getcap($str)"); ! else { ! char* retval; ! char* str = (char*) str_get(st[1]); ! char output[50], *outputp = output; ! ! retval = tgetstr(str, &outputp); ! str_set(st[0], (char*) retval); ! } ! return sp; case US_getyx: if (items != 3) 12. Standard field types The forms system contains routines for inputting various standard field types. - Ordinary text fields Ordinary text fields can be implemented with the attributes: construct_displayed_value = @char_field initialize_displayed_field = @id_cursor_after validate_displayed_value = @true interpret_displayed_value = @trim_trailing_space insert = @text_insert edit = @text_edit When the field is entered, the cursor is placed after the first non-blank character of the value. When the field is exited, the contents of the field have trailing spaces removed, and the remainder is the field vbalue. - Hidden text fields Hidden text fields are just like ordinary text fields, except that the field value is not displayed -- the characters of the value (up to the last non-blank character) are displayed as periods ("."). Hidden text fields are good for inputting passwords and similar things. They can be implemented with the attributes: construct_displayed_value = @char_field initialize_displayed_field = @id_cursor_after_hidden validate_displayed_value = @true interpret_displayed_value = @trim_trailing_space insert = @text_insert_hidden edit = @text_edit_hidden - Enumerated fields Enumerated fields allow one of a set of values to be selected. Each value is represented by one of a set of "representations", which are what is displayed to the user and what the user types in the field to specify a value. The set of permissible values and their representations are specified by the attribute "translate_table", which is a list of items of the form "representation=value", separated by backslashes ("\"). The representations and values are searched for in translate_table, so they may not contain backslashes or equal signs. In addition, representations are recognized case-insensitively, while values are represented case-sensitively. When a value is translated to a representation, the first representation listed is chosen. A value that does not have a representation should not be present. A representation that does not have a value will be rejected as invalid. An example of an enumerated field with the translation table Value Representation 1 Yes (preferred representation) 1 Y 0 No (preferred representation) 0 N is constructed by: construct_displayed_value = @enum_field initialize_displayed_field = @id_cursor_after validate_displayed_value = @enum_validate interpret_displayed_value = @enum_interpret translate_table = Yes=1\Y=1\No=0\N=0\=0 insert = @text_insert edit = @text_edit canonicalize = 1 In this case, "canonicalize" is set, so that upon field exit the value is displayed in the preferred representation.