Format items

Format items are a means of inserting data into a literal string. They have a wide variety of uses:

  • To insert characters into a string that cannot or should not be typed directly.
  • As a means of communicating line breaking information to a stream.
  • As a means of selecting symbols in numerical sequence.
  • As a means of communicating formatting information to the parser and retrieving values from parsed data.

Format items can be divided into two classes based on their syntax:

  • static format items make textual substitutions with pre-defined meanings, and
  • dynamic format items take a value as a parameter, and behave differently with each value.

Static format items

The syntax of a static format item is as follows:

  • the escape character; by default, %, followed by
  • the format string.
Format strings consist of zero or more format modifiers followed by a format command.

Static format items are

  • %%—insert an explicit percent sign,
  • %_—insert an explicit space character,
  • %n—insert an explicit newline character,
  • %t—insert an explicit tab character,
  • %0# through to %255#—insert an explicit byte with the given value,
  • %{...}—a sequence of characters, using their numeric character codes; a numeric base may be specified in front of the first brace, for example %16r{0d, 0a},
  • %#—insert an explicit octothorpe character (#),
  • %)—insert an explicit closing parenthesis,
  • %"—insert an explicit double quote character,
  • %'—insert an explicit single quote character,
  • %/—indicates a point where line breaking can occur,
  • %[ and %]—protect the delimited text from line breaking, and
  • %@%—insert an explicit percent sign inside a macro expansion.

The format items that represent white space (%t, %n, and %_) can take an s format modifier, which indicates that white-space stripping can be applied to the character. 

  process
     output "First line%sn"
     output "%snSecond line%sn"

Dynamic format items

Dynamic format items are generally used with the format operator, as in:

  • the format string,
  • the format operator (%), followed by
  • the value.

For example, to pad a literal string with spaces to a width of eight characters, 

  process
     output "8fg" % "foo" || "END"
This outputs 
  foo     END

Two kinds of format strings are supported: format instructions and templates. A format instruction consists of a format command preceded by one or more format modifiers. A template consists of <, a set of template characters, and >.

For example, 

  import "ombcd.xmd" unprefixed
  
  process
     local bcd    foo initial { 233.33 }
     local string bar initial { "'Twas brillig and the slithy toves" }
  
     output "Foo padded to right to 8 digits: [" || "8fd" % foo || "]%n"
     output "Bar uppercased: " || "ug" % bar || "%n"

This examples presents two format instructions:

  • for foo—"8fd" % foo, in which 8f is the format modifier, d is the format command, and % is the format operator, and
  • for bar—"ug" % bar, in which u is the format modifier, g is the format command, and % is the format operator.

At the end of the line containing each of the two format instructions, there is also a static format item, %n, to insert a newline character.

The format string varies according to the type of the variable. To format the values of specific data types using dynamic format items, see:

The format commands used in dynamic format items, and the types they are used with, are: