#lang scribble/doc

@(require scribble/manual
          (for-label scheme
                     "main.ss"))

@title{The "libxml2" Tool}

@defmodule[(planet clements/libxml2)]

This library is intended to provide bindings to the popular "libxml2" library.

Currently, the only thing it does is use the libxml2 library to parse xml
files into sxml, including Relax NG validation.  
It's about twice as fast as (planet lizorkin/ssax:2:0/ssax).

It does handle namespaces, in one of the two styles described by SXML. In particular,
it prepends the URI itself associated with the namespace to the node's name. This appears
also to be the default behavior of ssax.

This library is completely skeletal.  If you want to build a set of bindings to libxml2,
use this as a starting point.

@defproc[(xml->sxml/file [path path-string?]) sxml?]

Given a file, produce the sxml that corresponds to it. FWIW, the runtime is completely 
dominated by the construction of the scheme s-expression; the libxml2 parse function takes
about a tenth of the total time.

@defproc[(xml->sxml/bytes [bytes bytes?] [#:valid validation-context validation-context? #f]) sxml?]

Given a byte-string, produce the sxml that corresponds to it. See comments on prior function.

Here's an example, using the validation context @scheme[vc] defined below:

@schemeblock[(xml->sxml/bytes #"<TARGETDECK><TARGET name=\"Zaronga\"><POSITION /></TARGET></TARGETDECK>"
                              #:valid vc)]

@defproc[(bytes->validation-context [bytes bytes?] [#:valid validation-context validation-context? #f]) validation-context?]

Given a byte-string representing a Relax NG specification written using the XML syntax, produce
a validation context usable with @scheme[xml->sxml/file] and @scheme[xml->sxml/bytes].

Here's an example:

@schemeblock[(define vc (bytes->validation-context (string->bytes/utf-8 
  #<<|
<?xml version="1.0" encoding="UTF-8"?>
<element name="TARGETDECK" xmlns="http://relaxng.org/ns/structure/1.0">
  <zeroOrMore>
    <element name="TARGET">
      <optional>
        <attribute name="name"/>
      </optional>
      <element name="POSITION">
        <value/>
      </element>
    </element>
  </zeroOrMore>
</element>
|
  )))]


@defproc[(validation-context? [v any/c]) boolean?]

Returns @scheme[true] only when @scheme[v] is a value produced by @scheme[bytes->validation-context].

Let me know of any bugs.