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
• "%{...} 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}.
• "%#" 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, 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:

• 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 ] [ LEGACY LIBRARIES ] [ ERRORS ]