Related Syntax
Entity managers: programmer-defined

The relatively simple model supported by OmniMark's built-in entity manager (an external entity is a file) works for most OmniMark applications, but not for all. For those other applications, OmniMark programmers can, in a simple and straightforward way, write their own entity managers, using OmniMark's external-text-entity rule.

The external-text-entity rule allows the OmniMark programmer to do things other than just providing an alternative way of finding a file containing an entity's text. An entity can be any sequence of characters. The entity manager provides a sequence of characters to the SGML parser when the SGML parser passes and external entity reference to the entity manager. The sequence of characters doesn't have to be a "verbatim" copy of the text in a file. Other possibilities include:

• An OmniMark program can support an alternative way of finding entities' files, to provide more generality than OmniMark's entity manager, to be compatible with other SGML-supporting products, or to support newly developed conventions, such as the entity catalog file format developed by the SGML Open Consortium (SOCAT).
• An entity may be composed of the text of two or more files joined together. The system identifier may consist of a set of file names, or be the name of a subdirectory.
• Multiple entities can be "packaged" in a single file, requiring the OmniMark program to search for the entity's text in a file.
• An entity may consist of one or more records in a database.
• An entity may be known to the OmniMark program, and the program may contain the entity's text, for example, in a keyed shelf.
• The OmniMark program may create a stream shelf that contains the text of one or more external entities. The text for the streams could be read from one or more files, or be created by the OmniMark program.
• The OmniMark program may wish to provide default text for external text entities which cannot be found.

Direct access to the entries in the library rules and "-libpath" command-line arguments are provided by OmniMark so that the behavior of OmniMark's entity manager can be duplicated by a program written in OmniMark. This can be useful, for example, when what OmniMark's entity manager does is a good "fall-back" position when an application-specific scheme does not find an entity's text.

You can program an entity manager to skip over unreadable files when it is searching for the file containing the text of an external entity. The following code interprets the system identifier as a set of alternative file names separated by semicolons. It uses the first readable file it finds as the text of the external entity, skipping over references to directories. If there is no such file, the external-text-entity rule terminates the OmniMark program, and adds a message to the #error stream:

  external-text-entity #implied when entity is system
     repeat scan "%eq"
     match [\ ";"]+ => file-name
        do when file file-name is readable and
                file file-name isnt directory
           output file file-name
           exit
        done
     match ";"
        ; Skip over the separating semicolons
     match value-end
        put #error "None of the files %"%eq%" (for entity %q) " _
                   "are readable.%n"
        halt
     again

Related Syntax    external-text-entity    library

----

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