path: root/doc/expat.texi

@c This file is part of the Gamma manual.
@c Copyright (C) 2010 Sergey Poznyakoff
@c See gamma.texi for copying conditions.
@c *******************************************************************
@WRITEME

The @samp{(gamma expat)} module provides interface with
@command{libexpat}, a library for parsing @acronym{XML} documents.

Usage:

@lisp
(use-modules ((gamma expat)))
@end lisp

@menu
* primitives::             Expat Primitives
* handlers::
@end menu

@node primitives
@section Expat Primitives
@WRITEME

@deffn {Scheme procedure} xml-primitive-make-parser enc sep
Return a new @acronym{XML} parser. If @var{enc} is given, it must be one of:
@samp{US-ASCII}, @samp{UTF-8}, @samp{UTF-16}, @samp{ISO-8859-1}.  If @var{sep}
is given, the returned parser has namespace processing in effect.  In
that case, @var{sep} is a character which is used as a separator
between the namespace @acronym{URI} and the local part of the name in
returned namespace element and attribute names.
@end deffn

@deffn {Scheme procedure} xml-set-encoding parser enc
Set the encoding to be used by the @var{parser}.  The latter must be a
value returned from a previous call to
@code{xml-primitive-make-parser} or @code{xml-make-parser}.

The sequence:

@lisp
@group
  (let ((parser (xml-primitive-make-parser)))
    (xml-set-encoding parser encoding)
    @dots{}
@end group    
@end lisp

@noindent
is equivalent to:

@lisp
  (let ((parser (xml-primitive-make-parser encoding)))
   @dots{}
@end lisp

@noindent
and to:

@lisp
  (let ((parser (xml-make-parser encoding)))
   @dots{}
@end lisp
@end deffn

@deffn {Scheme procedure} xml-primitive-parse parser input isfinal
Parse next piece of input.  Arguments are:

@table @var
@item parser
A parser returned from a previous call to
@code{xml-primitive-make-parser} or @code{xml-make-parser}.

@item input
A piece of input text.

@item isfinal
Boolean value indicating whether @var{input} is the last part of
input.
@end table
@end deffn

@deffn {Scheme procedure} xml-primitive-set-handler parser key handler
Set @acronym{XML} handler for an event.  Arguments are:

@table @var
@item parser
A valid @acronym{XML} parser

@item key
A key, identifying an event.

@table @asis
@kwindex start-element-handler
@item #:start-element-handler

@kwindex end-element-handler
@item #:end-element-handler

@kwindex character-data-handler
@item #:character-data-handler

@kwindex processing-instruction-handler
@item #:processing-instruction-handler

@kwindex comment-handler
@item #:comment-handler

@kwindex start-cdata-section-handler
@item #:start-cdata-section-handler

@kwindex end-cdata-section-handler
@item #:end-cdata-section-handler

@kwindex default-handler
@item #:default-handler

@kwindex default-handler-expand
@item #:default-handler-expand

@kwindex external-entity-ref-handler
@item #:external-entity-ref-handler

@kwindex skipped-entity-handler
@item #:skipped-entity-handler

@kwindex unknown-encoding-handler
@item #:unknown-encoding-handler

@kwindex start-namespace-decl-handler
@item #:start-namespace-decl-handler

@kwindex end-namespace-decl-handler
@item #:end-namespace-decl-handler

@kwindex xml-decl-handler
@item #:xml-decl-handler

@kwindex start-doctype-decl-handler
@item #:start-doctype-decl-handler

@kwindex end-doctype-decl-handler
@item #:end-doctype-decl-handler

@kwindex element-decl-handler
@item #:element-decl-handler

@kwindex attlist-decl-handler
@item #:attlist-decl-handler

@kwindex entity-decl-handler
@item #:entity-decl-handler

@kwindex unparsed-entity-decl-handler
@item #:unparsed-entity-decl-handler

@kwindex notation-decl-handler
@item #:notation-decl-handler

@kwindex not-standalone-handler
@item #:not-standalone-handler
@end table


@item handler
Handler procedure.
@end table
@end deffn

@deffn {Scheme function} xml-make-parser args@dots{}
@FIXME
@end deffn

@deffn {Scheme function} xml-parse-more parser input
Equivalent to:

@lisp
(xml-primitive-parse parser input #f)
@end lisp

@noindent
unless @var{input} is an end-of-file object, in which case it
is equivalent to:

@lisp
(xml-primitive-parse parser "" #t)
@end lisp
@end deffn

@deffn {Scheme function} xml-parse parser
@FIXME
@end deffn

@deffn {Scheme function} xml-set-handler parser args@dots{}
@FIXME
@end deffn

@node handlers
@section Expat Handlers
@WRITEME

@deffn {Handler prototype} start-element name attrs
@FIXME
@end deffn

@deffn {Handler prototype} end-element name
@FIXME
@end deffn

@deffn {Handler prototype} character-data text
@FIXME
@end deffn

@deffn {Handler prototype} processing-instruction target data
@FIXME
@end deffn

@deffn {Handler prototype} comment text
@FIXME
@end deffn

@deffn {Handler prototype} start-cdata-section
@FIXME
@end deffn

@deffn {Handler prototype} end-cdata-section
@FIXME
@end deffn

@deffn {Handler prototype} default text
@FIXME
@end deffn

@deffn {Handler prototype} default-expand text
@FIXME
@end deffn

@deffn {Handler prototype} unparsed-entity-decl entity-name base @
 system-id public-id notation-name
@FIXME
@end deffn

@deffn {Handler prototype} notation-decl notation-name base @
 system-id public-id
@FIXME
@end deffn

@deffn {Handler prototype} start-namespace prefix uri
@FIXME
@end deffn

@deffn {Handler prototype} end-namespace prefix
@FIXME
@end deffn

@deffn {Handler prototype} skipped-entity entity-name parameter?
@FIXME
@end deffn

@deffn {Handler prototype} not-standalone 
@FIXME
@end deffn

@deffn {Handler prototype} xml-decl version encoding detail
@FIXME
@end deffn

@deffn {Handler prototype} start-doctype-decl name sysid pubid @
 has-internal-subset?
@FIXME
@end deffn

@deffn {Handler prototype} end-doctype-decl
@FIXME
@end deffn

@deffn {Handler prototype} attlist-decl el-name att-name att-type detail
@FIXME
@end deffn

@deffn {Handler prototype} entity-decl name param? value base sys-id pub-id @
 notation
@FIXME
@end deffn