do xml-parse

control structure

Syntax
do xml-parse document (with id-checking switch-expression)? 
                      (with utf-8 switch-expression)? 
                      (creating xml-dtds{string-expression})? scan string-source-expression 
   local-declaration*
   action*
done


do xml-parse scan string-source-expression 
   local-declaration*
   action*
done


do xml-parse instance (with document-element string-expression)? 
                      (with (xml-dtds{string-expression} | current xml-dtd))?
                      (with id-checking switch-expression)? scan string-source-expression 
   local-declaration*
   action*
done


Purpose

Basic usage

do xml-parse is used to invoke the XML parser. A number of activities must occur within a do xml-parse block.

  1. Specify the type of parse to be launched: well-formed or validating.
  2. Provide a string source that will be used for input.
  3. Consume the resulting markup source, either directly as #content or by executing exactly one parse continuation operator (%c or suppress) to fire markup rules.

Well-formed parsing

Well-formed parsing (that is, XML parsing without validating against a DTD) is invoked by leaving out the document keyword and other arguments except for the input: 

  do xml-parse scan file #args[1]
     output "%c"
  done

Validating parsing

The document keyword is used to configure the XML parser to validate its input against a DTD. The DTD is supplied as part of the input. 

  do xml-parse document scan file #args[1]
     output "%c"
  done

This assumes that the file whose name is specified on the command-line contains an XML document. If the DTD and the instance are in different files, they can be joined: 

  do xml-parse document scan file #args[1] || file #args[2]
     output "%c"
  done

Validating of multiple documents

If the same DTD is to be used to parse several input instances, it is best to pre-compile the DTD and store it on the built-in sgml-dtds shelf: 

  do xml-parse document creating xml-dtds{"my-dtd"} scan file #args[1]
     suppress
  done
If the instance file names are stored on a shelf my-instances, then each instance can then be processed in turn: 
  repeat over my-instances
     do xml-parse instance with xml-dtds{"my-dtd"} scan file my-instances 
        output "%c"
     done
  again

Validating against an outer DTD

A nested XML parse can use the same DTD as an outer XML parse to validate its own input: for instance, 

  process
     using group "one"
     do xml-parse document scan "<!DOCTYPE a ["
                              || "<!ELEMENT a (b | #PCDATA)*>"
                              || "<!ELEMENT b (#PCDATA)>]>"
                              || "<a><b>Hello, World!</b></a>"
        output "%c"
     done
  
  
  group "one"
     element "a"
        using group "b"
        do xml-parse instance with current xml-dtd scan "<a>Salut, Monde!</a>"
           output "%c"
        done
        output "%c"
  
  
     element "b"
        output "%c"
  
  
  group "b"
     element "a"
        output "%c"

In this program, the XML parse launched in the element rule for a inside group one uses the same DTD as the parse launched in the process rule.

Validating a partial instance

It is possible to parse a partial instance: a piece of data comprising an element from a DTD which is not the doctype element of that DTD. In this case, the element to be used as the effective doctype for parsing the data is specified using the document-element argument: 

  do xml-parse instance with document-element "lamb" with xml-dtds{"my-dtd"} scan file #args[1]
     output "%c"
  done
XML comments, processing instructions and even marked sections can precede and follow the element's start and end tags, but anything else (particularly other elements, data, or entity references) is an error.

Controlling ID/IDREF checking

By default, OmniMark checks all XML idref attributes to make sure they reference valid IDs. This checking may not be appropriate in processing a partial instance. It also takes time. It can be disabled using with id-checking followed by a switch expression. The following code will parse the specified document without checking IDREFs: 

  do xml-parse document with id-checking false scan file #args[1]
     output "%c"
  done

Handling documents with different character set encodings

The XML standard specifies that XML documents use the Unicode character set. However, there are many different encodings of the Unicode character set. OmniMark can process documents in any of these encodings: see Character set encoding for details.

One character encoding issue that arises in markup processing is the question of which character set encoding the parser is to use when resolving numeric character entities. When doing well-formed parsing, OmniMark uses UTF-8 encoding to represent numeric character entities. When doing validating parsing, the parser can be configured to use either UTF-8 or Latin-1 encoding for numeric character entities. The default is Latin-1. This has a number of consequences.

  • The processing of the documents that do not contain character entities greater than 127 is not affected, unless the document is encoded using a character encoding that does not correspond with 7-bit ASCII for characters 0 to 127. In this case, it is best to convert the document to UTF-8 for processing and convert it back afterwards.
  • A document encoded in Latin-1 and containing character entities greater than 127 should be converted to UTF-8 for processing, and converted back afterwards.
  • Documents encoded in UTF-8 and processed using well-formed parsing do not need special considerations.
  • When processing a document encoded in UTF-8 using validating parsing, the with utf-8 modifier should be passed to do xml-parse, with a switch expression that evaluates to true: 
      process
     do xml-parse document with utf-8 true scan file #args[1]
        output "%c"
     done
  • If the document being processed is encoded in Latin-1 and does not contains character entities greater 256, and is being processed using a validating parse, no special considerations are required.
  • If the document being processed is encoded in Latin-1 and does contains character entities greater 256, and is being processed using a validating parse, the document should be converted to UTF-8 for processing, and converted back afterwards.

Related Syntax
Related Concepts