entity-resolver

data type

Library: Markup utilities (OMMARKUPUTILITIES)
Import : ommarkuputilities.xmd

Purpose

An instance of the entity-resolver type can be used to resolve references to external entities.

The default entity-resolver type resolves external entities much the same way as OmniMark's default entity manager, relying on the built-in shelves #library and #libpath which can be set from the command line.

If entity resolution fails, the resolution-failure exception will be thrown. This is different from the default entity manager which throws a #program-error instead.

The markup utilities library also provides the operator | that can combine two entity-resolver values so that the right-hand resolver acts as a fallback in case the primary left-hand resolver fails.

Using the base entity-resolver

The following example uses the default entity-resolver to resolve the DTD external text entity reference:

  import "ommarkuputilities.xmd" unprefixed
  
  process
     do xml-parse document scan "<!DOCTYPE a SYSTEM 'doc.dtd'><a/>"
        using output as external-entity-resolver via new entity-resolver {}
           output #content
     done
     output "All entities have been resolved.%n"
  
   catch resolution-failure
     output "An entity could not be resolved.%n"

The output of this program depends on whether the file doc.dtd can be found in the current directory or any directory specified using the -libpath command-line option.

Extensions

The base entity-resolver record type can be extended and its behaviour modified. One such extension that is part of the standard OmniMark libraries can be found is oasis.catalog-type in the omoasiscatalogs library.

The next example demonstrates an extension that uses the OMVFS library to potentially read the resolved entity content from the Web, if it is not available locally.

  import "ommarkuputilities.xmd" unprefixed
  import "omvfs.xmd"               prefixed by vfs.
  
  declare record web-resolver extends entity-resolver
  
  
  define overriding string function
     map-external-identifier               via value web-resolver resolver
                             public-identifier value string       public-id  optional
                             system-identifier value string       system-id  optional
  as
     do when public-id is specified & #library has key public-id
        return #library{public-id}
  
     else when system-id is specified
        return system-id
  
     else
        local resolution-failure-report r
  
        set r:resolver to resolver
        set new r:properties{"message"} to "No SYSTEM identifier has been specified."
  
        throw resolution-failure report r
     done
  
  
  define overriding string source function
     read-entity  via value web-resolver resolver
                 from value string       uri
  as
     output vfs.reader of vfs.open uri
  
  
  process
     do sgml-parse document scan '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"'
                              || ' "http://www.w3.org/TR/html4/transitional.dtd">%n'
                              || '<html><head><title>HTML test</title></head></html>%n'
        using output as external-entity-resolver via new web-resolver {}
           output #content
     done
     output "All entities have been resolved.%n"
  
   catch resolution-failure
     output "An entity could not be resolved.%n"

Related Topics

Entities, external

Other Library Functions