6.12 STD:Read Formatted File

This module provides sophisticated control for reading formatted files into Bunao arrays.

Here is the STD:Read Formatted File interface, configured with an example:

The file to be read should be logically divided into consecutive groups. A group is a simple database consisting of some number of records, each of which has the same number of fields.

File: the name of the file to read. Here, it is reading from `myfile'.

Use the Stop radio buttons to determine the number of records to read.

End of File. Select this if the file consists of only one block and is to be read until end of file.

Grps of Flds;Recs per Fld. (Default) Use this option for all other cases. This entry field takes two lists of numbers, separated by a semicolon, `;'. The first part is a comma separated list of the number of groups of fields. The second part is a comma separated list of the number of records per field. Here, the value `3,2,2;5,2,3' implies that there are three groups: the first group has five records, each of which has three fields (ie, it has values that will fill five elements each of three arrays). Similarly, the second group has 2 records of 2 fields, and the final group has 3 records of 2 fields each.

As a special case, if this entry has only a single number, then this is the number of records for all arrays to read in.

(Start) Index. Specifies index at which the destination array should be filled. This entry may be left blank, in which case all arrays are filled from index 1. If not left blank, it must be a comma separated list that specifies the start index for each group. Here, the index is blank.

Note that if specified, the Index iist must be exactly the same length as each part of the Grps of Flds;Recs per Fld field.

The Fields list control specifies what the destination arrays are for each field, and how to determine the end of a field.

Array: the name of the destination array for this field. Here 7 arrays are listed: `A1, A2, A3, B1, B2, C1, C2'. Note that the number of arrays must exactly equal the sum of the groups-of-fields list (first half of Grps of Flds;Recs per Fld). Here, 3+2+2 does equal 7.

Field End: whether the field length is a fixed number of lines or if it is marked by a delimiter of some kind. The Field End control is a menubutton that displays `Delimiter' or `Lines'; clicking the button displays a small menu to change from one to the other. Note that the button is a separate control for each field line, so a single file can have both kinds of fields, if necessary. Here, all field lengths are given as lines.

The rest of the listcontrol changes depending on what kind of Field End is selected:

Field by lines(default):

Lines. The entry field just after the menubutton is the number of lines per field, by default, 1. Here, all fields are 1 line long.

Caret Extender. (Unchecked by default) If checked, the system will enable an old Listmaker feature in which a caret character `^' at the end of a line escapes the following newline, effectively extending the current line by the contents of the next one. Here, none of the fields have the caret extender feature enabled.

Field by delimeter:

Delimeter. The entry field just after the menubutton is the field delimeter character. Valid delimeters are any ASCII character, also `\n' for newline, `\t' for tab. (Actually any Tcl character constant is valid).

Use the radiobuttons that follow to specify the delimiter's position.

Anywhere. (Default) The delimeter can be anywhere on the line.

Line by Itself. The delimeter must be on a line by itself.

If `myfile' looks like this:

a1(1) a2(1) a3(1) a1(2) a2(2) a3(2) a1(3) a2(3) a3(3) a1(4) a2(4) a3(4) a1(5) a2(5) a3(5) b1(1) b2(1) b1(2) b2(2) c1(1) c2(1) c3(1) c1(2) c2(2) c3(2) c1(3) c2(3) c3(3)

Then this instance of the STD:Read Formatted File module causes the following assignments to occur:

A1(1) = a1(1) A2(1) = a2(1) A3(1) = a3(1) A1(2) = a1(2) A2(2) = a2(2) A3(2) = a3(2) A1(3) = a1(3) A2(3) = a2(3) A3(3) = a3(3) A1(4) = a1(4) A2(4) = a2(4) A3(4) = a3(4) A1(5) = a1(5) A2(5) = a2(5) A3(5) = a3(5) B1(1) = b1(1) B2(1) = b2(1) B1(2) = b1(2) B2(2) = b2(2) C1(1) = c1(1) C2(1) = c2(1) C3(1) = c3(1) C1(2) = c1(2) C2(2) = c2(2) C3(2) = c3(2) C1(3) = c1(3) C2(3) = c2(3) C3(3) = c3(3)

If the input file had instead looked like this:

a1(1):a2(1):a3(1) a1(2):a2(2):a3(2) a1(3):a2(3):a3(3) a1(4):a2(4):a3(4) a1(5):a2(5):a3(5) b1(1)!b2(1) b1(2)!b2(2) c1(1)%c2(1)%c3(1) c1(2)%c2(2)%c3(2) c1(3)%c2(3)%c3(3)

then exactly the same assignments could be achieved by configuring the module like this: