Expat Library - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:19:15Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:19, 26 January 2025
Line 45:		Line 45:
	No further setup is required. To use the shared Amiga library, you must include the following header file at the beginning of your code:		No further setup is required. To use the shared Amiga library, you must include the following header file at the beginning of your code:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <proto/expat.h>		#include <proto/expat.h>
	</syntaxhighlight>		</syntaxhighlight>
Line 53:		Line 53:
	Just like other AmigaOS libraries, the Expat Library must be opened and its interface obtained before you can use it:		Just like other AmigaOS libraries, the Expat Library must be opened and its interface obtained before you can use it:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Library *ExpatBase = NULL;		struct Library *ExpatBase = NULL;
	struct ExpatIFace *IExpat = NULL;		struct ExpatIFace *IExpat = NULL;
Line 84:		Line 84:
	This handler function is invoked when the parser encounters an element's start tag.		This handler function is invoked when the parser encounters an element's start tag.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void start_handler(void userData, const XML_Char name, const XML_Char **attrs)		void start_handler(void userData, const XML_Char name, const XML_Char **attrs)
	{		{
Line 94:		Line 94:
	This handler function is invoked when the parser encounters an element's end tag.		This handler function is invoked when the parser encounters an element's end tag.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void end_handler(void userData, const XML_Char name)		void end_handler(void userData, const XML_Char name)
	{		{
Line 106:		Line 106:
	Please note that Expat may produce several events (and thus call the character-data handler several times successively) before it processes all text within a single element. Such a situation arises, for example, when the text contains character entities (a character entity will always produce a separate event), or when the parser reaches the end of the buffer and needs to reload it with new data. You can never assume that element text will be processed in one go, and your code must be ready to handle it!		Please note that Expat may produce several events (and thus call the character-data handler several times successively) before it processes all text within a single element. Such a situation arises, for example, when the text contains character entities (a character entity will always produce a separate event), or when the parser reaches the end of the buffer and needs to reload it with new data. You can never assume that element text will be processed in one go, and your code must be ready to handle it!

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void chardata_handler(void userData, const XML_Char string, int length)		void chardata_handler(void userData, const XML_Char string, int length)
	{		{
Line 118:		Line 118:
	When you have written all handlers you'll need for your particular application, it's time to create the parser (or ''a parser instance'' as we say, because more than one can be used). It takes a single function call:		When you have written all handlers you'll need for your particular application, it's time to create the parser (or ''a parser instance'' as we say, because more than one can be used). It takes a single function call:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	XML_Parser parser = NULL;		XML_Parser parser = NULL;

Line 150:		Line 150:
	The following piece of code will register the handlers we've written above (the two element handlers and the character-data handler) with the [[#Creating The Parser\|parser we've created]]:		The following piece of code will register the handlers we've written above (the two element handlers and the character-data handler) with the [[#Creating The Parser\|parser we've created]]:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExpat->XML_SetElementHandler(parser, start_handler, end_handler);		IExpat->XML_SetElementHandler(parser, start_handler, end_handler);
	IExpat->XML_SetCharacterDataHandler(parser, chardata_handler);		IExpat->XML_SetCharacterDataHandler(parser, chardata_handler);
Line 161:		Line 161:
	User data normally comprises more than a single value, so it is recommended to create a dedicated custom structure such as ''struct MyUserData'' in the example code snippet below. The parser must then receive the '''address''' of the data structure (or any other kind of user data), which is done using the function XML_SetUserData():		User data normally comprises more than a single value, so it is recommended to create a dedicated custom structure such as ''struct MyUserData'' in the example code snippet below. The parser must then receive the '''address''' of the data structure (or any other kind of user data), which is done using the function XML_SetUserData():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/* Define the user data structure. */		/* Define the user data structure. */
	struct MyUserData		struct MyUserData

Daniel Jedlicka at 10:01, 27 October 2013

2013-10-27T10:01:41Z

← Older revision		Revision as of 10:01, 27 October 2013
Line 13:		Line 13:
	Tree-based parsers are really comfortable to work with: the parser reconstructs the entire document structure and contents for you. You are also provided with functions to search in the document, find data, add or modify the contents etc. Event-driven parsers are, on the other hand, much more basic. They require setup and generally more work on the part of the programmer.		Tree-based parsers are really comfortable to work with: the parser reconstructs the entire document structure and contents for you. You are also provided with functions to search in the document, find data, add or modify the contents etc. Event-driven parsers are, on the other hand, much more basic. They require setup and generally more work on the part of the programmer.

	However, tree-based parsers are rather taxing resource-wise. Parsing the document takes longer and uses up a considerable amount of memory. Implementations also tend to be bulky: for example, the current [http://www.os4depot.net/index.php?function=showfile&file=library/xml/libxml2.lha AmigaOS static library implementation of libxml2] is bigger than 5MB – which is a preposterous file size overhead added to your program only to provide it with a parser! Event-driven parsers may offer fewer bells and whistles but they are much smaller (about 300KB in all [http://www.os4depot.net/index.php?function=showfile&file=development/library/misc/expat.lha AmigaOS Expat implementations], static or shared) and faster. In order to keep the spirit of Amiga software, you'll quite naturally want to use Expat as a ~~well-proven~~ and efficient parser, preferably in its shared Amiga library incarnation.		However, tree-based parsers are rather taxing resource-wise. Parsing the document takes longer and uses up a considerable amount of memory. Implementations also tend to be bulky: for example, the current [http://www.os4depot.net/index.php?function=showfile&file=library/xml/libxml2.lha AmigaOS static library implementation of libxml2] is bigger than 5MB – which is a preposterous file size overhead added to your program only to provide it with a parser! Event-driven parsers may offer fewer bells and whistles but they are much smaller (about 300KB in all [http://www.os4depot.net/index.php?function=showfile&file=development/library/misc/expat.lha AmigaOS Expat implementations], static or shared) and faster. In order to keep the spirit of Amiga software, you'll quite naturally want to use Expat as a lightweight and efficient parser, preferably in its shared Amiga library incarnation.

	Among other things that speak in favour of event-driven parsers is the fact that when working with XML files, reconstructing the complete document tree structure is not always necessary. Quite often you're just interested in particular data that is stored in particular elements (for instance, you may only want to mine text data from the <para> sections of an XHTML document). A parser like Expat can then be used to process (react upon) events only concerning the parts of the document you're interested in. But even if you do need the entire tree structure, for whatever purpose or merely for the comfort, there is no reason to give up on Expat. As tree-based parsers are typically built on top of event-driven parsers, you can use Expat to build your own XML data representation. It means work but you can tailor the procedure to your own needs, providing perhaps less sophisticated but still adequate representation, without the extra overhead libxml2 would incur.		Among other things that speak in favour of event-driven parsers is the fact that when working with XML files, reconstructing the complete document tree structure is not always necessary. Quite often you're just interested in particular data that is stored in particular elements (for instance, you may only want to mine text data from the <para> sections of an XHTML document). A parser like Expat can then be used to process (react upon) events only concerning the parts of the document you're interested in. But even if you do need the entire tree structure, for whatever purpose or merely for the comfort, there is no reason to give up on Expat. As tree-based parsers are typically built on top of event-driven parsers, you can use Expat to build your own XML data representation. It means work but you can tailor the procedure to your own needs, providing perhaps less sophisticated but still adequate representation, without the extra overhead libxml2 would incur.
Line 142:		Line 142:
	== Parser Configuration ==		== Parser Configuration ==

	Before you can start parsing, the parser instance must be properly configured. This typically entails [[#Handler Registration\|registering all handlers]] (so that the parser knows which particular function to call when it encounters an event) and ~~providing~~ a ~~pointer to the~~ user data we want to carry around.		Before you can start parsing, the parser instance must be properly configured. This typically entails [[#Handler Registration\|registering all handlers]] (so that the parser knows which particular function to call when it encounters an event) and [[#User Data Setting\|preparing user data]] we want to carry around.

	=== Handler Registration ===		=== Handler Registration ===
Line 178:		Line 178:
	*/		*/

	/* Finally, ~~set~~ the user data address. */		/* Finally, provide the user data address. */
	IExpat->XML_SetUserData(parser, &myUserData);		IExpat->XML_SetUserData(parser, &myUserData);
	</syntaxhighlight>		</syntaxhighlight>
Line 184:		Line 184:
	== Parsing XML Files ==		== Parsing XML Files ==

	Parsing an XML document pretty much boils down to reading the file data into a memory buffer and calling XML_Parse() upon it. If you know that you'll only be working with small files, you can of course allocate a buffer the size of the XML file and then read the entire document into it. However, remember that your software may run on a system with limited memory resources, so it is always advisable to strive for a low memory footprint. The more common technique is to provide a smaller buffer and use a loop to read/parse the document in parts. This way you can process even really big XML files that otherwise wouldn't fit into memory.		Parsing an XML document pretty much boils down to reading the file data into a memory buffer and calling XML_Parse() upon it. If you know that you'll only be working with small files, you can of course allocate a buffer the size of the XML file and then read the entire document into it. However, remember that your software may run on a system with limited memory resources, so it is always advisable to strive for a low memory footprint. The more common technique is, therefore, to provide a smaller buffer and use a loop to read/parse the document in parts. This way you can process even really big XML files that otherwise wouldn't fit into memory.

	= Advanced Use =		= Advanced Use =

Daniel Jedlicka at 17:47, 26 October 2013

2013-10-26T17:47:59Z

← Older revision		Revision as of 17:47, 26 October 2013
Line 104:		Line 104:
	This handler function is invoked when the parser encounters character data (i.e. a text string that is enclosed within an element but is not itself a tag).		This handler function is invoked when the parser encounters character data (i.e. a text string that is enclosed within an element but is not itself a tag).

	Please note that Expat may produce several events (and thus call the character-data handler several times successively) before it processes all text within a single element. Such a situation arises, for example, when the text contains character entities (a character entity always ~~produces~~ a separate event), or when the parser reaches the end of the buffer and needs to reload it with new data. You can never assume that element text will be processed in one go, and your code must be ready to handle it!		Please note that Expat may produce several events (and thus call the character-data handler several times successively) before it processes all text within a single element. Such a situation arises, for example, when the text contains character entities (a character entity will always produce a separate event), or when the parser reaches the end of the buffer and needs to reload it with new data. You can never assume that element text will be processed in one go, and your code must be ready to handle it!

	<syntaxhighlight>		<syntaxhighlight>
Line 159:		Line 159:
	When using an event-driven parser you'll need to monitor the whole process yourself – keep track of depth, remember the name of the parent element, etc. You'll also need to pass values and pointers to and between handlers; for example, the [[#The Character-Data Handler\|character-data handler]] usually needs access to a global memory buffer to copy text into. In other words, you'll need to carry data around. As global variables are a no-no, Expat can take arbitrary ''user data'' and pass it to the individual handlers invoked along the parsing process. This data can then be accessed from within the handlers via the ''userData'' pointer that is provided when the handler function gets called.		When using an event-driven parser you'll need to monitor the whole process yourself – keep track of depth, remember the name of the parent element, etc. You'll also need to pass values and pointers to and between handlers; for example, the [[#The Character-Data Handler\|character-data handler]] usually needs access to a global memory buffer to copy text into. In other words, you'll need to carry data around. As global variables are a no-no, Expat can take arbitrary ''user data'' and pass it to the individual handlers invoked along the parsing process. This data can then be accessed from within the handlers via the ''userData'' pointer that is provided when the handler function gets called.

	User data normally comprises more than a single value, so it is recommended to create a dedicated custom structure such as ''struct MyUserData'' in the example code snippet below. The data structure (or any other kind of user data) is ~~then fed to the parser~~ using the function XML_SetUserData().		User data normally comprises more than a single value, so it is recommended to create a dedicated custom structure such as ''struct MyUserData'' in the example code snippet below. The parser must then receive the '''address''' of the data structure (or any other kind of user data), which is done using the function XML_SetUserData():

	<syntaxhighlight>		<syntaxhighlight>
Line 178:		Line 178:
	*/		*/

	/* Finally, ~~feed~~ the user data ~~to the parser~~. */		/* Finally, set the user data address. */
	IExpat->XML_SetUserData(parser, &myUserData);		IExpat->XML_SetUserData(parser, &myUserData);
	</syntaxhighlight>		</syntaxhighlight>

	== Parsing XML Files ==		== Parsing XML Files ==

			Parsing an XML document pretty much boils down to reading the file data into a memory buffer and calling XML_Parse() upon it. If you know that you'll only be working with small files, you can of course allocate a buffer the size of the XML file and then read the entire document into it. However, remember that your software may run on a system with limited memory resources, so it is always advisable to strive for a low memory footprint. The more common technique is to provide a smaller buffer and use a loop to read/parse the document in parts. This way you can process even really big XML files that otherwise wouldn't fit into memory.

	= Advanced Use =		= Advanced Use =

Daniel Jedlicka: /* User Data Setting */

2013-10-26T17:02:20Z

User Data Setting

← Older revision		Revision as of 17:02, 26 October 2013
Line 159:		Line 159:
	When using an event-driven parser you'll need to monitor the whole process yourself – keep track of depth, remember the name of the parent element, etc. You'll also need to pass values and pointers to and between handlers; for example, the [[#The Character-Data Handler\|character-data handler]] usually needs access to a global memory buffer to copy text into. In other words, you'll need to carry data around. As global variables are a no-no, Expat can take arbitrary ''user data'' and pass it to the individual handlers invoked along the parsing process. This data can then be accessed from within the handlers via the ''userData'' pointer that is provided when the handler function gets called.		When using an event-driven parser you'll need to monitor the whole process yourself – keep track of depth, remember the name of the parent element, etc. You'll also need to pass values and pointers to and between handlers; for example, the [[#The Character-Data Handler\|character-data handler]] usually needs access to a global memory buffer to copy text into. In other words, you'll need to carry data around. As global variables are a no-no, Expat can take arbitrary ''user data'' and pass it to the individual handlers invoked along the parsing process. This data can then be accessed from within the handlers via the ''userData'' pointer that is provided when the handler function gets called.

	User data normally comprises more than a single value, so it is recommended to create a dedicated custom structure such as ''struct MyUserData'' in the example code snippet below. ~~Before~~ ~~you~~ ~~start~~ ~~parsing,~~ ~~you~~ ~~need~~ to ~~initialize~~ ~~the~~ ~~structure~~ ~~with~~ ~~default~~ ~~values,~~ ~~and~~ ~~then~~ ~~feed~~ ~~it to~~ the ~~parser:~~		User data normally comprises more than a single value, so it is recommended to create a dedicated custom structure such as ''struct MyUserData'' in the example code snippet below. The data structure (or any other kind of user data) is then fed to the parser using the function XML_SetUserData().

	<syntaxhighlight>		<syntaxhighlight>
			/* Define the user data structure. */
	#define BUFSIZE 4096 // text buffer size

	struct MyUserData		struct MyUserData
	{		{
Line 171:		Line 170:
	};		};

			/* Declare the structure we'll be using for parsing. */

	struct MyUserData myUserData;		struct MyUserData myUserData;

	/*		/*
	~~Initialize~~ the user data		Here you would initialize the user data
			to default values.
	*/		*/
	myUserData.depth = 0
	myUserData.parElement = NULL;

		⚫	/* Finally, feed the user data to the parser. */
	if ( (myUserData.buffer = IExec->AllocVecTags(BUFSIZE,
		⚫	IExpat->XML_SetUserData(parser, &myUserData);
	AVT_ClearWithValue, 0,
	TAG_END)) )
	{
	/*
⚫	~~Ready~~, so feed the data to the parser.
	*/
⚫	IExpat->XML_SetUserData(parser, &myUserData);
	}
	else
	{
	/* Failed to create the text buffer,
	we cannot start parsing.
	Report error and clean up. */
	}
	</syntaxhighlight>		</syntaxhighlight>

Daniel Jedlicka: /* The Character-Data Handler */

2013-10-25T18:35:00Z

The Character-Data Handler

← Older revision		Revision as of 18:35, 25 October 2013
Line 102:		Line 102:
	== The Character-Data Handler ==		== The Character-Data Handler ==

	This handler function is invoked when the parser encounters character data (i.e. a text string that is enclosed within an element but is not itself a tag). Please note that Expat may produce several events (and thus call the character-data handler several times successively) before it processes all text within a single element. You can never assume that element text will be processed in one go!		This handler function is invoked when the parser encounters character data (i.e. a text string that is enclosed within an element but is not itself a tag).

			Please note that Expat may produce several events (and thus call the character-data handler several times successively) before it processes all text within a single element. Such a situation arises, for example, when the text contains character entities (a character entity always produces a separate event), or when the parser reaches the end of the buffer and needs to reload it with new data. You can never assume that element text will be processed in one go, and your code must be ready to handle it!

	<syntaxhighlight>		<syntaxhighlight>

Daniel Jedlicka at 16:43, 24 October 2013

2013-10-24T16:43:24Z

@@ Line 15: / Line 15: @@
 However, tree-based parsers are rather taxing resource-wise. Parsing the document takes longer and uses up a considerable amount of memory. Implementations also tend to be bulky: for example, the current [http://www.os4depot.net/index.php?function=showfile&file=library/xml/libxml2.lha AmigaOS static library implementation of libxml2] is bigger than 5MB – which is a preposterous file size overhead added to your program only to provide it with a parser! Event-driven parsers may offer fewer bells and whistles but they are much smaller (about 300KB in all [http://www.os4depot.net/index.php?function=showfile&file=development/library/misc/expat.lha AmigaOS Expat implementations], static or shared) and faster. In order to keep the spirit of Amiga software, you'll quite naturally want to use Expat as a well-proven and efficient parser, preferably in its shared Amiga library incarnation.
-Among other things that speak in favour of event-driven parsers is the fact that when working with XML files, reconstructing the complete document tree structure is not always necessary. Quite often you're just interested in particular data that is stored in particular elements. A parser like Expat can then be used to process (react upon) events only concerning the parts of the document you're interested in. But even if you do need the entire tree structure, for whatever purpose or merely for the comfort, there is no reason to give up on Expat. As tree-based parsers are typically built on top of event-driven parsers, you can use Expat to build your own XML data representation. It means work but you can tailor the procedure to your own needs, providing perhaps less sophisticated but still adequate representation, without the extra overhead libxml2 would incur.
+Among other things that speak in favour of event-driven parsers is the fact that when working with XML files, reconstructing the complete document tree structure is not always necessary. Quite often you're just interested in particular data that is stored in particular elements (for instance, you may only want to mine text data from the <para> sections of an XHTML document). A parser like Expat can then be used to process (react upon) events only concerning the parts of the document you're interested in. But even if you do need the entire tree structure, for whatever purpose or merely for the comfort, there is no reason to give up on Expat. As tree-based parsers are typically built on top of event-driven parsers, you can use Expat to build your own XML data representation. It means work but you can tailor the procedure to your own needs, providing perhaps less sophisticated but still adequate representation, without the extra overhead libxml2 would incur.
 = How To Use The Library =
@@ Line 74: / Line 74: @@
 Whereas handler function names are arbitrary (you can choose any name), the parameter list must follow precise definition and is different for each type of handler (see the "libraries/expat.h" include file for the definitions).
-You can pass [[#User Data Setting|user data]] to and between handlers, be it a simple variable or a complex data structure. This data can then be accessed from within the handler via the ''userData'' pointer that is provided when the handler function gets called. It is commonly used for tracking the process (parsing state), storing intermediate values, or passing global data to handlers. Never use global variables for that!
+You can pass [[#User Data Setting|user data]] to and between handlers, be it a simple variable or a complex data structure. This is commonly used for tracking the process (parsing state), storing intermediate values, or passing global data to handlers. Never use global variables for that!
 == Element Handlers ==
@@ Line 154: / Line 154: @@
 === User Data Setting ===
 == Parsing XML Files ==

Daniel Jedlicka at 22:50, 21 October 2013

2013-10-21T22:50:19Z

← Older revision		Revision as of 22:50, 21 October 2013
Line 9:		Line 9:
	* ''Tree-based parsers'', which process the entire XML file and build a tree structure representing the elements and other constructs in the document. An example of a tree-based parser is [http://en.wikipedia.org/wiki/Libxml2 libxml2], which is also available for AmigaOS.		* ''Tree-based parsers'', which process the entire XML file and build a tree structure representing the elements and other constructs in the document. An example of a tree-based parser is [http://en.wikipedia.org/wiki/Libxml2 libxml2], which is also available for AmigaOS.

	* ''Stream-oriented (event-driven) parsers'', which process the XML file as a continuous stream and produce an event each time the parser encounters an XML ~~element or character data~~. Expat is an example of an event-driven parser.		* ''Stream-oriented (event-driven) parsers'', which process the XML file as a continuous data stream and produce an event each time the parser encounters an XML construct. Expat is an example of an event-driven parser.

	Tree-based parsers are really comfortable to work with: the parser reconstructs the entire document structure and contents for you. You are also provided with functions to search in the document, find data, add or modify the contents etc. Event-driven parsers are, on the other hand, much more basic. They require setup and generally more work on the part of the programmer.		Tree-based parsers are really comfortable to work with: the parser reconstructs the entire document structure and contents for you. You are also provided with functions to search in the document, find data, add or modify the contents etc. Event-driven parsers are, on the other hand, much more basic. They require setup and generally more work on the part of the programmer.
Line 70:		Line 70:
	= Handler Functions =		= Handler Functions =

	Handler functions are custom callback functions that get invoked automatically whenever the parser encounters an XML ~~event~~ in the stream. Obvious events include XML elements and character data but there are, of course, ~~more~~: comments, XML document declarations, namespace declarations, CDATA sections, unparsed entities (NDATA) etc. For each type of event you are interested in, a handler function must be written and [[#Handler Registration\|registered with the parser]]. How you write the handlers entirely depends on what you intend to do.		Handler functions are custom callback functions that get invoked automatically whenever the parser encounters a specific XML construct in the stream. Such a situation is called ''an event''. Obvious events include XML elements and character data (handlers for these are needed for any XML parsing) but there are, of course, others: comments, XML document declarations, namespace declarations, CDATA sections, unparsed entities (NDATA) etc. For each type of event you are interested in, a handler function must be written and [[#Handler Registration\|registered with the parser]]. How you write the handlers entirely depends on what you intend to do.

	Whereas handler function names are arbitrary (you can choose any name), the parameter list must follow precise definition and is different for each type of handler (see the "libraries/expat.h" include file for the definitions).		Whereas handler function names are arbitrary (you can choose any name), the parameter list must follow precise definition and is different for each type of handler (see the "libraries/expat.h" include file for the definitions).

Daniel Jedlicka: /* How To Use The Library */

2013-10-21T22:40:42Z

How To Use The Library

← Older revision		Revision as of 22:40, 21 October 2013
Line 19:		Line 19:
	= How To Use The Library =		= How To Use The Library =

	Depending on your particular aim and purpose, using the AmigaOS Expat Library entails at least the following ~~basic~~ steps (they will all be discussed in more detail further on):		Depending on your particular aim and purpose, using the AmigaOS Expat Library entails at least the following minimum steps (they will all be discussed in more detail further on):

	# Open the library and obtain its interface (see [[#Library Opening Chores\|Library Opening Chores]] below).		# Open the library and obtain its interface (see [[#Library Opening Chores\|Library Opening Chores]] below).
	# Create ~~two~~ [[#~~Element~~ ~~Handlers~~\|~~element handler~~]] ~~functions~~ to ~~process~~ ~~XML~~ ~~element~~ ~~events~~.		# Create [[#Handler Functions\|handlers]] to deal with the particular types of XML data.
	# Create a [[#The Character-Data Handler\|character-data handler]] function to process XML character data events.
	# Create a [[#Creating The Parser\|parser instance]].		# Create a [[#Creating The Parser\|parser instance]].
	# [[#Parser Configuration\|Configure the parser]] so that it knows of your handlers.		# [[#Parser Configuration\|Configure the parser]] so that it knows of your handlers.

Daniel Jedlicka at 22:30, 21 October 2013

2013-10-21T22:30:53Z

← Older revision		Revision as of 22:30, 21 October 2013
Line 71:		Line 71:
	= Handler Functions =		= Handler Functions =

	Handler functions are custom callback functions that get invoked automatically whenever the parser encounters an XML event in the stream. Obvious events include XML elements and character data but there are, of course, more: comments, XML document declarations, namespace declarations, CDATA sections, unparsed entities (NDATA) etc. For each type of event you are interested in, a handler function must be written. How you write ~~them~~ entirely depends on what you intend to do.		Handler functions are custom callback functions that get invoked automatically whenever the parser encounters an XML event in the stream. Obvious events include XML elements and character data but there are, of course, more: comments, XML document declarations, namespace declarations, CDATA sections, unparsed entities (NDATA) etc. For each type of event you are interested in, a handler function must be written and [[#Handler Registration\|registered with the parser]]. How you write the handlers entirely depends on what you intend to do.

	Whereas handler function names are arbitrary (you can choose any name), the parameter list must follow precise definition and is different for each type of handler (see the "libraries/expat.h" include file for the definitions).		Whereas handler function names are arbitrary (you can choose any name), the parameter list must follow precise definition and is different for each type of handler (see the "libraries/expat.h" include file for the definitions).
Line 93:		Line 93:
	=== The End Element Handler ===		=== The End Element Handler ===

	This handler function is invoked when the parser encounters an element's ~~closing~~ tag.		This handler function is invoked when the parser encounters an element's end tag.

	<syntaxhighlight>		<syntaxhighlight>
Line 141:		Line 141:
	== Parser Configuration ==		== Parser Configuration ==

	Before you can start parsing, the parser instance must be properly configured. This typically entails ~~setting~~ all handlers (so that the parser knows which particular function to call when it encounters an event) and providing a pointer to the user data we want to carry around.		Before you can start parsing, the parser instance must be properly configured. This typically entails [[#Handler Registration\|registering all handlers]] (so that the parser knows which particular function to call when it encounters an event) and providing a pointer to the user data we want to carry around.

	=== Handler ~~Setting~~ ===		=== Handler Registration ===

			A handler function must first be registered if you want Expat to use it during the parsing process. Separate registration functions exist for each handler type. The functions may be called anytime, thus allowing the programmer to modify the handler configuration along the way. However, in most cases you'll probably want to do all registrations just before you send Expat on the job.

			The following piece of code will register the handlers we've written above (the two element handlers and the character-data handler) with the [[#Creating The Parser\|parser we've created]]:

			<syntaxhighlight>
			IExpat->XML_SetElementHandler(parser, start_handler, end_handler);
			IExpat->XML_SetCharacterDataHandler(parser, chardata_handler);
			</syntaxhighlight>

	=== User Data Setting ===		=== User Data Setting ===

Daniel Jedlicka: /* Creating The Parser */

2013-10-20T18:06:09Z

Creating The Parser

← Older revision		Revision as of 18:06, 20 October 2013
Line 120:		Line 120:
	XML_Parser parser = NULL;		XML_Parser parser = NULL;

	parser = XML_ParserCreate(NULL);		parser = IExpat->XML_ParserCreate(NULL);

	if (!parser)		if (!parser)
Line 128:		Line 128:
	</syntaxhighlight>		</syntaxhighlight>

	~~This~~ function creates a simple XML parser with no namespace support. The function's only parameter is the name of the character encoding that is used in the document you want to parse. If the parameter is NULL (as in the example above), the parser assumes that the document uses one of the '''built-in encodings:'''		The function creates a simple XML parser with no namespace support (please refer to [[#Namespace Processing\|this section]] if you need to handle namespaces). The function's only parameter is the name of the character encoding that is used in the document you want to parse. If the parameter is NULL (as in the example above), the parser assumes that the document uses one of the '''built-in encodings:'''

	* US-ASCII		* US-ASCII

← Older revision		Revision as of 22:40, 21 October 2013
Line 19:		Line 19:
	= How To Use The Library =		= How To Use The Library =

	Depending on your particular aim and purpose, using the AmigaOS Expat Library entails at least the following ~~basic~~ steps (they will all be discussed in more detail further on):		Depending on your particular aim and purpose, using the AmigaOS Expat Library entails at least the following minimum steps (they will all be discussed in more detail further on):

	# Open the library and obtain its interface (see [[#Library Opening Chores\|Library Opening Chores]] below).		# Open the library and obtain its interface (see [[#Library Opening Chores\|Library Opening Chores]] below).
	# Create ~~two~~ [[#~~Element~~ ~~Handlers~~\|~~element handler~~]] ~~functions~~ to ~~process~~ ~~XML~~ ~~element~~ ~~events~~.		# Create [[#Handler Functions\|handlers]] to deal with the particular types of XML data.
	# Create a [[#The Character-Data Handler\|character-data handler]] function to process XML character data events.
	# Create a [[#Creating The Parser\|parser instance]].		# Create a [[#Creating The Parser\|parser instance]].
	# [[#Parser Configuration\|Configure the parser]] so that it knows of your handlers.		# [[#Parser Configuration\|Configure the parser]] so that it knows of your handlers.