GSXMLParser $Revision$ $Date$ GSXMLParser GSXML.h

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.

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.

loadEntity: publicID at: locationURL

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.

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.

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.

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.

parser

Creation of a new Parser (for incremental parsing) by calling initWithSAXHandler:

parserWithContentsOfFile: path

Creation of a new Parser by calling initWithSAXHandler:withContentsOfFile:

GSXMLParser *p = [GSXMLParser parserWithContentsOfFile: @"macos.xml"]; if ([p parse]) { [[p doc] dump]; } else { printf("error parse file\n"); } parserWithContentsOfURL: url

Creation of a new Parser by calling initWithSAXHandler:withContentsOfURL:

parserWithData: data

Creation of a new Parser by calling initWithSAXHandler:withData:

parserWithSAXHandler: handler

Creation of a new Parser by calling initWithSAXHandler:

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.

parserWithSAXHandler: handler withContentsOfFile: path

Creation of a new Parser by calling initWithSAXHandler:withContentsOfFile:

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]; parserWithSAXHandler: handler withContentsOfURL: url

Creation of a new Parser by calling initWithSAXHandler:withContentsOfURL:

parserWithSAXHandler: handler withData: data

Creation of a new Parser by calling initWithSAXHandler:withData:

xmlEncodingStringForStringEncoding: encoding Return the name of the string encoding (for XML) to use for the specified OpenStep encoding. initWithSAXHandler: handler

Initialisation of a new Parser with SAX handler (if not nil).

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.

The source for the parsing process is not specified - so parsing must be done incrementally by feeding data to the parser.

initWithSAXHandler: handler withContentsOfFile: path

Initialisation of a new Parser with SAX handler (if not nil) by calling initWithSAXHandler:

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.

initWithSAXHandler: handler withContentsOfURL: url

Initialisation of a new Parser with SAX handler (if not nil) by calling initWithSAXHandler:

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.

initWithSAXHandler: handler withData: data

Initialisation of a new Parser with SAX handler (if not nil) by calling initWithSAXHandler:

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.

lib

Return pointer to xmlParserCtxt structure.

doc

Return GSXMLDocument object.

parse

Parse source. Return YES if parsed, otherwise NO. This method should be called once to parse the entire document.

GSXMLParser *p = [GSXMLParser parserWithContentsOfFile:@"macos.xml"]; if ([p parse]) { [[p doc] dump]; } else { printf("error parse file\n"); } parse: data

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.

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. substituteEntites: yesno

Set and return the previous value for entity support. Initially the parser always keeps entity references instead of substituting entity values in the output.

keepBlanks: yesno

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.

getWarnings: yesno doValidityChecking: yesno

Sets whether the document needs to be validated.

errNo

Return error code for last parse operation.