mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-26 18:21:04 +00:00
8f6392e943
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@9280 72102866-910b-0410-8b05-ffd578937521
405 lines
12 KiB
XML
405 lines
12 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
|
|
<gsdoc base="GSXMLParser" prev="GSXMLAttribute" up="GSXML" next="GSSAXHandler">
|
|
<head>
|
|
<title>GSXMLParser</title>
|
|
<author name="Michael Pakhantsov">
|
|
<email address="mishel@berest.dp.ua"/>
|
|
</author>
|
|
<author name="Richard Frith-Macdonald">
|
|
<email address="rfm@gnu.org"/>
|
|
</author>
|
|
<version>$Revision$</version>
|
|
<date>$Date$</date>
|
|
</head>
|
|
|
|
<body>
|
|
<chapter>
|
|
<heading>GSXMLParser</heading>
|
|
<class name="GSXMLParser" super="NSObject">
|
|
<declared>GSXML.h</declared>
|
|
<desc>
|
|
<p>
|
|
The XML parser object is the pivotal part of parsing an XML
|
|
document - it will either build a tree representing the
|
|
document (if initialized without a GSSAXHandler), or will
|
|
cooperate with a GSSAXHandler object to provide parsing
|
|
without the overhead of building a tree.
|
|
</p>
|
|
<p>
|
|
The parser may be initialized with an input source (in which
|
|
case it will expect to be asked to parse the entire input in
|
|
a single operation), or without. If it is initialised without
|
|
an input source, incremental parsing can be done by feeding
|
|
successive parts of the XML document into the parser as
|
|
NSData objects.
|
|
</p>
|
|
</desc>
|
|
|
|
<method type="NSString*" factory="yes">
|
|
<sel>loadEntity:</sel>
|
|
<arg type="NSString*">publicID</arg>
|
|
<sel>at:</sel>
|
|
<arg type="NSString*">locationURL</arg>
|
|
<desc>
|
|
<p>
|
|
This method controls the loading of external entities into
|
|
the system. If it returns an empty string, the entity is not
|
|
loaded. If it returns a filename, the entity is loaded from
|
|
that file. If it returns nil, the default entity loading
|
|
mechanism is used.
|
|
</p>
|
|
<p>
|
|
The default entity loading mechanism is to construct a file
|
|
name from the locationURL, by replacing all path separators
|
|
with underscores, then attempt to locate that file in the DTDs
|
|
resource directory of the main bundle, and all the standard
|
|
system locations.
|
|
</p>
|
|
<p>
|
|
As a special case, the default loader examines the publicID
|
|
and if it is a GNUstep DTD, the loader constructs a special
|
|
name from the ID (by replacing dots with underscores and
|
|
spaces with hyphens) and looks for a file with that name
|
|
and a '.dtd' extension in the GNUstep bundles.
|
|
</p>
|
|
<p>
|
|
NB. This method will only be called if there is no SAX
|
|
handler in use, or if the corresponding method in the
|
|
SAX handler returns nil.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMLParser*" factory="yes">
|
|
<sel>parser</sel>
|
|
<desc>
|
|
<p>
|
|
Creation of a new Parser (for incremental parsing)
|
|
by calling initWithSAXHandler:
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMLParser*" factory="yes">
|
|
<sel>parserWithContentsOfFile:</sel>
|
|
<arg type="NSString*">path</arg>
|
|
<desc>
|
|
<p>
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withContentsOfFile:
|
|
</p>
|
|
<example>
|
|
GSXMLParser *p = [GSXMLParser parserWithContentsOfFile: @"macos.xml"];
|
|
|
|
if ([p parse])
|
|
{
|
|
[[p doc] dump];
|
|
}
|
|
else
|
|
{
|
|
printf("error parse file\n");
|
|
}
|
|
|
|
</example>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMLParser*" factory="yes">
|
|
<sel>parserWithContentsOfURL:</sel>
|
|
<arg type="NSURL*">url</arg>
|
|
<desc>
|
|
<p>
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withContentsOfURL:
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMLParser*" factory="yes">
|
|
<sel>parserWithData:</sel>
|
|
<arg type="NSData*">data</arg>
|
|
<desc>
|
|
<p>Creation of a new Parser by calling
|
|
initWithSAXHandler:withData:
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMlParser*" factory="yes">
|
|
<sel>parserWithSAXHandler:</sel>
|
|
<arg type="GSSAXHandler*">handler</arg>
|
|
<desc>
|
|
<p>
|
|
Creation of a new Parser by calling initWithSAXHandler:
|
|
</p>
|
|
<p>
|
|
If the handler object supplied is nil, the parser will build
|
|
a tree representing the parsed file rather than attempting
|
|
to get the handler to deal with the parsed elements and entities.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMlParser*" factory="yes">
|
|
<sel>parserWithSAXHandler:</sel>
|
|
<arg type="GSSAXHandler*">handler</arg>
|
|
<sel>withContentsOfFile:</sel>
|
|
<arg type="NSString*">path</arg>
|
|
<desc>
|
|
<p>
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withContentsOfFile:
|
|
</p>
|
|
<example>
|
|
NSAutoreleasePool *arp = [[NSAutoreleasePool alloc] init];
|
|
GSSAXHandler *h = [GSDebugSAXHandler handler];
|
|
GSXMLParser *p = [GSXMLParser parserWithSAXHandler: h
|
|
withContentsOfFile: @"macos.xml"];
|
|
|
|
if ([p parse])
|
|
{
|
|
printf("ok\n");
|
|
}
|
|
|
|
|
|
[arp release];
|
|
</example>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMlParser*" factory="yes">
|
|
<sel>parserWithSAXHandler:</sel>
|
|
<arg type="GSSAXHandler*">handler</arg>
|
|
<sel>withContentsOfURL:</sel>
|
|
<arg type="NSURL*">url</arg>
|
|
<desc>
|
|
<p>
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withContentsOfURL:
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMlParser*" factory="yes">
|
|
<sel>parserWithSAXHandler:</sel>
|
|
<arg type="GSSAXHandler*">handler</arg>
|
|
<sel>withData:</sel>
|
|
<arg type="NSData*">data</arg>
|
|
<desc>
|
|
<p>
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withData:
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSString*" factory="yes">
|
|
<sel>xmlEncodingStringForStringEncoding:</sel>
|
|
<arg type="NSStringEncoding">encoding</arg>
|
|
<desc>
|
|
Return the name of the string encoding (for XML) to use for the
|
|
specified OpenStep encoding.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="id" init="yes">
|
|
<sel>initWithSAXHandler:</sel>
|
|
<arg type="GSSAXHandler*">handler</arg>
|
|
<desc>
|
|
<p>
|
|
Initialisation of a new Parser with SAX handler (if not nil).
|
|
</p>
|
|
<p>
|
|
If the handler object supplied is nil, the parser will build
|
|
a tree representing the parsed file rather than attempting
|
|
to get the handler to deal with the parsed elements and entities.
|
|
</p>
|
|
<p>
|
|
The source for the parsing process is not specified - so
|
|
parsing must be done incrementally by feeding data to the
|
|
parser.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="id">
|
|
<sel>initWithSAXHandler:</sel>
|
|
<arg type="GSSAXHandler*">handler</arg>
|
|
<sel>withContentsOfFile:</sel>
|
|
<arg type="NSString*">path</arg>
|
|
<desc>
|
|
<p>
|
|
Initialisation of a new Parser with SAX handler (if not nil)
|
|
by calling initWithSAXHandler:
|
|
</p>
|
|
<p>
|
|
Sets the input source for the parser to be the specified file -
|
|
so parsing of the entire file will be performed rather than
|
|
incremental parsing.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="id">
|
|
<sel>initWithSAXHandler:</sel>
|
|
<arg type="GSSAXHandler*">handler</arg>
|
|
<sel>withContentsOfURL:</sel>
|
|
<arg type="NSURL*">url</arg>
|
|
<desc>
|
|
<p>
|
|
Initialisation of a new Parser with SAX handler (if not nil)
|
|
by calling initWithSAXHandler:
|
|
</p>
|
|
<p>
|
|
Sets the input source for the parser to be the specified URL -
|
|
so parsing of the entire document will be performed rather than
|
|
incremental parsing.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="id">
|
|
<sel>initWithSAXHandler:</sel>
|
|
<arg type="GSSAXHandler*">handler</arg>
|
|
<sel>withData:</sel>
|
|
<arg type="NSData*">data</arg>
|
|
<desc>
|
|
<p>
|
|
Initialisation of a new Parser with SAX handler (if not nil)
|
|
by calling initWithSAXHandler:
|
|
</p>
|
|
<p>
|
|
Sets the input source for the parser to be the specified data
|
|
object (which must contain an XML document), so parsing of the
|
|
entire document will be performed rather than incremental parsing.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void*">
|
|
<sel>lib</sel>
|
|
<desc>
|
|
<p>Return pointer to xmlParserCtxt structure.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSXMLDocument*">
|
|
<sel>doc</sel>
|
|
<desc>
|
|
<p>
|
|
Return GSXMLDocument object.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>parse</sel>
|
|
<desc>
|
|
<p>
|
|
Parse source. Return YES if parsed, otherwise NO.
|
|
This method should be called once to parse the entire document.
|
|
</p>
|
|
<example>
|
|
GSXMLParser *p = [GSXMLParser parserWithContentsOfFile:@"macos.xml"];
|
|
|
|
if ([p parse])
|
|
{
|
|
[[p doc] dump];
|
|
}
|
|
else
|
|
{
|
|
printf("error parse file\n");
|
|
}
|
|
|
|
</example>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>parse:</sel>
|
|
<arg type="NSData*">data</arg>
|
|
<desc>
|
|
<p>
|
|
Pass data to the parser for incremental parsing. This method
|
|
should be called many times, with each call passing another
|
|
block of data from the same document. After the whole of the
|
|
document has been parsed, the method should be called with
|
|
an empty or nil data object to indicate end of parsing.
|
|
On this final call, the return value indicates whether the
|
|
document was valid or not.
|
|
</p>
|
|
<example>
|
|
GSXMLParser *p = [GSXMLParser parserWithSAXHandler: nil source: nil];
|
|
|
|
while ((data = getMoreData()) != nil)
|
|
{
|
|
if ([p parse: data] == NO)
|
|
{
|
|
NSLog(@"parse error");
|
|
}
|
|
}
|
|
// Do something with document parsed
|
|
|
|
[p parse: nil]; // Completed parsing of document.
|
|
|
|
</example>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>substituteEntites:</sel>
|
|
<arg type="BOOL">yesno</arg>
|
|
<desc>
|
|
<p>
|
|
Set and return the previous value for entity support.
|
|
Initially the parser always keeps entity references instead
|
|
of substituting entity values in the output.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>keepBlanks:</sel>
|
|
<arg type="BOOL">yesno</arg>
|
|
<desc>
|
|
<p>
|
|
Set and return the previous value for blank text nodes support.
|
|
ignorableWhitespace() are only generated when running
|
|
the parser in validating mode and when the current element
|
|
doesn't allow CDATA or mixed content.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>getWarnings:</sel>
|
|
<arg type="BOOL">yesno</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>doValidityChecking:</sel>
|
|
<arg type="BOOL">yesno</arg>
|
|
<desc>
|
|
<p>
|
|
Sets whether the document needs to be validated.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="int">
|
|
<sel>errNo</sel>
|
|
<desc>
|
|
<p>
|
|
Return error code for last parse operation.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
</class>
|
|
</chapter>
|
|
</body>
|
|
</gsdoc>
|
|
|