Previous

10.3.4. Format texts

{In formatted transput, each straightened value from a data list (cf. 10.3.3 ) is matched against a constituent picture of a format-text provided by the user. A picture specifies how a value is to be converted to or from a sequence of characters and prescribes the layout of those characters in the book. Features which may be specified include the number of digits, the position of the decimal point and of the sign, if any, suppression of zeroes and the insertion of arbitrary strings. For example, using the picture -d.3d " " 3d " " e z+d, the value 1234.567 would be transput as the string " 1.234 567io+3".

A "format" is a structured value (i.e., an internal object) of mode 'FORMAT', which mirrors the hierarchical structure of a format-text (which is an external object). In this section are given the syntax of format-texts and the semantics for obtaining their corresponding formats. The actual formatted transput is performed by the routines given in section 10.3.5 but, for convenience, a description of their operation is given here, in association with the corresponding syntax.}


10.3.4.1. Collections and pictures




10.3.4.1.1. Syntax {The following mode-declarations (taken from 10.3.5.a ) are reflected in the metaproduction rules A to K below.

A) MODE FORMAT = STRUCT(FLEX [1:0] PIECE {F}f);

B) MODE PIECE = STRUCT(INT cp, count, bp, FLEX [1: 0] COLLECTION c);

C) MODE COLLECTION =UNION(PICTURE, COLLITEM);

D) MODE COLLITEM = STRUCT(INSERTION i1, PROC INT rep, INT p, INSERTION i2);

E) MODE INSERTION = FLEX [1:0] STRUCT(PROC INT rep, UNION(STRING , CHAR) sa);

F) MODE PICTURE = STRUCT(UNION(PATTERN, CPATTERN, FPATTERN, GPATTERN, VOID) p, INSERTION i);

G) MODE PATTERN = STRUCT(INT type, FLEX [1: 0 ] FRAME frames);

H) MODE FRAME = STRUCT(INSERTION i, PROC INT rep, BOOL supp, CHAR marker);

I) MODE CPATTERN = STRUCT(INSERTION i, INT type, FLEX [1:0] INSERTION c);

J) MODE FPATTERN = STRUCT(INSERTION i, PROC FORMAT pf);

K) MODE GPATTERN = STRUCT(INSERTION i, FLEX [1: 0] PROC INT spec); }

A) FORMAT :: structured with row of PIECE field letter aleph mode.

B) PIECE :: structured with integral field letter c letter p integral field letter c letter o letter u letter n letter t integral field letter b letter p row of COLLECTION field letter c mode.

C) COLLECTION :: union of PICTURE COLLITEM mode.

D) COLLITEM :: structured with INSERTION field letter i digit one procedure yielding integral field letter r letter e letter p integral field letter p INSERTION field letter i digit two mode.

E) INSERTION :: row of structured with procedure yielding integral field letter r letter e letter p union of row of character character mode field letter s letter a mode.

F) PICTURE :: structured with union of PATTERN CPATTERN FPATTERN GPATTERN void mode field letter p INSERTION field letter i mode.

G) PATTERN :: structured with integral field letter t letter y letter p letter e row of FRAME field letter f letter r letter a letter m letter e letter s mode.

H) FRAME :: structured with INSERTION field letter i procedure yielding integral field letter r letter e letter p boolean field letter s letter u letter p letter p character field letter m letter a letter r letter k letter e letter r mode.

I) CPATTERN :: structured with INSERTION field letter i integral field letter t letter y letter p letter e row of INSERTION field letter c mode.

J) FPATTERN :: structured with INSERTION field letter i procedure yielding FIVMAT field letter p letter f mode.

K) GPATTERN :: structured with INSERTION field letter i row of procedure yielding integral field letter s letter p letter e letter c mode.

L) FIVMAT :: mui definition of structured with row of structured with integral field letter c letter p integral field letter c letter o letter u letter n letter t integral field letter b letter p row of union of structured with union of PATTERN CPATTERN structured with INSERTION field letter i procedure yielding mui application field letter p letter f mode GPATTERN void mode field letter p INSERTION field letter i mode COLLITEM mode field letter c mode field letter aleph mode. {'FIVMAT' is equivalent {2.1.1.2.a } to 'FORMAT'.}

M) MARK :: sign ; point ; exponent ; complex ; boolean.

N) COMARK :: zero ; digit ; character.

O) UNSUPPRESSETY :: unsuppressible ; EMPTY.

P) TYPE :: integral ; real ; boolean ; complex ; string ; bits ; integral choice ; boolean choice ; format ; general.

a) FORMAT NEST format text{5D } : formatter{94f } token, NEST collection{b} list, formatter{94f } token.

b) NEST collection{a,b} : pragment{92a } sequence option, NEST picture{c}; pragment{92a } sequence option, NEST insertion{d}, NEST replicator{g}, NEST collection{b} list brief pack, pragment{92a } sequence option, NEST insertion{d}.

c) NEST picture{b} : NEST TYPE pattern{A342a ,A343a,A344a,A345a,A346a,A347a,A348a,b,A349a,A34Aa} option, NEST insertion{d}.

d) NEST insertion{b,c,j,k,A347b ,A343a,b,A349a,A34Aa} : NEST literal{i} option, NEST alignment{e} sequence option.

e) NEST alignment{d} : NEST replicator{g}, alignment code{f}, NEST literal{i} option.

f) alignment code{e} : letter k{94a } symbol ; letter x{94a } symbol ; letter y{94a} symbol ; letter l{94a } symbol ; letter p{94a} symbol ; letter q{94a } symbol.

g) NEST replicator{b,e,i,k} : NEST unsuppressible replicator{h} option.

h) NEST unsuppressible replicator{g,i} : fixed point numeral{811b } ; letter n{94a} symbol, meek integral NEST ENCLOSED clause{31a ,34a,-}, pragment{92a } sequence option.

i) NEST UNSUPPRESSETY literal{d,e,i,A348c } : NEST UNSUPPRESSETY replicator{g,h}, strong row of character NEST denoter{80a } coercee{61a} , NEST unsuppressible literal{i} option.

j) NEST UNSUPPRESSETY MARK frame{A342c ,A343b,c,A344a,A345a} : NEST insertion{d}, UNSUPPRESSETY suppression{l}, MARK marker{A342e ,A343d,e,A344b,A345b} .

k) NEST UNSUPPRESSETY COMARK frame{A342b,c ,A346a} : NEST insertion{d}, NEST replicator{g}, UNSUPPRESSETY suppression{l}, COMARK marker{A342d,f ,A346b} .

l) UNSUPPRESSETY suppression{j,k,A347b } : where (UNSUPPRESSETY) is (unsuppressible), EMPTY ; where (UNSUPPRESSETY) is (EMPTY), letter s{94a } symbol option.

m) *frame : NEST UNSUPPRESSETY MARK frame{j}; NEST UNSUPPRESSETY COMARK frame{k}; NEST RADIX frame{A347b } .

n) *marker : MARK marker{A342e ,A343d,e,A344b,A345b} ; COMARK marker{A342d,f ,A346b} ; radix marker{A347c } .

o) *pattern : NEST TYPE pattern{A342a ,A343a,A344a,A345a,A346a,A347a,A348a,h,A349a,A34Aa} . {Examples:

}

a)
p "table of"x 10a,l n (lim-1)("x = " 12z+d 2x, +.12de+2d 3q"+j*"3" "si+.10de+2d l)p
b)
p"table of"x10a ·l n (lim - 1)("x=" 12z+d 2x, +.12de+2d 3q"+j*"3" "si+.10de+2d l)p
c)
120k c ("mon", "tues", "wednes", "thurs", "fri", "satur", "sun") "day"
d)
p"table of"x
e)
p"table of"
h)
10 ·n(lim -1)
i)
"+j*"3" "
j)
si
k)
"x="12z
l)
s
{The positions where pragments {9.2.1.a } may occur in format-texts are restricted. In general (as elsewhere in the language), a pragment may not occur hetween two DIGIT- or LETTER-symbols.}

{

aa) For formatted output, putf {10.3.5.1.a } and printf (or writef) {10.5.1.f } may be used and, for formatted input, getf {10.3.5.2.a } and readf {10.5.1.g }. Each element in the data list (cf. 10.3.3 ) is either a format to be associated with the file or a value to be transput (thus a format may be included in the data list immediately before the values to be transput using that format).

bb) During a call of putf or getf transput proceeds as follows: For each element of the data list, considered in turn,

If it is a format,
thenit is made to be the current format of the file by associate format {10.3.5.k } :
otherwise, the element is straightened {10.3.2.3.c } and each element of the resulting multiple value is output {hh } or input {ii } using the next "picture" {cc, gg } from the current format.

cc) A "picture" is the yield of a picture. It is composed or a "pattern"of some specific 'TYPE' (according to the syntax of the TYPE-pattern of that picture), followed by an "insertion" {ee }. Patterns, apart from 'choice', 'format' and 'general' patterns, are composed of "frames", possibly "suppressed", each of which has an insertion, a "replicator" {dd }, and a "marker" to indicate whether it is a "d", "z", "i" etc. frame. The frames of each pattern may be grouped into "sign moulds", "integral moulds", etc., according to the syntax of the corresponding pattern.

dd) A "replicator" is a routine, returning an integer, constructed from a replicator {10.3.4.1.2.c }, For example, the replicator 10 gives rise to a routine composed from INT: 10; moreover, n (lim - 1) is a "dynamic" replicator and gives rise to INT: (lim - 1). Note that the scope of a replicator restricts the scope of any format containing it, and thus it may be necessary to take a local copy of a file before associating a format with it (see, e.g.. 11.D ). A replicator which returns a negative value is treated as if it had returned zero ("k" alignments apart).

When a picture is "staticized", all of its replicators and other routines (including those contained in its insertions) are called collaterally. A staticized pattern may be said to "control" a string, and there is then a correspondence between the frames of that pattern, taken in order, and the characters of the string. Each frame controls n consecutive characters of the string, where n is 0 for an "r" frame and, otherwise, is the integer returned by the replicator of the frame (which is always 1 for a "+", "-", ".", "e", "i" or "b" frame). Each controlled character must be one of a limited set appropriate to that frame.

ee) An "insertion", which is the yield of an insertion {10.3.4.1.2.d }, is a sequence of replicated "alignments" and strings: an insertion containing no alignments is termed a "literal". An insertion is "performed" by performing its alignments {ff } and on output (input) writing ("expecting" {ll } ) each character of its replicated strings (a string is replicated by repeating it the number of times returned by its replicator).

ff) An "alignment" is the character yielded by an alignment-code {10.3.4.1.2.d }. An alignment which has been replicated n times is performed as follows:

· "k" causes set char number to be called, with n as its second parameter:

· "x" causes space to be called n times:

· "y" causes backspace to be called n times:

· "l" causes newline to be called n times:

· "p" causes newpage to be called n times;

· "q" on output (input) causes the character blank to be written (expected) n times.

gg) A format may consist of a sequence of pictures, each of which is selected in turn by get next picture {10.3.5.b }. In addition, a set of pictures may be grouped together to form a replicated "collection" (which may contain further such collections). When the last picture in a collection has been selected, its first picture is selected again, and so on until the whole collection has been repeated n times, where n is the integer returned by its replicator. A collection may be provided with two insertions, the first to be performed before the collection, the second afterwards.

A format may also invoke other formats by means of 'format' patterns {10.3.4.9.1 }.

When a format has been exhausted, the event routine corresponding to on format end is called; if this returns false, the format is repeated; otherwise, if the event routine has failed to provide a new format, undefined is called.

hh) A value V is output, using a picture P, as follows:

If the pattern Q of P is a 'choice' or 'general' pattern,
then V is output using P (See 10.3.4.3.1.aa,dd , 10.3.4.10.1.aa );
otherwise. V is output as follows:

ii) A value is input to a name N, using a picture P, as follows:

If the pattern Q of P is a 'choice' or 'general' pattern,
thena value is input to N using P (see 10.3.4.8.1.bb,ee , 10.3.4.10.1.bb );
otherwise,

jj) A string is "edited", using a pattern P, as follows: In each part of the string controlled by a sign mould,

· if the first character of the string (which indicates the sign) is "+" and the sign mould contains a "-" frame, then that character is replaced by " "

· the first character (i.e., the sign) is shifted to the right across all leading zeroes in this part of the string and these zeroes are replaced by spaces (for example, using the sign mould 4z+, the string "+0003" becomes "+ 3" In each part of the string controlled by an integral mould,

· zeroes controlled by "z" frames are replaced by spaces as follows:

· between the start of the string and the first nonzero digit;

· between each "d", "e" or "i" frame and the next nonzero digit; (for example, using the pattern zdzd2d the string "180168" becomes "18 168";) For each frame F of P,

· the insertion of F is performed.

· if F is not suppressed, the characters controlled by F are written; (for example, the string "+0003.5", when edited using the pattern 4z+ s "," d, causes the string " +3,5" to be written and the string "180186", using the pattern zd"-"zd"-19"2d, gives rise to "18- 1-1968").

kk) A string is "indited", using a pattern P, as follows: For each frame F of P,

· the insertion of F is performed. For each element of the string controlled by F, a character is obtained as follows: If F is contained in a sign mould, then

· if a sign has been found, a digit is expected, with "0" as suggestion;

· otherwise, either a "+" or a "-" is expected, with "0" as suggestion; and, in addition, if the sign mould contains a frame, then a space precding the first digit will be accepted as the sign (and replaced by "+"); otherwise, if F is contained in an integral mould, then If F is suppressed, then :"0" is supplied, otherwise:

Case A: F is a "d" frame:


· a digit is expected, with "0" as suggestion;

Case B: if F is "z" frame:


· a digit or space is expected, with "0" as suggestion, but a space is only acceptable as follows:

· between the start of the string and the first nonzero digit;

· between each "d", "e" or "i" frame and the next nonzero digit;

· such spaces are replaced by zeroes. otherwise, if F is an "a" frame, then if F not suppressed, a character is read and supplied; otherwise " " is supplied; otherwise, if F is not suppressed, then if F is a "." ("c", "i", "b") frame, a "." ("10" or "." or "e", "^" or "i", flip or flop) is expected, with "." ("10", "^", flop) as suggestion; otherwise, if F is a suppressed "." frame, the character "." ("10", "^") is supplied.

ll) A member of a set of characters S is "expected", with the character C as suggestion, as follows:

· a character is read;

If that character is one of the expected characters (i.e., a member of S),

then that character is supplied;

otherwise, the event routine corresponding to on char error is called, with C as suggestion; if this returns true and C, as possibly replaced, is one of the expected characters, then that character is supplied; otherwise, undefined is called. }
 
Next