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
• Dynamic format items - take a variable as a parameter, and behave differently with each value of the variable

Static format items

The syntax of a static format item is as follows:

• The escape character; by default, "%".
• The format string.

Static format items are

• "%%" percent sign
• "%_" space character
• "%n" newline character
• "%t" tab character
• "%0#"..."%255#" a byte with the given value
• "%#" octothorpe character (#)
• "%)" closing parenthesis
• "%"" double quote character
• "%'" single quote character
• %/ indicates a point where line breaking can occur
• %[...%] protects the enclosed text from line breaking.
• "%@%" percent sign inside a macro expansion.

The format items that represent white space ("t", "n", "_") can take an "s" format modifier. This causes only one of that character to be output, even if two or more of the format items are output in succession. This is useful when building strings dynamically.

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

Dynamic format items

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

• format string
• the escape character; by default, "%"
• value

Note that format items do not accept expressions or literal strings. To format the result of an expression, use the format item in quotes, the % operator, followed by the expression or quoted string.

Literal string example:

  ; pad-quote-string.xom
  ; "8fg" pads the quoted string "foo" with spaces to a width of 8
  process
      output   "8fg" % "foo"  || "end"
  ; Output: "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 ">".

The example format.xom uses format instructions:

  ;  format.xom
  import "ombcd.xmd" unprefixed
  process
     local bcd foo initial {233.33}
     local stream 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"
  ; Output:  Foo padded to right to 8 digits: [233.33  ]
  ;            Bar uppercased: 'TWAS BRILLIG AND THE SLITHY TOVES

In format.xom, we have two format instructions:

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

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:

• BCD variables
• integer variables
• floating point variables
• stream variables
• parsed data (during XML or SGML parsing)

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

• "a" -- integer data type formatting
• "b" -- integer data type formatting
• "d" -- integer data type formatting, BCD data type formatting
• "g" -- stream (string data formatting)
• "i" -- integer data type formatting
• "q" -- parsed data formatting
• "p" -- parsed data formatting
• "v" -- parsed data formatting
• "x" -- deprecated format command used instead of "g" for pattern variables in earlier versions of OmniMark
• "y" -- symbol declaration
• "@" -- macro arguments

Related Syntax    escape

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]