swirl Guide to OmniMark 5   OmniMark home
docs home 
IndexConceptsTasksSyntaxLibrariesOMX VariablesErrors
 
Prerequisite Concepts     Related Syntax  
Parsed data: formatting

When you parse XML or SGML data, you have two choices for formatting the parsed data. The first is to capture the parsed data in OmniMark streams and then use regular OmniMark programming techniques to format the data. The other is to give instructions to the parser on how you want the data formatted. The latter approach is often faster and cleaner.

You give instructions to the parser on how to format data using format items and placing the appropriate format modifiers on the format commands "c", "v", and "q". In some cases, you can use format modifiers to access different elements or interpretations of a piece of parsed data.

Formatting data content

Unless you intercept it in a data content rule, the parser outputs data content to the current output scope. You can add format modifiers to the parse continuation operator, "%c", to change how the data content is formatted.

The supported format modifiers are:

It is possible to override the subcomponents, even those going into the same stream, by removing the modifier with the following syntax:

  put my-stream with "" "%c"

Formatting element names and external entities

The "%q" format item refers to the name of the currently opened element everywhere except in external-text-entity and external-data-entity rules. In functions, even if the function is called from an external-text-entity or an external-data-entity rule, the "%q" still refers to the currently opened element. This is to ensure that a function always behaves in the same way, regardless of what rule it is called from.

When referring to an element, the "%q" format can have the following modifiers:

In entity rules, the "%q" format item only refers to the name of the current entity in the actions of an external-data-entity or an external-text-entity rule. It refers to the current element everywhere else, including in functions, as mentioned above.

The following modifiers can be used to return other information about a current entity.

These modifiers can be combined as follows:

If an entity has no system identifier, then the "e" format modifier acts the way "ep" does.

If an entity has no public identifier, or if the program has no library rule to associate a system identifier with the entity's public identifier, then it is an error to use the "ep" format modifier combination. If such an entity also does not declare a system identifier in the entity declaration, then it is also an error to use the "e" format modifier.

The same observation applies to the system identifier of the entity's notation when using the above format modifiers in combination with the "o" format modifier.

All of the combinations above may be further combined with the "l" or "u" format modifiers. Additionally, the "o" format modifier can also be combined with the "f" and "k" format modifiers, provided that it is not also combined with the "e" or "p" modifiers.

The "f" and "k" format modifiers can only be used with entity names and notation names.

Formatting attributes and external data entities

You use the "%v" format item to output an attribute of an element or of an external-data-entity.

The following example outputs the section ID (the attribute named "ID") when processing an SGML document:

  element section
    output "Section: || %v(id) || %c"

The DTD for the above example must contain lines similar to the following:

  <!element section - o (#PCDATA)>
  <!attlist section id number #REQUIRED>

In element rules, the named attribute must be an attribute of the element; in external-data-entity rules, it must be a data attribute of the entity being processed. In all other rules, the named attribute must be an attribute of the containing element.

The following modifiers can always be used with the "%v" format item:

If the attribute has a CDATA declared type, the following modifiers can also be used:

If the attribute's declared type is entity or entities, and the entity name refers to an external entity, you can use the following modifiers (but not with the "f", "k", "l", and "u" modifiers):

These modifiers are combined as follows:

If an entity has no system identifier, then "e" acts as "ep" does. It is an error if either "e" or "ep" is used, and the entity has no system or public identifier bound by a library rule to a system identifier.

This format accesses letters within system and public identifiers in uppercase or lowercase as they appear in the entity declaration. Letters in element, entity, or notation names appear in uppercase or lowercase as they appear in the processed document, unless the SGML declaration specifies uppercase substitution for that class of name. If so, the name is accessed with letters forced to uppercase. Thus, in the Reference Concrete Syntax, by default, element and notation names appear in uppercase while entity names appear as entered in the document.

For an entities attribute, if the attribute value contains more than one entity name, the using prefix must be used to select one entity whose system or public identifier is to be manipulated or displayed.

If the value of an entity or entities attribute is the name of an internal CDATA or SDATA entity, the "%ev" format can be used to determine the replacement text of the internal entity.

The "e", "p", and "ep" formats can also be used with notation attributes, under the same conditions as entity or entities.

This example illustrates how the "%ev" format handles internal and external entities differently.

The element "as-is" has a single required ENTITY attribute "text". The entity named by the attribute value simply provides the text that is to replace the element, wherever it occurs in a document.

  <!ELEMENT as-is - o EMPTY>
  <!ELEMENT as-is text ENTITY #REQUIRED>

The element rule for processing the "as-is" element does the following:

Note that "%ev" returns one of two things, depending on whether the entity named by the attribute to which it is applied is internal or external:


  element as-is
        do when attribute text is external
           output file "%ev(text)"
        else
           output "%ev(text)"
        done
     suppress

Prerequisite Concepts
     Format items
   Markup rules
 
  Related Syntax
   attribute
   external-data-entity
   external-text-entity
 
----

Top [ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ OMX ] [ OMX ] [ ERRORS ]

Generated: August 11, 2000 at 3:06:25 pm
If you have any comments about this section of the documentation, send email to docerrors@omnimark.com

Copyright © OmniMark Technologies Corporation, 1988-2000.