From kristaps at bsd.lv  Thu Nov  3 11:32:15 2011
From: kristaps at bsd.lv (Kristaps Dzonsons)
Date: Thu, 03 Nov 2011 11:32:15 +0100
Subject: [Expat-discuss] expat.3 manpage
Message-ID: <4EB26DAF.3030900@bsd.lv>

Hi,

Scanning the expat.h header for docs is a little clunky, as is trying to 
navigate an unconventional HTML doc page, which is a mixture of install 
guide, API reference, and HOWTO; so I reconstituted the expat.h docs as 
mdoc(7) (using OpenBSD's expat.h as a reference, which is in sync with 
2.0.1).  This results in a nice-looking, consistent UNIX manpage.

Is anybody interested in this?  Note that well-formatted online manuals 
can be generated from this by running, e.g., mandoc -Thtml expat.3.  It 
needs a bit of polish to incorporate common usages, but the reference is 
there.

Thoughts?

Kristaps


.Dd $Mdocdate$
.Dt EXPAT 3
.Os
.Sh NAME
.Nm expat
.Nd an XML parser library
.Sh LIBRARY
.Lb expat
.Sh SYNOPSIS
.In expat.h
.Ft const XML_LChar *
.Fo XML_ErrorString
.Fa "enum XML_Error code"
.Fc
.Ft const XML_LChar *
.Fn XML_ExpatVersion
.Ft XML_Expat_Version
.Fn XML_ExpatVersionInfo
.Ft XML_Parser
.Fo XML_ExternalEntityParserCreate
.Fa "XML_Parser parser"
.Fa "const XML_Char *context"
.Fa "const XML_Char *encoding"
.Fc
.Ft const XML_Char *
.Fo XML_GetBase
.Fa "XML_Parser parser"
.Fc
.Ft void *
.Fo XML_GetBuffer
.Fa "XML_Parser parser"
.Fa "int len"
.Fc
.Ft XML_Index
.Fo XML_GetCurrentByteCount
.Fa "XML_Parser parser"
.Fc
.Ft XML_Index
.Fo XML_GetCurrentByteIndex
.Fa "XML_Parser parser"
.Fc
.Ft XML_Size
.Fo XML_GetCurrentColumnNumber
.Fa "XML_Parser parser"
.Fc
.Ft XML_Size
.Fo XML_GetCurrentLineNumber
.Fa "XML_Parser parser"
.Fc
.Ft enum XML_Error
.Fo XML_GetErrorCode
.Fa "XML_Parser parser"
.Fc
.Ft const XML_Feature *
.Fn XML_GetFeatureList
.Ft int
.Fo XML_GetIdAttributeIndex
.Fa "XML_Parser parser"
.Fc
.Ft const char *
.Fo XML_GetInputContext
.Fa "XML_Parser parser"
.Fa "int *offset"
.Fa "int *size"
.Fc
.Ft void
.Fo XML_GetParsingStatus
.Fa "XML_Parser parser"
.Fa "XML_ParsingStatus *status"
.Fc
.Ft int
.Fo XML_GetSpecifiedAttributeCount
.Fa "XML_Parser parser"
.Fc
.Ft void *
.Fo XML_GetUserData
.Fa "XML_Parser parser"
.Fc
.Ft enum XML_Status
.Fo XML_Parse
.Fa "XML_Parser parser"
.Fa "const char *s"
.Fa "int len"
.Fa "int isFinal"
.Fc
.Ft enum XML_Status
.Fo XML_ParseBuffer
.Fa "XML_Parser parser"
.Fa "int len"
.Fa "int isFinal"
.Fc
.Ft XML_Parser
.Fo XML_ParserCreate
.Fa "const XML_Char *encoding"
.Fc
.Ft XML_Parser
.Fo XML_ParserCreateNS
.Fa "const XML_Char *encoding"
.Fa "XML_Char namespaceSeparator"
.Fc
.Ft XML_Parser
.Fo XML_ParserCreate_MM
.Fa "const XML_Char *encoding"
.Fa "const XML_Memory_Handling_Suite *memsuite"
.Fa "const XML_Char *namespaceSeparator"
.Fc
.Ft void
.Fo XML_ParserFree
.Fa "XML_Parser parser"
.Fc
.Ft XML_Bool
.Fo XML_ParserReset
.Fa "XML_Parser parser"
.Fa "const XML_Char *encoding"
.Fc
.Ft enum XML_Status
.Fo XML_ResumeParser
.Fa "XML_Parser parser"
.Fc
.Ft void
.Fo XML_SetAttlistDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_AttlistDeclHandler attdecl"
.Fc
.Ft enum XML_Status
.Fo XML_SetBase
.Fa "XML_Parser parser"
.Fa "const XML_Char *base"
.Fc
.Ft void
.Fo XML_SetCdataSectionHandler
.Fa "XML_Parser parser"
.Fa "XML_StartCdataSectionHandler start"
.Fa "XML_EndCdataSectionHandler end"
.Fc
.Ft void
.Fo XML_SetCharacterDataHandler
.Fa "XML_Parser parser"
.Fa "XML_CharacterDataHandler handler"
.Fc
.Ft void
.Fo XML_SetCommentHandler
.Fa "XML_Parser parser"
.Fa "XML_CommentHandler handler"
.Fc
.Ft void
.Fo XML_SetDefaultCurrent
.Fa "XML_Parser parser"
.Fc
.Ft void
.Fo XML_SetDefaultHandler
.Fa "XML_Parser parser"
.Fa "XML_DefaultHandler handler"
.Fc
.Ft void
.Fo XML_SetDefaultHandlerExpand
.Fa "XML_Parser parser"
.Fa "XML_DefaultHandler handler"
.Fc
.Ft void
.Fo XML_SetDoctypeDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_StartDoctypeDeclHandler start"
.Fa "XML_EndDoctypeDeclHandler end"
.Fc
.Ft void
.Fo XML_SetElementHandler
.Fa "XML_Parser parser"
.Fa "XML_StartElementHandler handler"
.Fa "XML_EndElementHandler end"
.Fc
.Ft void
.Fo XML_SetElementDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_ElementDeclHandler eldecl"
.Fc
.Ft void
.Fo XML_SetEndCdataSectionHandler
.Fa "XML_Parser parser"
.Fa "XML_EndCdataSectionHandler end"
.Fc
.Ft void
.Fo XML_SetEndDoctypeDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_EndDoctypeDeclHandler end"
.Fc
.Ft void
.Fo XML_SetEndElementHandler
.Fa "XML_Parser parser"
.Fa "XML_StartElementHandler handler"
.Fa "XML_EndElementHandler end"
.Fc
.Ft void
.Fo XML_SetEndNamespaceDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_EndNamespaceDeclHandler end"
.Fc
.Ft void
.Fo XML_SetEntityDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_EntityDeclHandler handler"
.Fc
.Ft void
.Fo XML_SetExternalEntityRefHandler
.Fa "XML_Parser parser"
.Fa "XML_ExternalEntityRefHandler handler"
.Fc
.Ft void
.Fo XML_SetExternalEntityRefHandlerArg
.Fa "XML_Parser parser"
.Fa "void *arg"
.Fc
.Ft enum XML_Status
.Fo XML_SetEncoding
.Fa "XML_Parser parser"
.Fa "const XML_Char *encoding"
.Fc
.Ft void
.Fo XML_SetNamespaceDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_StartNamespaceDeclHandler start"
.Fa "XML_EndNamespaceDeclHandler end"
.Fc
.Ft void
.Fo XML_SetNotationDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_NotationDeclHandler handler"
.Fc
.Ft void
.Fo XML_SetNotStandaloneHandler
.Fa "XML_Parser parser"
.Fa "XML_NotStandaloneHandler handler"
.Fc
.Ft int
.Fo XML_SetParamEntityParsing
.Fa "XML_Parser parser"
.Fa "enum XML_ParamEntityParsing parsing"
.Fc
.Ft void
.Fo XML_SetProcessingInstructionHandler
.Fa "XML_Parser parser"
.Fa "XML_ProcessingInstructionHandler handler"
.Fc
.Ft void
.Fo XML_SetReturnNSTriplet
.Fa "XML_Parser parser"
.Fa "int do_nst"
.Fc
.Ft void
.Fo XML_SetSkippedEntityHandler
.Fa "XML_Parser parser"
.Fa "XML_SkippedEntityHandler handler"
.Fc
.Ft void
.Fo XML_SetStartCdataSectionHandler
.Fa "XML_Parser parser"
.Fa "XML_StartCdataSectionHandler start"
.Fc
.Ft void
.Fo XML_SetStartDoctypeDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_StartDoctypeDeclHandler start"
.Fc
.Ft void
.Fo XML_SetStartElementHandler
.Fa "XML_Parser parser"
.Fa "XML_StartElementHandler handler"
.Fc
.Ft void
.Fo XML_SetStartNamespaceDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_StartNamespaceDeclHandler start"
.Fc
.Ft void
.Fo XML_SetUnknownEncodingHandler
.Fa "XML_Parser parser"
.Fa "XML_UnknownEncodingHandler handler"
.Fa "void *encodingHandlerData"
.Fc
.Ft void
.Fo XML_SetUnparsedEntityDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_UnparsedEntityDeclHandler handler"
.Fc
.Ft void
.Fo XML_SetUserData
.Fa "XML_Parser parser"
.Fa "void *userData"
.Fc
.Ft void
.Fo XML_SetXmlDeclHandler
.Fa "XML_Parser parser"
.Fa "XML_XmlDeclHandler xmldecl"
.Fc
.Ft enum XML_Status
.Fo XML_StopParser
.Fa "XML_Parser parser"
.Fa "XML_Bool resumable"
.Fc
.Ft void
.Fo XML_UseForeignDTD
.Fa "XML_Parser parser"
.Fa "XML_Bool useDTD"
.Fc
.Ft void
.Fo XML_UseParserAsHandlerArg
.Fa "XML_Parser parser"
.Fc
.Sh DESCRIPTION
The
.Nm
library is an XML parser library written in C.
It is a stream-oriented parser in which an application registers
handlers for things the parser might find in the XML document (like
start tags).
.Pp
The following is a list of functions:
.Bl -tag -width Ds
.It Fn XML_ErrorString
Returns a string describing the error.
.It Fn XML_ExpatVersion
.It Fn XML_ExpatVersionInfo
Return a string containing the version number of this expat.
.It Fn XML_ExternalEntityParserCreate
Creates an
.Ft XML_Parser
object that can parse an external general entity; context is a
nil-terminated string specifying the parse context; encoding is a
nil-terminated string giving the name of the externally specified
encoding, or
.Dv NULL
if there is no externally specified encoding.
The context string consists of a sequence of tokens separated by
formfeeds
.Pq \f ;
a token consisting of a name specifies that the general entity of the
name is open; a token of the form prefix=uri specifies the namespace for
a particular prefix; a token of the form =uri specifies the default
namespace.
This can be called at any point after the first call to an
.Va ExternalEntityRefHandler
so longer as the parser has not yet been freed.
The new parser is completely independent and may safely be used in a
separate thread.
The handlers and userData are initialized from the parser argument.
Returns
.Dv NULL
if out of memory.
Otherwise returns a new
.Ft XML_Parser
object.
.It Fn XML_GetBase
.It Fn XML_SetBase
Gets or sets the base to be used for resolving relative URIs in system
identifiers in declarations.
Resolving relative identifiers is left to the application: this value
will be passed through as the base argument to the
.Va XML_ExternalEntityRefHandler ,
.Va XML_NotationDeclHandler
and
.Va XML_UnparsedEntityDeclHandler .
The base argument will be copied.
Returns
.Dv XML_STATUS_ERROR
if out of memory,
.Dv XML_STATUS_OK
otherwise.
.It Fn XML_GetBuffer
Get the buffer passed to
.Fn XML_Parse .
.It Fn XML_GetCurrentByteCount
.It Fn XML_GetCurrentByteIndex
.It Fn XML_GetCurrentColumnNumber
.It Fn XML_GetCurrentLineNumber
These functions return information about the current parse location.
They may be called from any callback called to report some parse event;
in this case the location is the location of the first of the sequence
of characters that generated the event.
When called from callbacks generated by declarations in the document
prologue, the location identified isn't as neatly defined, but will be
within the relevant markup.
When called outside of the callback functions, the position indicated
will be just past the last parse event (regardless of whether there was
an associated callback).
They may also be called after returning from a call to
.Fn XML_Parse
or
.Fn XML_ParseBuffer .
If the return value is
.Dv XML_STATUS_ERROR
then the location is the location of the character at which the error
was detected; otherwise the location is the location of the last parse
event, as described above.
.It Fn XML_GetErrorCode
If
.Fn XML_Parse
or
.Fn XML_ParseBuffer
have returned
.Dv XML_STATUS_ERROR ,
then
.Fn XML_GetErrorCode
returns information about the error.
.It Fn XML_GetFeatureList
Get the features of this expat.
.It Fn XML_GetIdAttributeIndex
Returns the index of the ID attribute passed in the last call to
XML_StartElementHandler, or -1 if there is no ID attribute.
Each attribute/value pair counts as 2; thus this corresponds to an
index into the atts array passed to the XML_StartElementHandler.
.It Fn XML_GetInputContext
If
.Dv XML_CONTEXT_BYTES
is defined, returns the input buffer, sets the integer pointed to by
offset to the offset within this buffer of the current parse position,
and sets the integer pointed to by size to the size of this buffer (the
number of input bytes).
Otherwise returns a
.Dv NULL
pointer.
Also returns a
.Dv NULL
pointer if a parse isn't active.
NOTE: The character pointer returned should not be used outside the
handler that makes the call.
.It Fn XML_GetParsingStatus
Returns status of parser with respect to being initialized, parsing,
finished, or suspended and processing the final buffer.
.Fn XML_Parse
and
.Fn XML_ParseBuffer
should return
.Fn XML_ParsingStatus
with
.Dv XML_FINISHED_OK
or
.Dv XML_FINISHED_ERROR
replacing
.Dv XML_FINISHED .
.It Fn XML_GetSpecifiedAttributeCount
Returns the number of the attribute/value pairs passed in last call to
the
.Va XML_StartElementHandler
that were specified in the start-tag rather than defaulted.
Each attribute/value pair counts as 2; thus this correspondds to an
index into the atts array passed to the
.Va XML_StartElementHandler .
.It Fn XML_GetUserData
Returns the last value set by
.Fn XML_SetUserData
or
.Dv NULL .
.It Fn XML_Parse
.It Fn XML_ParseBuffer
Parses some input.
Returns
.Dv XML_STATUS_ERROR
if a fatal error is detected.
The last call to
.Fn XML_Parse
must have
.Fa isFinal
true;
.Fa len
may be zero for this call (or any other).
Though the return values for these functions has always been described
as a Boolean value, the implementation, at least for the 1.95.x series,
has always returned exactly one of the
.Ft XML_Status
values.
.It Fn XML_ParserCreate
Constructs a new parser; encoding is the encoding specified by the
external protocol or
.Dv NULL
if there is none specified.
.It Fn XML_ParserCreateNS
Constructs a new parser and namespace processor.
Element type names and attribute names that belong to a namespace will
be expanded; unprefixed attribute names are never expanded; unprefixed
element type names are expanded only if there is a default namespace.
The expanded name is the concatenation of the namespace URI, the
namespace separator character, and the local part of the name.
If the namespace separator is
.Sq \e0
then the namespace URI and the local part will be concatenated without
any separator.
It is a programming error to use the separator
.Sq \e0
with namespace triplets (see
.Fn XML_SetReturnNSTriplet ) .
.It Fn XML_ParserCreate_MM
Constructs a new parser using the memory management suite referred to by
.Fa memsuite .
If
.Fa memsuite
is
.Dv NULL ,
then use the standard library memory suite.
If
.Fa namespaceSeparator
is not
.Dv NULL
it creates a parser with namespace processing as described above.
The character pointed at will serve as the namespace separator.
All further memory operations used for the created parser will come from
the given suite.
.It Fn XML_ParserReset
Prepare a parser object to be re-used.
This is particularly valuable when memory allocation overhead is
disproportionatly high, such as when a large number of small documnents
need to be parsed.
All handlers are cleared from the parser, except for the
.Fa unknownEncodingHandler .
The parser's external state is re-initialized except for the values of
ns and ns_triplets.
.It Fn XML_ParserFree
Frees memory used by the parser.
.It Fn XML_ResumeParser
Resumes parsing after it has been suspended with
.Fn XML_StopParser .
Must not be called from within a handler call-back.
Returns same status codes as
.Fn XML_Parse
or
.Fn XML_ParseBuffer .
Additional error code
.Dv XML_ERROR_NOT_SUSPENDED
possible.
Note: This must be called on the most deeply nested child parser
instance first, and on its parent parser only after the child parser has
finished, to be applied recursively until the document entity's parser
is restarted.
That is, the parent parser will not resume by itself and it is up to the
application to call
.Fn XML_ResumeParser
on it at the appropriate moment.
.It Fn XML_SetAttlistDeclHandler
The Attlist declaration handler is called for *each* attribute.
So a single Attlist declaration with multiple attributes declared will
generate multiple calls to this handler.
The
.Fa default
parameter may be
.Dv NULL
in the case of the "#IMPLIED" or "#REQUIRED" keyword.
The
.Fa isrequired
parameter will be true and the default value will be
.Dv NULL
in the case of "#REQUIRED".
If
.Fa isrequired
is true and default is not
.Dv NULL ,
then this is a "#FIXED" default.
.It Fn XML_SetCdataSectionHandler
.It Fn XML_SetEndCdataSectionHandler
.It Fn XML_SetStartCdataSectionHandler
Set handler for CDATA.
.It Fn XML_SetCharacterDataHandler
Set handler for data.
Data in
.Fa s
is not nil-terminated.
.It Fn XML_SetCommentHandler
Set handler for comments.
Data in
.Fa s
is nil-terminated.
.It Fn XML_SetDefaultCurrent
This can be called within a handler for a start element, end element,
processing instruction or character data.
It causes the corresponding markup to be passed to the default handler.
.It Fn XML_SetDefaultHandler
Set handler for any characters in the XML document for which there is no
applicable handler.
This includes both characters that are part of markup which is of a kind
that is not reported (comments, markup declarations), or characters that
are part of a construct which could be reported but for which no handler
has been supplied.
The characters are passed exactly as they were in the XML document
except that they will be encoded in UTF-8 or UTF-16.
Line boundaries are not normalized.
Note that a byte order mark character is not passed to the default
handler.
There are no guarantees about how characters are divided between calls
to the default handler: for example, a comment might be split between
multiple calls.
.It Fn XML_SetDefaultHandlerExpand
This sets the default handler but does not inhibit expansion of internal
entities.
The entity reference will not be passed to the default handler.
.It Fn XML_SetDoctypeDeclHandler
.It Fn XML_SetEndDoctypeDeclHandler
.It Fn XML_SetStartDoctypeDeclHandler
Set the handler called for the start of the DOCTYPE declaration, before
any DTD or internal subset is parsed; or
for the end of the DOCTYPE declaration when the closing > is
encountered, but after processing any external subset.
.It Fn XML_SetElementHandler
.It Fn XML_SetEndElementHandler
.It Fn XML_SetStartElementHandler
Set handler for elements.
.Fa atts
is array of name/value pairs, terminated by
.Dv NULL ;
names and values are nil-terminated.
.It Fn XML_SetElementDeclHandler
Set the handler called for an element declaration.
It's the caller's responsibility to free
.Fa model
when finished with it.
.It Fn XML_SetEntityDeclHandler
Set the handler called for entity declarations.
The
.Fa is_parameter_entity
argument will be non-zero if the entity is a parameter entity, zero
otherwise.
For internal entities (<!ENTITY foo "bar">), value will be not
.Dv NULL
and
.Fa systemId ,
.Fa publicID ,
and
.Fa notationName
will be
.Dv NULL .
The
.Fa value
string is NOT nul-terminated; the length is provided in the
.Fa value_length
argument.
Since it is legal to have zero-length values, do not use this argument
to test for internal entities.
For external entities,
.Fa value
will be
.Dv NULL
and
.Fa systemId
will be not
.Dv NULL .
The
.Fa publicId
argument will be
.Dv NULL
unless a public identifier was provided.
The
.Fa notationName
argument will have a not
.Dv NULL
value only for unparsed entity declarations.
Note that
.Fa is_parameter_entity
can't be changed to
.Ft XML_Bool ,
since that would break binary compatibility.
.It Fn XML_SetExternalEntityRefHandler
Set the handler calledfor a reference to an external parsed general
entity.
The referenced entity is not automatically parsed.
The application can parse it immediately or later using
.Fn XML_ExternalEntityParserCreate .
The
.Fa parser
argument is the parser parsing the entity containing the reference; it
can be passed as the parser argument to
.Fn XML_ExternalEntityParserCreate .
The
.Fa systemId
argument is the system identifier as specified in the entity
declaration; it will not be
.Dv NULL .
The
.Fa base
argument is the system identifier that should be used as the base for
resolving
.Fa systemId
if
.Fa systemId
was relative; this is set by
.Fa XML_SetBase ;
it may be
.Dv NULL .
The
.Fa publicId
argument is the public identifier as specified in the entity
declaration, or
.Dv NULL
if none was specified; the whitespace in the public identifier will have
been normalized as required by the XML spec.
The
.Fa context
argument specifies the parsing context in the format expected by the
context argument to
.Fn XML_ExternalEntityParserCreate ;
.Fa context
is valid only until the handler returns, so if the referenced entity is
to be parsed later, it must be copied.
.Fa context is
.Dv NULL
only when the entity is a parameter entity.
The handler should return
.Dv XML_STATUS_ERROR
if processing should not continue because of a fatal error in the
handling of the external entity.
In this case the calling parser will return an
.Dv XML_ERROR_EXTERNAL_ENTITY_HANDLING
error.
Note that unlike other handlers the first argument is the parser, not
.Fa userData .
.It Fn XML_SetExternalEntityRefHandlerArg
If a non-NULL value for
.Fa arg
is specified here, then it will be passed as the first argument to the
external entity ref handler instead of the
.Fa parser
object.
.It Fn XML_SetEncoding
This is equivalent to supplying an encoding argument to
.Fn XML_ParserCreate .
On success
.Fn XML_SetEncoding
returns non-zero, zero otherwise.
Note: Calling
.Fn XML_SetEncoding
after
.Fn XML_Parse
or
.Fn XML_ParseBuffer
has no effect and returns
.Dv XML_STATUS_ERROR .
.It Fn XML_SetNamespaceDeclHandler
.It Fn XML_SetEndNamespaceDeclHandler
.It Fn XML_SetStartNamespaceDeclHandler
When namespace processing is enabled, these are called once for each
namespace declaration.
The call to the start and end element handlers occur between the calls
to the
.Fa start
and
.Fa end
namespace declaration handlers.
For an xmlns attribute, prefix will be
.Dv NULL .
For an xmlns="" attribute, uri will be
.Dv NULL .
.It Fn XML_SetNotationDeclHandler
Called for a declaration of notation.
The
.Fa base argument is whatever was set by
.Fn XML_SetBase .
The
.Fa notationName
will never be
.Dv NULL .
The other arguments can be.
.It Fn XML_SetNotStandaloneHandler
Set the handler called if the document is not standalone, that is, it
has an external subset or a reference to a parameter entity, but does
not have standalone="yes".
If this handler returns
.Dv XML_STATUS_ERROR ,
then processing will not continue, and the parser will return a
.Dv XML_ERROR_NOT_STANDALONE
error.
If parameter entity parsing is enabled, then in addition to the
conditions above this handler will only be called if the referenced
entity was actually read.
.It Fn XML_SetParamEntityParsing
Controls parsing of parameter entities (including the external DTD
subset).
If parsing of parameter entities is enabled, then references to external
parameter entities (including the external DTD subset) will be passed to
the handler set with
.Fn XML_SetExternalEntityRefHandler .
The context passed will be 0.
Unlike external general entities, external parameter entities can only
be parsed synchronously.
If the external parameter entity is to be parsed, it must be parsed
during the call to the external entity ref handler: the complete
sequence of
.Fn XML_ExternalEntityParserCreate ,
.Fn XML_Parse ,
.Fn XML_ParseBuffer ,
and
.Fn XML_ParserFree
calls must be made during this call.
After
.Fn XML_ExternalEntityParserCreate
has been called to create the parser for the external parameter entity
(context must be 0 for this call), it is illegal to make any calls on
the old parser until
.Fn XML_ParserFree
has been called on the newly created parser.
If the library has been compiled without support for parameter entity
parsing (ie without XML_DTD being defined), then
.Fn XML_SetParamEntityParsing
will return 0 if parsing of parameter entities is requested; otherwise
it will return non-zero.
Note: If
.Fn XML_SetParamEntityParsing
is called after
.Fn XML_Parse
or
.Fn XML_ParseBuffer ,
then it has no effect and will always return 0.
.It Fn XML_SetProcessingInstructionHandler
Set the processing instruction handler.
.Fa target
and
.Fa data
are nil-terminated.
.It Fn XML_SetReturnNSTriplet
If
.Fa do_nst
is non-zero, and namespace processing is in effect, and a name has a
prefix (i.e. an explicit namespace qualifier) then that name is returned
as a triplet in a single string separated by the separator character
specified when the parser was created: URI + sep + local_name + sep +
prefix.
If
.Fa do_nst
is zero, then namespace information is returned in the default manner
(URI + sep + local_name) whether or not the name has a prefix.
Note: Calling
.Fn XML_SetReturnNSTriplet
after
.Fn XML_Parse
or
.Fn XML_ParseBuffer
has no effect.
.It Fn XML_SetSkippedEntityHandler
Set the handler for skipped entities.
.It Fn XML_SetUnknownEncodingHandler
Set the handler called for an encoding that is unknown to the parser.
The
.Fa name
argument gives the name of the encoding as specified in the encoding
declaration.
If the callback can provide information about the encoding, it must fill
in the
.Ft XML_Encoding
structure, and return
.Dv XML_STATUS_OK .
Otherwise it must return
.Dv XML_STATUS_ERROR .
If
.Fa info
does not describe a suitable encoding, then the parser will return an
.Dv XML_UNKNOWN_ENCODING
error.
.It Fn XML_SetUnparsedEntityDeclHandler
This sets the handler that has been superceded by
.Fn XML_SetEntityDeclHandler .
It is provided here for backward compatibility.
This is called for a declaration of an unparsed (NDATA) entity.
The
.Fa base
argument is whatever was set by
.Fn XML_SetBase .
The
.Fa entityName ,
.Fa systemId
and
.Fa notationName
arguments will never be
.Dv NULL .
The other arguments may be.
.It Fn XML_SetUserData
This value is passed as the
.Fa userData
argument to callbacks.
.It Fn XML_SetXmlDeclHandler
Set the XML declaration handler called for *both* XML declarations and
text declarations.
The way to distinguish is that the version parameter will be
.Dv NULL
for text declarations.
The encoding parameter may be
.Dv NULL
for XML declarations.
The standalone parameter will be -1, 0, or 1 indicating respectively
that there was no standalone parameter in the declaration, that it was
given as no, or that it was given as yes.
.It Fn XML_StopParser
Stops parsing, causing
.Fn XML_Pars
or
.Fn XML_ParseBuffe
to return.
Must be called from within a call-back handler, except when aborting (
.Fa resumable
as 0) an already suspended parser.
Some call-backs may still follow because they would otherwise get lost.
Examples: endElementHandler for empty elements when stopped in
startElementHandler, endNameSpaceDeclHandler when stopped in
endElementHandler, and possibly others.
Can be called from most handlers, including DTD related call-backs,
except when parsing an external parameter entity and
.Fa resumable
!= 0.
Returns
.Dv XML_STATUS_OK
when successful,
.Dv XML_STATUS_ERROR
otherwise.
Possible error codes:
.Dv XML_ERROR_SUSPENDED :
when suspending an already suspended parser.
.Dv XML_ERROR_FINISHED :
when the parser has already finished.
.Dv XML_ERROR_SUSPEND_PE :
when suspending while parsing an external PE.
When
.Fa resumable
!= 0 (true) then parsing is suspended, that is,
.Fn XML_Parse
and
.Fn XML_ParseBuffer
return
.Dv XML_STATUS_SUSPENDED .
Otherwise, parsing is aborted, that is,
.Fn XML_Parse
and
.Fn XML_ParseBuffer
return
.Dv XML_STATUS_ERROR
with error code
.Dv XML_ERROR_ABORTED .
Note: This will be applied to the current parser instance only, that is,
if there is a parent parser then it will continue parsing when the
externalEntityRefHandler returns.
It is up to the implementation of the externalEntityRefHandler to call
.Fn XML_StopParser
on the parent parser (recursively), if one wants to stop parsing
altogether.
When suspended, parsing can be resumed by calling
.Fn XML_ResumeParser .
.It Fn XML_UseForeignDTD
If
.Fa useDTD
as
.Dv XML_TRUE
is passed to this function, then the parser will assume that there is an
external subset, even if none is specified in the document.
In such a case the parser will call the externalEntityRefHandler with a
value of
.Dv NULL
for the systemId argument (the publicId and context arguments will be
.Dv NULL
as well).
Note: For the purpose of checking WFC: Entity Declared, passing
.Fa useDTD
as
.Dv XML_TRUE
will make the parser behave as if the document had a DTD with an
external subset.
Note: If this function is called, then this must be done before the
first call to
.Fn XML_Parse
or
.Fn XML_ParseBuffer ,
since it will have no effect after that.
Returns
.Dv XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING .
Note: If the document does not have a DOCTYPE declaration at all, then
startDoctypeDeclHandler and endDoctypeDeclHandler will not be called,
despite an external subset being parsed.
Note: If XML_DTD is not defined when Expat is compiled, returns
.Dv XML_ERROR_FEATURE_REQUIRES_XML_DTD .
.It Fn XML_UseParserAsHandlerArg
If this function is called, then the parser will be passed as the first
argument to callbacks instead of
.Fa userData .
The
.Fa userData
will still be accessible using
.Fn XML_GetUserData .
.El
.Sh AUTHORS
.An -nosplit
The
.Nm
library was written by
.An James Clarke .
This manual was written by
.An Kristaps Dzonsons ,
.Mt kristaps at bsd.lv .