PROCEDURE WriteF( f : File; fmtStr : ARRAY OF CHAR; items : ARGLIST OF <Type> ); (* Writes the textual representation of one or more data items to output stream f. The output format is determined by fmtStr. *)
A WriteF
procedure is required for type BYTE
. If the value of SYSTEM.BITSPERBYTE
is other than eight BYTE
and ADDRESS
may possibly share a single implementation.
The syntax of a format string for byte output is as follows:
ByteFmtStr : '"' noFormatting? numeralOptions? alignOptions? columnOptions? '"' ; noFormatting : 'N' ; numeralOptions : 'b' | 'x' | "d" ; alignOptions : alignment fieldWidth ; alignment : '<' | '>' ; fieldWidth : digit digit? digit? ; columnOptions : concatenator | columns ; concatenator : '~' ; columns : '!" digit? digit? ;
The meaning of formatting options is as follows:'N'
- normalised, base-16, all digits'b'
- numerals are written as base-2 literals'x'
- numerals are written as base-16 literals'd'
- numerals are written in decimal format'<'
- values are left aligned, option requires field width'>'
- values are right aligned, option requires field width'~'
- concatenate values to their respective predecessor without separators'!'
- values are written in columns, option may be followed by the number of columns
byte1 := CAST (BYTE, 0); byte2 := CAST (BYTE, 123); ByteIO.WriteF(f, "N", byte1, byte2); => 00, 7B BYTE.WriteF( f, "b", byte1, byte2 ); => 0b0, 0b01111001 BYTE.WriteF( f, "x", byte1, byte2 ); => 0x0, 0x7B
For word and address output one WriteF
procedure each is required for types WORD
and ADDRESS
.
The syntax of a format string for word and address output is as follows:
wordOrAddrFmtStr : '"' noFormatting? numeralOptions? alignOptions? columnOptions? '"' ; noFormatting : 'N' ; numeralOptions : literalOptions | digit digit? digitGrouping? ; literalOptions : 'b' | 'x' | "d" ; digitGrouping : ( '_' | '.' | ':' ) digit digit? ; alignOptions : alignment fieldWidth ; alignment : '<' | '>' ; fieldWidth : digit digit? digit? ; columnOptions : concatenator | columns ; concatenator : '~' ; columns : '!" digit? digit? ;
The meaning of formatting options is as follows:'N'
- normalised, base-16, all digits'b'
- numerals are written as base-2 literals'x'
- numerals are written as base-16 literals'd'
- numerals are written in decimal format'_'
- numerals are written in whitespace separated groups, option requires number of digits per group'.'
- numerals are written in period separated groups, option requires number of digits per group':'
- numerals are written in colon separated groups, option requires number of digits per group'<'
- numerals are left aligned, option requires field width'>'
- numerals are right aligned, option requires field width'~'
- concatenate values to their respective predecessor without separators'!'
- values are written in columns, option may be followed by the number of columns
word1 := CAST (WORD, 0); word2 := CAST (WORD, 123); word3 := CAST (WORD, 65535); WordIO.Write3F( f, "N|\n", word1, word2, word3 ); (* first two in default array format *) WordIO.Write3F( f, "b|\n", word1, word2, word3 ); WordIO.Write3F( f, "x\n", word1, word2, word3 ); WordIO.Write3F( f, "d\n", word1, word2, word3 ); WordIO.Write3F( f, "_4\n", word1, word2, word3 ); => { 00000000, 0000007B, 0000FFFF } { 0b0, 0b00000000'00000000'00000000'01111011, 0b00000000'00000000'11111111'11111111 } 0x0, 0x0000007B, 0x0000FFFF 0, 123, 65535 0000 0000, 0000 007B, 0000 FFFF
For boolean value output one WriteF
procedure is required for type BOOLEAN
.
The syntax of a format string for character based output is as follows:
boolFmtStr : '"' noFormatting? boolOptions? alignOptions? columnOptions? '"' ; noFormatting : 'N' ; boolOptions : 'T' | 'Y' ; alignOptions : alignment fieldWidth ; alignment : '<' | '>' ; fieldWidth : digit digit? digit? ; columnOptions : concatenator | columns ; concatenator : '~' ; columns : '!" digit? digit? ;
The meaning of formatting options is as follows:'N'
- normalised, equivalent to "T"'T'
- true values are written as TRUE
, false values are written as FALSE
'Y'
- true values are written as YES
, false values are written as NO
'<'
- values are left aligned, option requires field width'>'
- values are right aligned, option requires field width'~'
- concatenate values to their respective predecessor without separators'!'
- values are written in columns, option may be followed by the number of columns
BooleanIO.WriteF( f, "T", TRUE, FALSE ); => TRUE, FALSE BooleanIO.WriteF( f, "Y", TRUE, FALSE ); => YES, NO
For bitset output one WriteF
procedure is required for type BITSET
.
The syntax of a format string for bitset output is as follows:
bitsetFmtStr : '"' noFormatting? bitsetOptions alignOptions? columnOptions? '"' ; noFormatting : 'N' ; bitsetOptions : setLiteral | groupedBinary? ; setLiteral : 'S' ; groupedBinary : ( '_' | '.' ) digit digit? ; alignOptions : alignment fieldWidth ; alignment : '<' | '>' ; fieldWidth : digit digit? digit? ; columnOptions : concatenator | columns ; concatenator : '~' ; columns : '!" digit? digit? ;
The meaning of formatting options is as follows:'N'
- normalised, equivalent to "S"'S'
- value is written as a Modula-2 bitset literal'_'
- value is written as a binary bit group separated by whitespace, requires number of bits per group'.'
- value is written as a binary bit group separated by periods, requires number of bits per group
The meaning of formatting options for the bitset taken as a whole is as follows:'<'
- values are left aligned, option requires field width'>'
- values are right aligned, option requires field width'~'
- concatenate values to their respective predecessor without separators'!'
- values are written in columns, option may be followed by the number of columns
BitsetIO.WriteF( f, "N", { } , { 2, 5, 7 } ); => { }, { 2, 5, 7 } BitsetIO.WriteF( f, "S", { } , { 2, 5, 7 } ); => { }, { 2, 5, 7 } BitsetIO.WriteF( f, "_4", { } , { 2, 5, 7 } ); (* assuming 8-bit bitset *) => { 0000 0000 }, { 0010 0101 }
For character based data output one WriteF
procedure is required for each of the pervasive types CHAR
, UNICHAR
and each of their composite types ARRAY
OF
CHAR
and ARRAY
OF
UNICHAR
.
The syntax of a format string for character based output is as follows:
charFmtStr : '"' noFormatting? literalOption? quotingOptions? alignOptions? columnOptions? '"' ; noFormatting : 'N' ; literalOption : 'u' ; quotingOptions : 'Q' | 'D' ; alignOptions : alignment fieldWidth ; alignment : '<' | '>' ; fieldWidth : digit digit? digit? ; columnOptions : concatenator | columns ; concatenator : '~' ; columns : '!" digit? digit? ;
The meaning of formatting options is as follows:'N'
- normalised, raw characters, no quoting'u'
- data items are written as character literals'Q'
- data items are enclosed in single quotation marks'D'
- data items are enclosed in double quotation marks'<'
- data items are left aligned, option requires field width'>'
- data items are right aligned, option requires field width'~'
- concatenate data items to their respective predecessor without separators'!'
- data items are written in columns, option may be followed by the number of columns
CharIO.WriteF( f, "~", "A", "B", "C", "D", "E" ); => ABCDE CharIO.WriteF( f, "N", "A", "B", "C", "D", "E" ); => A, B, C, D, E CharIO.WriteF( f, "Q", "A", "B", "C", "D", "E" ); => 'A', 'B', 'C', 'D', 'E' CharIO.WriteF ("u", "A"); => 0u41 ARRAYOFCHAR.WriteF( f, "N", "foo", "bar", "baz" ); => foo, bar, baz ARRAYOFCHAR.WriteF( f, "Q", "foo", "bar", "baz" ); => 'foo', 'bar', 'baz' ARRAYOFCHAR.WriteF( f, "<16!5", "ALIAS","AND","ARGLIST","ARRAY","BEGIN" "BLUEPRINT","BY","CASE","CONST","COPY" "DEFINITION","DIV","DO","ELSE","ELSIF" "END","EXIT","FOR","FROM","GENLIB" "IF","IMPLEMENTATION","IMPORT","IN","INDETERMINATE" "LITERAL","LOOP","MOD","MODULE","NEW" "NONE","NOT","OF","OPAQUE","OR" "POINTER","PROCEDURE","RECORD","REFERENTIAL","RELEASE" "REPEAT","RETAIN","RETURN","SET","THEN" "TO","TYPE","UNTIL","VAR","WHILE" ); => ALIAS AND ARGLIST ARRAY BEGIN BLUEPRINT BY CASE CONST COPY DEFINITION DIV DO ELSE ELSIF END EXIT FOR FROM GENLIB IF IMPLEMENTATION IMPORT IN INDETERMINATE LITERAL LOOP MOD MODULE NEW NONE NOT OF OPAQUE OR POINTER PROCEDURE RECORD REFERENTIAL RELEASE REPEAT RETAIN RETURN SET THEN TO TYPE UNTIL VAR WHILE
For whole number output one WriteF
procedure is required for each of the pervasive types OCTET
, CARDINAL
, INTEGER
, LONGCARD
, LONGINT
and any other user defined whole number type.
The syntax of a format string for whole number output is as follows:
wholeNumFmtStr : '"' noFormatting? numeralOptions alignOptions? columnOptions? '"' ; noFormatting : 'N' ; numeralOptions : base16Options | decimalOptions ; base16Options : ( 'b' | 'x' ) digit? digit? ; decimalOptions : sign? digitOptions? digitGrouping? suffix? ; digitOptions : fillChar? digit digit? ; sign : '+' | '-' ; fillChar : '*' | 'z' ; digitGrouping : '_' | ':' | ';' ; suffix : "'" printableCharacter+ "'" ; alignOptions : alignment fieldWidth ; alignment : '<' | '>' ; fieldWidth : digit digit? digit? ; columnOptions : concatenator | columns ; concatenator : '~' ; columns : '!" digit? digit? ;
The meaning of formatting options is as follows:'N'
- normalised, decimals, significant digits only'b'
- numerals are written as base-2 literals'x'
- numerals are written as base-16 literals'+'
- numerals are preceded by their sign or whitespace if their value is zero'-'
- numerals are preceded by their sign if negative, otherwise by whitespace'*'
- numerals are left filled with asterisks, option requires number of digits shown'z'
- numerals are left filled with zeroes, option requires number of digits shown'_'
- numerals are written with digits grouped into triads from right to left, separated by whitespace':'
- numerals are written with digits grouped into triads from right to left, separated by period';'
- numerals are written with digits grouped into triads from right to left, separated by comma'<'
- numerals are left aligned, option requires field width'>'
- numerals are right aligned, option requires field width'~'
- concatenate numerals to their respective predecessor without separators'!'
- numerals are written in columns, option may be followed by the number of columns
(* Base-16 literal format, no fill, no padding *) IntegerIO.WriteF( f, "x", 0, -123 ); => 0x0, 0xFFFFFF85 (* Base-16 literal format, no fill, no padding *) CardinalIO.WriteF( f, "x", 0, 123, 3456789 ); => 0x0, 0x7B, 0x34BF15 (* decimal format, force sign, no fill, no grouping no padding *) IntegerIO.WriteF( f, "+", 123, -3456789 ); => +123, -3456789 (* decimal format, force sign, no fill, show eight digits, no grouping, no padding *) IntegerIO.WriteF( f, "+8", 123, -3456789 ); => + 123, - 3456789 (* decimal format, force sign, zero fill, show eight digits, no grouping, no padding *) IntegerIO.WriteF( f, "+z8", 123, -3456789 ); => +00000123, -03456789 (* decimal format, force sign, asterisk fill, show eight digits, no grouping, no padding *) IntegerIO.WriteF( f, "+*8", 123, -3456789 ); => +*****123, -*3456789 (* decimal format, force sign, asterisk fill, show eight digits, digit grouping, no padding *) IntegerIO.WriteF( f, "+*8;", 123, -3456789 ); => +******123, -*3,456,789 (* decimal format, force sign, asterisk fill, show eight digits, digit grouping, padding to right align into a field of width 15 *) IntegerIO.WriteF( f, "+*8;>15", 123, -3456789 ); => +*******123, -*3,456,789 (* same as previous example but separate items with newline by specifying one column *) IntegerIO.WriteF( f, "+*8;>15!1", 123, -3456789 ); => +*******123 -*3,456,789 (* note that to end the entire output with a newline, one appends \n to the format string *)
For real number output one WriteF
procedure is required for each of the pervasive types REAL
, LONGREAL
, each of the standard library types BCD
, LONGBCD
and each user defined real number type.
The syntax of a format string for real number output is as follows:
realNumFmtStr : '"' noFormatting? realOptions? numeralOptions alignOptions? columnOptions? '"' ; noFormatting : 'N' ; realOptions : 'S' digit? digit?| 'F' | 'E' | '$' numeralOptions : sign? intDigitOptions? fracDigitOptions? digitGrouping? suffix?; intDigitOptions : fillChar? digit digit? ; fracDigitOptions : ( '.' | ',' ) digit digit? ; sign : '+' | '-' ; fillChar : '*' | 'z' | 's' ; digitGrouping : '_' | ';' ; suffix : "'" printableCharacter+ "'" ; alignOptions : alignment fieldWidth ; alignment : '<' | '>' ; fieldWidth : digit digit? digit? ; columnOptions : concatenator | columns ; concatenator : '~' ; columns : '!" digit? digit? ;
The meaning of formatting options is as follows:
'N'
- normalised, equivalent "S"'S'
- numerals are written in scientific notation "1.9e4"'E'
- numerals are written in engineering notation; exponent is always a multiple of three "19.0e3"'F'
- numerals are written in fixed point notation without an exponenet "19000"'$'
- numerals are written with the currency prefix and two digits after the decimal in fixed format "$19000.00"'+'
- numerals are preceded by their sign or whitespace if their value is zero'-'
- numerals are preceded by their sign if negative, otherwise by whitespace'*'
- numerals are left filled with asterisks, option requires number of integral digits shown's'
- numerals are left filled with spaces, option requires number of integral digits shown (default if it is omitted)'z'
- numerals are left filled with zeroes, option requires number of integral digits shown'.'
- numerals are written with a decimal point, option requires number of fractional digits shown','
- numerals are written with a decimal comma, option requires number of fractional digits shown'_'
- numerals are grouped into triads from right to left, separated by whitespace';'
- numerals are grouped into triads from right to left, separated by commas if decimal point, otherwise periods'<'
- numerals are left aligned, option requires field width'>'
- numerals are right aligned, option requires field width'''
- append characters enclosed in single quotes to each numeral'~'
- concatenate numerals to their respective predecessor without separators'!'
- numerals are written in columns, option may be followed by the number of columns
(* asterisk fill, fixed point eight integral digits, two fractional digits, single column comma digit grouping *) LongRealIO.WriteF( f, "F*8.2!1", 123.0, 123456789.0 ); =>*****123.00 123456789.00 (* asterisk fill, dollar format which is fixed point eight integral digits, two fractional digits, plus comma digit grouping, append " USD" *) LongRealIO.WriteF( f, "$*8;' USD'", 123.0, 123456789.0 ); => $*****123.00 USD, $123,456,789.00 USD (* zero fill, fixed point eight integral digits, three fractional digits, comma digit grouping *) LongRealIO.WriteF( f, "Fz8.3;", 0.0, 123.0, 123456789.0 ); => 00,000,000.000, 00,000,123.000, 123,456,789.000 (* asterisk fill, scientific notation eight integral digits, six fractional digits, space digit grouping *) LongRealIO.WriteF( f, "S*8.6_", 0.0, 123.0, 123456789.0 ); => *******0.000 000e+00, *******1.230 000e+002, *******1.234 568e+008 (* asterisk fill, engineering notation eight integral digits, two fractional digits, two columns, space digit grouping *) (* note no comma separators in column format *) LongRealIO.WriteF( f, "E*8.2_!2", 0.0, 123.0, 123456789.0 ); => *******0.00e+000*****123.00e+000 *****123.46e+006 (* space fill, modified floating point notation requiring six sig figs before decimal, adjusted exponent, eight integral digits, two fractional digits, space digit grouping *) (* note no comma separators in column format *) LongRealIO.WriteF( f, "S6s8.6_", 123.0, 123456789.0 ); => 123 000.000 000e-003, 123 456.789 000e+003 (* the space fill trigger "s" is only needed when necessary to separate other elements; it is the default if it can be skipped. *).
For complex number output one WriteF
procedure is required for each of the complex types COMPLEX
and LONGCOMPLEX
, and each user defined complex number type.
The syntax of a format string for complex number output is as follows:
realNumFmtStr : '"' noFormatting? realOptions? complexOptions? numeralOptions alignOptions? columnOptions? '"' ; noFormatting : 'N' ; realOptions : 'S' digit? digit?| 'F' | 'E' complexOptions : 'i', | 'j', 'r' numeralOptions : sign? intDigitOptions? fracDigitOptions? digitGrouping? suffix?; intDigitOptions : fillChar? digit digit? ; fracDigitOptions : ( '.' | ',' ) digit digit? ; sign : '+' | '-' ; fillChar : '*' | 'z' ; digitGrouping : '_' | ';' ; suffix : "'" printableCharacter+ "'" ; alignOptions : alignment fieldWidth ; alignment : '<' | '>' ; fieldWidth : digit digit? digit? ; columnOptions : concatenator | columns ; concatenator : '~' ; columns : '!" digit? digit? ;
The meaning of formatting options for each of the two real components is as follows:
'N'
- normalised, equivalent "S"'S'
- numerals are written in (possibly modified) scientific notation. The option specifies the required number of digits before the decimal; default is one "1.9e4"'E'
- numerals are written in engineering notation; exponent is always a multiple of three "19.0e3"'F'
- numerals are written in fixed point notation without an exponenet "19000"'+'
- numerals are preceded by their sign or whitespace if their value is zero'-'
- numerals are preceded by their sign if negative, otherwise by whitespace'*'
- numerals are left filled with asterisks, option requires number of integral digits shown'z'
- numerals are left filled with zeroes, option requires number of integral digits shown'.'
- numerals are written with a decimal point, option requires number of fractional digits shown','
- numerals are written with a decimal comma, option requires number of fractional digits shown'_'
- numerals are grouped into triads from right to left, separated by whitespace';'
- numerals are grouped into triads from right to left, separated by commas if decimal point, otherwise periods
The meaning of formatting options for the complex number as a whole is as follows:
'<'
- numerals are left aligned, option requires field width'>'
- numerals are right aligned, option requires field width'''
- append characters enclosed in single quotes to each numeral'~'
- concatenate numerals to their respective predecessor without separators'!'
- numerals are written in columns, option may be followed by the number of columns
The meaning of the complex formatting options is as follows:'i'
- composite format with suffix i for imaginary part'j'
- composite format with suffix j for imaginary part'r'
- raw format with real and imaginary part in parentheses separated by comma
Examples:
COMPLEX.WriteF( f, "i", {3.5, 6.75} ); => 3.5+6.75i COMPLEX.WriteF( f, "j", {3.5, 6.75} ); => 3.5+6.75j COMPLEX.WriteF( f, "r", {3.5, 6.75} ); => ( 3.5, 6.75 ) COMPLEX.WriteF( f, <format-string>, {3.5, 6.75} ); => ( 3.500000000e+00, 6.750000000e+00 )
For non-character array output the Write F?
procedure that is required for each base type can also output an array.
The syntax of a format string for non-character array output is based on the syntax of format strings for the respective base type:
nonChrArrayFmtStr : '"' baseTypeFmtOptions arrayOptions? '"' ; arrayOptions : '|' enclosureStart, separator, enclosureEnd | concatenator ; enclosureStart : '{' | '[' | '(' ; enclosureEnd : '}' | ']' | ')' ; enclosure : ',' | ';[' | ' )' ; concatenator : '~' ;
The meaning of array specific formatting options is as follows:
The start and end enclosures must match
'{}'
- array data is enclosed in curly braces, default if no array specific formatting options are present'[]'
- array data is enclosed in square brackets'()'
- array data is enclosed in parentheses'~'
- array data is written without enclosure
VAR x : ARRAY 2 OF REAL = { 1.23, 4.5 }; y : ARRAY 3 OF REAL = { 67.5, 78.0, 99.2 }; RealIO.Write2ArrayF( f, "F2.2|{,}\n", x, y ); RealIO.Write2ArrayF( f, "F2.2|[;]\n", x, y ); RealIO.Write2ArrayF( f, "F2.2|{ }\n", x, y ); RealIO.Write2ArrayF( f, "F2.2|~\n", x, y ); => { 1.23, 4.50 }, { 67.50, 78.00, 99.20 } [ 1.23; 4.50 ]; [ 67.50; 78.00; 99.20 ] { 1.23 4.50 } { 67.50 78.00 99.20 } 1.23, 4.50, 67.50, 78.00, 99.20