molib documentation

Languages Available: français español

NAME

XML parser - this document defines some XML information

VERSION

Version: 1.2.0

DESCRIPTION

This part of the documentation is a quick reference to the XML recommendation. It's aim is to help developing this library in order to read valid XML documents following the strict rules set forth by the W3C consortium.

Any data being returned which still includes line separators will only include 0x0A (&x24;2.11).

See the web site here: http://www.w3.org/TR/REC-xml

special attributes: (ATTLIST) xml:space (default|preserve) 'default' (ATTLIST) xml:lang CDATA #IMPLIED (TAG) xml:lang="<normalized language encoding>"

predefined entities: & ' > < "

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

Contructor - creates a new XML parser object
Destructor - cleans up an XML parser object

VERSION

Version: 1.2.0

SYNOPSIS

moXMLParser(moXMLStream& xml_stream);
~moXMLParser();

private:
void Init(moXMLStream *xml_stream = 0);
void Clean(void);
void CleanSyntax(void);

PARAMETERS

xml_stream - a reference to a stream including XML code

DESCRIPTION

An XML parser accepts as input an moXMLStream object which itself is based on an moTextStream. The parameter is required which is why it was defined as a reference.

It will only read files of text as supported by the moTextStream object. The result is a set of strings and data in wide characters (moWCString).

These strings can be read as required (the file is processed little by little instead of all at once). Use the ReadNext() function to get the following XML entry.

SEE ALSO

Parse

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

SetSyntax - defines the XML DTD of the input file
SetVersion - defines the XML version of the input file
SetInputEncoding - defines the encoding of the input file

VERSION

Version: 1.2.0

SYNOPSIS

bool SetSyntax(const moWCString& dtd);
bool SetVersion(unsigned long version);
bool SetInputEncoding(const moWCString& encoding);

PARAMETERS

dtd - the whole DTD to use to read the input file

DESCRIPTION

All of these functions can be used to initialize the XML parser before the ReadNext() function is called.

The SetSyntax() function will be used to initialize the syntax of the reader (i.e. the DTD). This will be considered as being the default syntax. If there is an error in the DTD then this function fails.

If the file has an XML header including the standalone flag set to 'yes' then this DTD will be dropped.

The SetVersion() function can be used to determine the version of the input file. This is useful if the file doesn't include an XML header. It is strongly encouraged to also define the encoding if there isn't an XML header in the input file.

At this time, valid versions are 1.0 and 1.1 (0x10000 and 0x10001).

The SetInputEncoding() function defines the encoding of the input file. It has to be a valid encoding as understood by iconv(1). Note that a version also has to be specified if the XML file doesn't include a header. This function fails if the given encoding isn't recognized by iconv(3).

NOTES

The encoding of the DTD used by the SetSyntax() is always UTF-32 since moWCString's are UTF-32 strings. This won't change the behavior of the parser later.

RETURN VALUE

true when the functions succeed

this means that:

1) the ReadNext() function wasn't called

and

2.a) SetSyntax() got a valid DTD

2.b) SetInputEncoding() got a valid character encoding

2.c) the version is supported (1.0 or 1.1 at the
time of writing)

in all the other cases, false is returned

SEE ALSO

Encoding, Syntax, XMLVersion, ReadNext

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

ReadNext - read the next entry
ReadNextNoSignal - read the next entry and bypass the signal
ReadNextBlock - read a block of XML entities between start/end tags
BlockToString - transform a block to a string
GetData - retrieve data parsed sooner

VERSION

Version: 1.2.0

SYNOPSIS

bool ReadNext(moXMLTypeSPtr& data, bool delete_signals = false);
bool ReadNextNoSignal(moXMLTypeSPtr& data);
bool ReadNextBlock(moList::position_t& from, moList::position_t& to, bool emit_signals = false, moWCString *output);
void BlockToString(moWCString& output, moList::position_t from, moList::position_t to);
moXMLTypeSPtr GetData(moList::position_t& pos) const;

PARAMETERS

data - an moXMLType object which has a type and some data
delete_signals - don't keep signal tags in the output
from - the first data read
to - the last (inclusive) data read
emit_signals - whether the ReadNextBlock() emits signals when it finds registered a tag
output - string where the result is saved
pos - the position of the data to be returned

DESCRIPTION

The ReadNext() function reads one XML entity as decribed below and generates a signal to all the handlers registered with this XML parser.

The ReadNextNoSignal() function is similar to the ReadNext() in that it reads one XML entity, but it won't call the Signal() function so none of the handlers will be called. This is usually called from within a handler to read raw data.

The ReadNextBlock() function was added to ease the reading of a large block of XML data between a start tag and an end tag. Usually one will receive a signal on a start tag. Then, the handler of the start tag will call this function to read everything up to the end tag. Note that by default the data read won't be signaled since this function calls ReadNextNoSignal() by default.

Now ReadNextBlock() can be used wih ReadNext() and also the result can be returned at once. The result of ReadNextBlock() and of GetData() with the 'from' and 'to' values returned by ReadNextBlock() are not equal. The problem raised from the 'v' format of the mo:replace tag. That specific tag wants the signals, but doing so means certain entries should be hidden from the output and calling GetData() would reveal these entries.

The GetData() function returns a pointer to an moXMLType object previously retrieved with one of the ReadNext...() functions. This is especially useful with the ReadNextBlock() function which only returns a 'from' and 'to' set of parameters (no actual moXMLType data.)

The different XML entities are defined as follow:

. XML_TYPE_TAG_START <name ...> a new tag <name ... /> an empty tag (returned like a regular tag) <... param ...> a standalone parameter (accepted in non-strict, not XML compliant) <... param=value ...> a parameter and its value (saved in a variable list in the moXMLTag)

. XML_TYPE_TAG_END </name> a closing tag

. XML_TYPE_TAG_DATA data data between tags

. XML_TYPE_PI <?pitarget ... ?> a language target (usually "xml")

. XML_TYPE_COMMENT  a comment; note that comments are returned to the caller only if specifically requested (by default this is turned off)

. XML_TYPE_CDATA <![CDATA[ ... ]]> data read as is

. <no type> <!... > a definition parsed internally (not returned)

RETURN VALUE

true when the function succeeds in reading an XML entity

false when there is an error or the end of the file is
encountered right away (no data read before EOF)

SEE ALSO

Syntax, SetSyntax Encoding, SetEncoding Version, SetVersion moXMLType, moXMLData, moXMLTag moXMLEvent

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

Include - XML stream to include now
PopInclude - called when the end of file of the current stream is reached
InitStream - ensure that the current stream is properly initialized

VERSION

Version: 1.2.0

SYNOPSIS

void Include(moXMLStream& xml_stream, const moWCString& type = "text/xml");

private:
int PopInclude(void);
void InitStream(moXMLStream& xml_stream);

PARAMETERS

xml_stream - a valid and initialized moXMLStream object
type - a mime type representing the content of the file being included

DESCRIPTION

The Include() function stacks the current XML input stream and put the new one specified in the function call as the current one.

The subsequent calls to the XML parser will read from this new input stream until the end is reached. At that time, the XML parser will release the current XML input stream and switch back to the previous one.

Any number of XML input streams can be included in this way, but if these streams are linked to system files, it will certainly be limited to the number of files which can be opened at once on your system.

The input file will automatically have its CleanNL() and SetLineSeparators() called with the proper values used by the XML parser. It is a good idea not to modify these values afterward.

The type of the data from the input file is assumed to be text/xml. This means it will be parsed for XML data as the root file. If the file being included should not be parsed because it is of some other type (plain text, code, etc.), then you should use a different mime type such as text/plain. This has the effect of switching the reading of the current input stream to 'Read Plain Content' (see the GetPlainContent function). This means the entire file will be read in a single string and returned in the list of elements read from the input file as a DATA block. Plain files are read as is and can include all the characters you need in there. This is used with the database system whenever the data is not defined as XML data (useful to include tags read from the database which you don't want the XML parser to handle in anyway).

SEE ALSO

moXMLStream, Constructor

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

Message - print out a message
Warning - print out a warning
Error - print out an error

VERSION

Version: 1.2.0

SYNOPSIS

void Message(const char *type, const char *format, ...);
void Warning(moTextStream::errcode_t warcode, const char *format, ...);
void Error(moTextStream::errcode_t errcode, const char *format, ...);

PARAMETERS

type - a string representing the type of message (INFO, DEBUG, etc.)
warcode - a warning number
errcode - an error number
format - the error string which can include mowc::fprintf() format string info

DESCRIPTION

The Message(), Warning() and Error() functions all are used to call the corresponding function in the current moXMLStream object.

If there is no current moXMLStream, then nothing happens.

NOTES

The actual definition of these functions can be found in the moTextStream class.

SEE ALSO

mowc::fprintf(), moTextStream

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

GetPosition - get the current read position of the input stream
SetPosition - set the current read position of the input stream

VERSION

Version: 1.2.0

SYNOPSIS

size_t GetPosition(void) const;
void SetPosition(size_t position) const;

PARAMETERS

position - the position where the input stream will start over

DESCRIPTION

The GetPosition() function returns what the ReadPosition() function returns from the input stream. It can later be used to set the position of the input file back to a place of interest (usualy used to repeat the same data multiple times).

The SetPosition() function sets the read position of the input stream to the specified position. The position is always given from the start of the file. A position you obtains using the GetPosition() function can be used with this function.

RETURN VALUE

GetPosition() returns the current position of the input stream
or 0 when no input stream is defined
or -1 if an error occurs

SetPosition() doesn't return any value

SEE ALSO

Syntax, SetSyntax Encoding, SetEncoding Version, SetVersion moXMLType, moXMLData, moXMLTag

BUGS

The input streams need to be seekable to support these functions.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

Syntax - return the name of the DTD syntax
Encoding - returns the current character encoding
Version - returns the XML version (1.0 or 1.1)

VERSION

Version: 1.2.0

SYNOPSIS

const moWCString& Syntax(void) const;
const moWCString& Encoding(void) const;
unsigned long Version(void) const;

DESCRIPTION

As the XML parser reads a file, it can return the name of the current language. By default we expect an XML file. Note that the convention is to have names in lower case ASCII. It is not possible to change this value.

The Encoding() returns the encoding="..." encountered in the XML header of the one set with SetEncoding(). It is automatically used with the iconv(3) function. It is not possible to change this value.

The Version() returns the version found in the XML header or defined with SetVersion(). Until a version was defined, the Version() function returns zero. The version is saved in a 16.16 fixed integer (0x10000 for version 1.0 and 0x10001 for version 1.1).

RETURN VALUE

the name of the DTD syntax (Syntax)
the name of the encoding (Encoding)
the XML version (Version)

SEE ALSO

ReadNext

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

RegisterEventHandler - attach an event handler to this moXMLParser
Signal - send a signal, call the OnEvent() function of the handlers

VERSION

Version: 1.2.0

SYNOPSIS

void RegisterEventHandler(xml_type_t type, moXMLEvent& event);

private:
bool Signal(moXMLType& data);

DESCRIPTION

The RegisterEventHandler() function will add one more event handler to the list of handlers.

Handlers are ordered using their name and priority (in that order).

The number of handlers per moXMLParser is not limited.

Whenever an event occur, the moXMLParser will call the Signal() function. This function will go through the list of existing parsers and call their OnEvent() function.

RETURN VALUE

The Signal() function returns true if one of the OnEvent() function
returns true. This is useful to break the calls and also ensure
that the tag which generated this event won't be returned to the
caller.

SEE ALSO

moXMLEvent

BUGS

At this time there is no way to unregister an event.

Trying to add or remove handlers from within an OnEvent() call will certainly fail by making the system crash. If you need to do such a thing, you can simulate it by adding extra handlers at the start and turn a flag ON (or OFF) once they need to be active (inactive).

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

SetVariable - saves a variable name and content
GetVariable - search for the content of a named variable
UnsetVariable - delete the named variable

VERSION

Version: 1.2.0

SYNOPSIS

moXMLStreamSPtr FindStream(const moWCString& name, moWCString& var_name);
moXMLStreamSPtr InputStream(void) const;
moVariableSPtr GetVariable(const moWCString& name) const;
void AppendVariableList(const moVariableList& list);
moVariableSPtr SetVariable(const moVariable& var);
moVariableSPtr SetVariable(const moWCString& set);
moVariableSPtr SetVariable(const moWCString& name, const moWCString& value);
void UnsetVariable(const moWCString& name);

PARAMETERS

list - a list of variables
var - a variable object
set - a string including the variable name and its content (all in one)
name - a variable name
value - a variable value
var_name - a variable name without the "/" and "../"

DESCRIPTION

The moXMLParser object supports variables. The variables themselves are saved in the moXMLStream objects.

The variable names have been extended in the moXMLParser so parent moXMLStream objet variables can be accessed too. Thus, a variable name is a string which can include the slash (/) and double period (..) notation as in a filename path.

The variable /global_filename can be used to store a filename in the root (top-most) moXMLStream object. This way, any included file can modify the global variables and thus "return" a value.

The double period can be used to set or get a variable in a parent moXMLStream object. Thus, the variable ../errno could be used to set an error number in a sub-XML file for the parent XML file to know that an error occured. Similarly, if you need to execute a complex expression or a function, you can return the result in a variable using the double period (for instance, one could save the result in the variable ../my_function_result)

The GetVariable() functions will automatically try to find the named variable in any parent moXMLStream. Thus, if you write:

<mo:insert name="filename">

the variable named "filename" will be searched in the current moXMLStream, and all the parents up to the root (top-most). The first variable found is returned.

When the GetVariable() is used with a name starting with /, then only the root moXMLStream is searched.

When the GetVariable() is used with one or more double period, it starts its searched in the corresponding parent moXMLStream.

The UnsetVariable() will unset a variable only in the specified moXMLStream. It will never try to check a parent or the root if no such variable was defined in the specified moXMLStream.

<mo:unset name="background-color">

The SetVariable() function sets the variable in the specified moXMLStream only.

<mo:set name="/global_var" value="this value">

The FindStream() function can be used to search for an moXMLStream based on a variable name. The input name is the same as you would use with any of the GetVariable(), SetVariable() and UnsetVariable() functions. The var_name is the input name with all the "/" and "../" removed. This function is used internally to find the proper moXMLStream object.

The InputStream() function returns the stream currently active.

The AppendVariableList() function reads the list of variables from the input and adds them to the different parser streams. Note that here the input variable names can include path information, it will be interpreted as expected.

NOTES

The examples syntax is valid only with the proper variable XML extension. Other extensions for support of variables can be used.

RETURN VALUE

All the functions except UnsetVariable() will return an moVariable
pointer or NULL when the variable couldn't be created.

The UnsetVariable() function doesn't return an error.

SEE ALSO

moXMLStream

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

IsXMLNameChar - check if a character is a valid XML name character

VERSION

Version: 1.2.0

SYNOPSIS

static unsigned long XMLCType(mowc::wc_t c);
static bool IsXMLNameChar(mowc::wc_t c, bool first = false);
static bool IsXMLSpace(mowc::wc_t c);

PARAMETERS

first - flag telling whether we need to check for the 1st char.
c - the character to check

DESCRIPTION

XMLCType() will search for the specified character in a list of XML characters to know whether it is of a given type. Types are listed here:

XML_CTYPE_VALID XML_CTYPE_SPACE XML_CTYPE_LETTER XML_CTYPE_BASE XML_CTYPE_IDEOGRAPHIC XML_CTYPE_COMBINING XML_CTYPE_DIGIT XML_CTYPE_EXTENDER XML_CTYPE_ENCODING_START XML_CTYPE_ENCODING XML_CTYPE_PUBLIC_ID XML_CTYPE_NAME XML_CTYPE_NAME_CHAR XML_CTYPE_CHAR_REF XML_CTYPE_XCHAR_REF XML_CTYPE_INVALID

IsXMLNameChar() checks the character and returns true whenever it is a valid XML character for a tag name.

IsXMLSpace() checks the character and returns true whenever it is a defined as a space in XML. Note that some tags will change the default behavior of the meaning of XML spaces.

The XMLSkipSpaces() reads spaces and skips them until a character which isn't a space or an error occurs. The first character after the spaces is returned, but also the function will put it back in the input buffer (so the next XMLGetC() returns it again).

RETURN VALUE

IsXMLNameChar()
true - the character is a valid XML name character
false - the character can't be part of an XML name

IsXMLSpace()
true - the character is a blank
false - the character is not a blank

SEE ALSO

GetTag, GetParam

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

InitDocument - initialize the state to read an XML document

GetComment - read a comment
GetData - read data between a start & end tag
GetETag - read an XML end tag </name>
GetParam - read a parameter name & value in a tag
GetPI - read a PI entry (<?name ... ?>)
GetSTag - read an XML start tag <name ...[/]>
GetXMLDecl - read the <?xml ...?> header

GetAttribute - reads one attribute (<name>[=<value>])
GetName - reads a valid XML name
GetReference - reads one character from the input stream, if
it is a reference, transform it accordingly
GetWord - reads a word using character types defined as flags

VERSION

Version: 1.2.0

SYNOPSIS

** Initialization functions **
private:
void InitDocument(void);

** Parsing functions **
private:
int GetComment(void);
int GetContent(void);
int GetData(void);
int GetElement(void);
int GetETag(void);
int GetXMLDecl(void);
int GetParam(void);
int GetPI(void);
int GetPlainContent(void);
int GetSTag(void);

** Helper functions **
private:
mowc::wc_t GetAttribute(moVariableSPtr& attr, bool ref);
mowc::wc_t GetName(void);
mowc::wc_t GetReference(void);
mowc::wc_t GetWord(unsigned long first, unsigned long others);
mowc::wc_t TestWord(const moWCString& str, unsigned long first, unsigned long others)

PARAMETERS

attr - a variable pointer which will be defined with a variable
if a valid name is found (otherwise it is set to 0)
ref - whether reference characters (&...;) can be used
first - the flags used to test the first character
others - the flags used to test all the other characters
str - the string to be checked

DESCRIPTION

*** Initialization functions

The InitDocument() will initialize the stack with a set of function pointers which will be used to read the XML document given as input.

*** Parsing functions

GetComment() reads an XML comment . Unles the ReturnComments() function was called with true, comments are simply ignored. Otherwise they are saved in the list of items being read from the input as an moXMLData with the type XML_TYPE_COMMENT.

GetData() reads the next data or the next tag.

GetElement() reads a tag and its contents.

GetETag() reads an ending tag (i.e. </name>), it has to correspond to the starting tag as found by GetSTag() (i.e. the name must be equal).

GetPI() reads a PI entry <?name ...?>. The result is an moXMLData named with the PI name and which data will be all the characters read after the name and up to (but not including) the '?>'.

GetSTag() reads a tag name and its attributes. When an empty tag is found, its name isn't added to the f_name variable and thus we won't expect a corresponding GetETag() call.

GetXMLDecl() reads the <?xml version=...> header at the beginning of the file. Note that the tag must exist unless some external definition is given to the parser in order to know the version, encoding etc. of the file. This entry is parsed in a very specific way since it is very specific. It follows 100% the specification (only thing at this time... I'm not sure the order of the parameter should be enforced!)

*** The following are helper functions, these CAN'T be used as pointers on the stack even if they have the proper definition to be.

GetAttribute() reads one name followed by an equal sign and a quoted value. When read the XML file in non-strict mode, the attribute doesn't need to have a corresponding value and values don't need to be quoted. An error is generated when a < character appears within the value. You can circumvent this using the < entity instead.

GetName() reads a valid XML name and puts in the f_current_string which will be emptied by this function.

The GetReference() reads once character whatsoever and it expects a & as the very first character (though, if it isn't then the character read is returned as is and no error is generated).

GetWord() reads a string of characters which have to match a specific set of flags as defined in the 'first' and 'others' parameters. The first character XMLCType() flags must be among the flags set in the 'first' parameter. Similarly, the following characters XMLCType() flags must be among the flags set in the 'others' parameter. For the GetWord() function, returning an empty string isn't an error. You can check yourself whether f_current_string is empty on return. All the spaces will be included if these are accepted as part of the word/data being read.

TestWord() tests a string as if being read by the GetWord() function. The main difference is that the whole string will be checked and if any one character isn't valid and error is returned.

RETURN VALUE

All the functions 'int' will eventually return one
of the following errors (errors were given negative
values, XML_RT_NOERROR is zero; one can test for
errors like in: if(result < 0) ...):

XML_RT_NOERROR when an element was successfully read
XML_RT_EOF when the end of the file was encountered
XML_RT_ERROR when an error occured (I/O or syntax error)
XML_RT_FATAL when a fatal error occurs (we can't continue)

The functions which return an 'mowc::wc_t' return either
a character or one of the errors as described earlier.

SEE ALSO

ReadNext

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

AddCDataTag - add the name of a tag which content is CDATA

VERSION

Version: 1.2.0

SYNOPSIS

void AddCDataTag(const moWCString& name);
bool IsCDataTag(const moXMLTag& tag) const;

PARAMETERS

name -- name of the tag which content is CDATA
tag -- tag to check against the list of CDATA tags

DESCRIPTION

Tags which content is of type CDATA need to make sure not to parse the data for anything else than "</". So instead of using the default GetContent() function, it will use the GetTagCData().

This is important, especially for entries in HTML between tags such as <script> and <style>.

The IsCDataTag() function get the name of the tag parameter and searches for it in the list of tags which have been registered with the AddCDataTag() function. If a match is found it returns true, otherwise it returns false.

RETURN VALUE

IsCDataTag() returns when if tag is a CDATA tag

SEE ALSO

GetContent(), GetTagCData()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

ReturnComments - asks the parser to return long comments

VERSION

Version: 1.2.0

SYNOPSIS

bool ReturnComments(bool status = true);

PARAMETERS

status - whether to return comments (true) or not (false)

DESCRIPTION

When this function is called with true, it makes the parser return comments on ReadNext() calls. This can be useful in cases where you (1) want to copy a file to, for instance, reformat it or (2) to read a script which was otherwise commented out.

SEE ALSO

GetTag

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

KeepEntities - asks the parser to not transform &<name>;

VERSION

Version: 1.2.0

SYNOPSIS

bool KeepEntities(bool status = true);

PARAMETERS

status - whether to keep entities (true) or not (false)

DESCRIPTION

When this function is called with true, it makes the parser return entities as is. This means entities won't be transformed to characters. Thus " will remain " instead of becoming ".

This is mainly used when the read XML file is converted to HTML which will require these characters to stay as is.

Obviously the use of entity in this case becomes prohibited.

NOTES

This flag doesn't prevent DTD entities (%<name>;) from being converted.

SEE ALSO

GetReference, GetPEReference

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

ReadDTD -- asks the parser to read the DTD if possible
DTDGetElements -- get the DTD elements (see moXMLElement)
DTDGetEntities -- get the DTD entities (&<name>;)
DTDGetParsedEntities -- get the DTD parsed entities (%<name>;)

VERSION

Version: 1.2.0

SYNOPSIS

bool ReadDTD(bool status = true);

const moSortedListUniqueOfXMLElements& DTDGetElements(void) const;
const moSortedListUniqueOfXMLEntities& DTDGetEntities(void) const;
const moSortedListUniqueOfXMLEntities& DTDGetParsedEntities(void) const;

PARAMETERS

status - whether to read the DTD (true) or not (false)

DESCRIPTION

The processor will try to read the DTD files whenever possible. It will try to read files, download DTD files, etc.

By default, however, the read DTD flag is turned off to prevent the loading of the DTD. This makes it a lot faster to read files since reading the DTD can take a while.

DTDGetElements() returns a sorted list of DTD elements. These are defined as moXMLElement objects. It can be used to generate the default value of different attributes of different tags. Elements include a list of attributes and a definition of entries which define what element are acceptable within that element.

DTDGetEntities() returns a sorted list of user entities. These are used to replace &<name>; entries in the XML source files. If you set the KeepEntities() status to true, then you can later use this list to convert entities as required.

DTDGetParsedEntities() returns a sorted list of DTD internal entities. These are referenced by %<name>; and are always automatically transformed whenever we read the DTD. They have no effect on the main document. It is unlikely that you will need these entities for any purpose once the DTD file was read.

RETURN VALUE

ReadDTD() returns the previous status so you can restore it later

DTDGetElements() returns a list of moXMLElement

DTDGetEntities() returns a list of moXMLEntities

DTDGetParsedEntities() returns a list of moXMLEntities

SEE ALSO

GetAnySubset

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

Push - stack a new function to be called
Pop - unstack the top most function

VERSION

Version: 1.2.0

SYNOPSIS

private:
void Push(xml_get_func_t func);
void Pop(void);

PARAMETERS

func - the function to stack

DESCRIPTION

In order to call all the functions in order and to have a recursive effect, the function pointers are stacked in the f_stack array.

The Push() function adds one new function and the Pop() function remove one function from the stack.

When a specific token is found in a function meaning that another sub-function should be called, then it will stack a new function pointer with Push() and return.

When a function can't find any valid token and it can return (i.e. it doesn't expect to find a valid token anymore) then it calls Pop(). This means the next function on the stack will be called.

If the stack becomes empty and the end of the input file wasn't reached yet, then there is some invalid extra tokens. If the end of the stack isn't reach but the end of the input file is reached, there are invalid tokens. In this latter case, we should be able to skip the invalid tokens. In the former case, we can either emit a warning or an error (remember that a warning can be turned off).

SEE ALSO

Get<...>, InitDocument

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser

NAME

XMLGetC - get the next character
XMLSkipSpaces - skip spaces

VERSION

Version: 1.2.0

SYNOPSIS

private:
mowc::wc_t XMLGetC(void);
mowc::wc_t XMLSkipSpaces(void);

DESCRIPTION

These two functions simply call the corresponding f_input function. However, if one of the f_input functions return EOF, then we first try to pop the current f_input and read more from the previous file. If that works, we don't return EOF, instead we return whatever is available in the previous file.

This is particularly important to make the %<ref>; work in the DTD.

SEE ALSO

moXMLStream

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream

NAME

Constructor - initialize the XML stream object
Destructor - clean up the XML stream object

VERSION

Version: 1.2.0

SYNOPSIS

moXMLStream(moIStream *input = 0, moOStream *output = 0, moOStream *error = 0);
~moXMLStream();

private:
virtual void OnNewStream(int which);

PARAMETERS

input - the XML input file
output - unused
error - the error stream
which - which of the input, output or error was changed

DESCRIPTION

This object is required for the XML parser to work. You must create at least one XML stream object, and use it on creation as the input stream.

Later on, you can create new XML streams and call the Include() function to have that stream include at the current position. This is often done whenever an input in the original XML files generates some data which needs to be parsed by the XML parser.

For example, if you have a tag <DATE> that you want to have changed to the current date, you can create a moIOStream to which you write the date in a text format, then you create an moXMLStream using that moIOStream of yours as the input file and finally call Include() with the new XML stream. This will now read from your stream until the EOF is found. At that time, the parser release the moXMLStream and return to using the original input file. The number of include isn't limited.

The OnNewStream() function is used so the system can ensure the proper convertor is in place for any new input stream defined on the moXMLStream object. Also, it will clear the state as if the moXMLStream had not be used before.

RETURN VALUE

none

SEE ALSO

XMLGetC

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream

NAME

XMLSetInputEncoding - forces the encoding of the XML stream

VERSION

Version: 1.2.0

SYNOPSIS

bool XMLSetInputEncoding(const moWCString& encoding);

PARAMETERS

encoding - the name of the new encoding

DESCRIPTION

The XMLSetInputEncoding() function will be used to change the encoding from the default. The default is to try to detect the encoding of the input file.

RETURN VALUE

This function returns true if the new encoding was accepted.

SEE ALSO

Constructor, Destructor

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream

NAME

XMLSetParser - set the parser pointer in this stream

VERSION

Version: 1.2.0

SYNOPSIS

void XMLSetParser(moXMLParser& parser);

PARAMETERS

parser - the parser this stream is being used by

DESCRIPTION

In order to have the full functionality of the GetVariable() you need to have a pointer to the parser which has it. Individual XML streams can only query their own variables, not their parents (included by).

SEE ALSO

Constructor, Destructor

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream

NAME

XMLGetInterpretVariables - get the status of the interpretation of variables
XMLInterpretVariables - set the status of the interpretation of variables

VERSION

Version: 1.2.0

SYNOPSIS

bool XMLGetInterpretVariables(void) const;
void XMLInterpretVariables(bool interpret_variables = true);

PARAMETERS

interpret_variables - whether &x24;(<name> ...) has to be interpreted

DESCRIPTION

The XMLGetInterpretVariables() function returns the current setup of the interpret variable boolean value.

By default an moXMLStream parser doesn't interpret variables. If you call the XMLInterpretVariable() function with true, then it will understand and convert any input variable with its content.

The syntax for a variable is as follow:

&x24;(<name>) &x24;(<command> <options>)

NOTE: the blank between a command and different options can be new lines characters.

And the <name>, <command> and <options> can all include variable references as well. Thus, the following will return the current value of the variable named test:

<mo:set name="the.name" value="test"> <mo:set name="test" value="result"> &x24;(&x24;(the.name))

In this example, "result" will be inserted (without the quotes). First it transforms &x24;(the.name) to test and then it applies &x24;() to that name which in turns is defined as "result".

RETURN VALUE

The XMLGetInterpretVariables() function returns the current status
of the interpret variable which is either true or false.

SEE ALSO

Constructor, Destructor

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream

NAME

XMLCurrentLine - returns a reference to the current line in full
XMLCurrentString - returns a reference to the last string read
XMLFindInCurrentLine - search for a string in the current line
XMLGetC - read one character from the input file
XMLGetPos - get the current character position in the line
XMLGetString - reads several characters from the input file
XMLNextLine - bufferize one line at once
XMLSetPos - change the current character position in the line
XMLSkipC - skip 1 or more characters in the current line
XMLSkipSpaces - read all spaces and return the next character (peek)
XMLTestString - test a string against the input
XMLUngetC - put one character back (you can't specify the character)

VERSION

Version: 1.2.0

SYNOPSIS

const moWCString& XMLCurrentLine(void) const;
const moWCString& XMLCurrentString(void) const;
moWCString& XMLCurrentString(void);
long XMLFindInCurrentLine(const moWCString& str, long length = -1) const;
mowc::wc_t XMLGetC(void);
int XMLGetPos(void) const;
int XMLGetString(moWCString& string, int count);
int XMLNextLine(void);
void XMLSetPos(int pos);
void XMLSkipC(int skip = 1);
mowc::wc_t XMLSkipSpaces(void);
bool XMLTestString(const char *str, bool case_sensitive = true) const;
void XMLUngetC(void);

private:
int XMLNextLineNow(void);

PARAMETERS

string - where the characters read are saved
count - the number of characters to read
str - the string to compare with
case_sensitive - whether the case of letters matters
skip - the number of characters to be skipped
length - maximum number of characters to compare (-1 for all of parameter string)
pos - new position in the current string

DESCRIPTION

XMLGetC() reads the next character from the input file. This function will automatically skip any character which is considered invalid by the XML standard. It may call the XMLNextLine() in case the end of the current line was reached.

The XMLUngetC() function will cancel the reading of the last character by XMLGetC() (and multiple calls can cancel an XMLGetString() call!). Note that the XMLUngetC() can't unget more than what is on the current line. Trying to unget more will result in a throw. This should anyway never be necessary.

The XMLSkipSpaces() can be called to skip all the spaces present in the input stream. It will read all the spaces until another character is found. This other character is put back in the input stream so the next call to XMLGetC() returns it. This character is also returned by a call to XMLSkipSpaces(). Thus, this function is similar to doing a eek for the next character ignoring spaces.

The XMLSkipC() function will be called whenever the following few characters are already known and thus a call to XMLGetC() is not required. Warning: this function fails if the end of line was already reached and the number of characters to skip is larger than the number of characters left on the current line.

The XMLTestString() function compares the user supplied string with the current line of input. Note that the user supplied string can't include an XML space. This is typically used to forward test strings such as '<?xml', '<!--', etc.

The XMLGetString() function can be used to read multiple characters at once. It is usual to use this function to read something which was first checked and found with the XMLTestString() function.

The XMLCurrentLine() function will be used whenever the last line read is required. A constant reference to the whole line is returned.

The XMLCurrentString() function gives you access to the current string variable. This string can be used whenever the current moXMLStream has a chance to be changed and the data being read needs to be preserved. There are two versions, one is constant and one is not.

The XMLNextLine() function is usually called by the XMLGetC() function when all the characters in the current buffer were read and more are necessary. It will read one line from the input stream including the new line sequence. It replaces the input stream new line sequence with a single '\n' character. This function needs to be called once on initialization and when a call to XMLTestString() needs to be done from the very first character on the input line.

The XMLFindInCurrentLine() is similar to the XMLTestString() function except it will search for the specified input string from the current position up to the end of the string. The position of the found string is returned or -1.

NOTES

The private functions are helper functions to the different non-private functions listed here.

RETURN VALUE

. const moWCString& XMLCurrentLine(void) const;

Return a reference to the current line (last line which was
read from the input file).

. const moWCString& XMLCurrentString(void) const;
. moWCString& XMLCurrentString(void);

Returns a reference to the current string (data added by
some functions which needs to be preserved between calls
and changes of the moXMLStream objects.)

You can get a constant or non constant version as required.

. long XMLFindInCurrentLine(const moWCString& str, long length = -1) const;

Returns a value from f_pos to the size of the current line
minus 1 (XMLCurrentLine().Length() - 1) or -1 when the
input string (str) isn't found in the current line.

. mowc::wc_t XMLGetC(void);

The following character found in the input stream. This
function returns XML_RT_EOF whenever the end of the file
is reached. Other negative values are errors.

. int XMLGetPos(void) const;

Return the current position within the current line.
(What the XMLGetC() function will use next).

. int XMLGetString(moWCString& string, int count);

Returns the following 'count' characters in 'string'.
The function returns XML_RT_NOERROR when no error
occurs.

. int XMLNextLine(void);

This function returns XML_RT_NOERROR when the line is
succesfully read. A negative value indicates an
error.

. mowc::wc_t XMLSkipSpaces(void);

Returns the character after the skipped spaces, however
that character is kept in the input stream. In other
words, the next XMLGetC() will return that character.

. bool XMLTestString(const char *str, bool case_sensitive = true) const;

Return true if the following characters in the current
line string match the characters in 'str'.

SEE ALSO

Constructor, Destructor

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream

NAME

XMLSaveName - save the current name for include functionality test
XMLGetName - retrieve the last saved name

VERSION

Version: 1.2.0

SYNOPSIS

void XMLSaveName(const moWCString& name);
const moWCString& XMLGetName(void) const;

PARAMETERS

name - the current name of tags (i.e. HTML/BODY/TABLE/TR/TD/B)

DESCRIPTION

At this time, the XMLSaveName() function is used whenever the moXMLParser::Include() function is called. It saves the current tag name the parser is in. This is used to ensure that when the included file is removed from the stack, we have the correct tag and not an unclosed tag from within the included file.

The XMLGetName() will return the last named saved with a call to the XMLSaveName(). At this time, this is done only when the end of a file is encountered and this is not the root file.

RETURN VALUE

The XMLGetName() returns a reference to the tag name.

SEE ALSO

moXMLType

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream

NAME

XMLSetVariable - create or modify the named variable with the specified value
XMLGetVariable - search for the named variable
XMLUnsetVariable - deletes the named variable

VERSION

Version: 1.2.0

SYNOPSIS

void XMLAppendVariableList(const moVariableList& list);
void XMLSafeAppendVariableList(const moVariableList& list);
moVariableSPtr XMLSetVariable(const moVariable& var);
moVariableSPtr XMLSetVariable(const moWCString& set);
moVariableSPtr XMLSetVariable(const moWCString& name, const moWCString& value);
moVariableSPtr XMLGetVariable(const moWCString& name) const;
void XMLUnsetVariable(const moWCString& name);

PARAMETERS

var - a pre-defined variable
set - a string composed of a variable name and its value
name - the name of a variable
value - the content of a variable

DESCRIPTION

The XMLAppendVariableList() adds all the variables from the input list to the moXMLStream object set of variables. Note that the existing variables will be overwritten. Use the XMLSafeAppendVariableList() function instead of you don't want to overwrite the existing variables.

The XMLSetVariable(), XMLGetVariable() and XMLUnsetVariable() are all three maps of the Set(), Get() and Unset() of the moVariable object.

These functions are called by the moXMLParser in order to set, find and unset variable as required.

The naming conversion defined in the moXMLParser isn't passed down to this object.

RETURN VALUE

The XMLSetVariable() and XMLGetVariable() functions return a
pointer to the created or found moVariable object.

The XMLUnsetVariable() function doesn't return anything.

SEE ALSO

moVariable, moXMLParser

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream::moReducer

NAME

Constructor - initialize the reducer
Reduce - reset the reducer before calling the lower level Reduce() function
GetVariable - function used to retrieve a variable from the XML stream
GetC - function used to read one character from the XML stream

VERSION

Version: 1.2.0

SYNOPSIS

moReducer(moXMLStream *stream);
virtual int Reduce(moWCString& result);
virtual moWCString GetVariable(const moWCString& name);
virtual mowc::wc_t GetC(unsigned long depth);

PARAMETERS

stream - the XML stream which owns this moReducer
result - a string where the reduced result is saved
name - this is the name of the variable being queried
depth - the current depth when the next character is being requested

DESCRIPTION

The moReducer in the moXMLStream is used to enable any level of variable reduction in an XML input.

This object will be used only if the user called the function XMLInterpretVariables() with true. In all other cases, it will be unused.

Note that the Reduce() is used to reset a variable so we know we are in a new parser.

For a complete set of information about how this object works, please look at the moVariableReduce class.

RETURN VALUE

The GetVariable() function returns a copy of the variable or an
empty string is the variable isn't defined.

The GetC() function returns the next character of input from the
moXMLStream object until either the depth parameter is zero or
the end of the stream is reached in which case MO_VR_EOF is
returned. Note that -1 can be returned if an error occurs.

SEE ALSO

moXMLType

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStream::moReducer::moExpandEntities

NAME

Execute - execute a specialised reducer command
Name - returns the name of the reducer command

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Execute(const moListOfWCStrings& parameters, moWCString& result);
virtual const moWCString Name(void) const;

PARAMETERS

parameters -- the parameter to expand
result -- the expanded parameter

DESCRIPTION

This class is used to extend the moReducer in order to offer a specialized instruction to expand XML entities whenever required by the user.

RETURN VALUE

The Execute() function will usually return 0 (no error).

SEE ALSO

moXMLType

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLStringReducer

NAME

Constructor - initialize the reducer
GetVariable - function used to retrieve a variable from the XML stream
GetC - function used to read one character from the attached string

VERSION

Version: 1.2.0

SYNOPSIS

moXMLStringReducer(const moWCString& string, moXMLStream *stream);
virtual moWCString GetVariable(const moWCString& name);
virtual mowc::wc_t GetC(unsigned long depth);

PARAMETERS

string - the string to use as input for the GetC() function
stream - an XML stream which variables will be used with this moStringReducer
name - this is the name of the variable being queried
depth - the current depth when the next character is being requested

DESCRIPTION

The moStringReducer in the moXMLParser is used to enable any level of variable reduction in a string.

This object is used by different extensions which deal with dynamic content which may include variables (it is possible to define dynamic variables using the set tag as follow: <mo:set ... keepvars="true">...</mo:set>

For a complete set of information about how this object works, please look at the moVariableReduce class.

RETURN VALUE

The GetVariable() returns a copy of the queried variable or an
empty string is the variable isn't defined.

The GetC() returns the next character in the string or MO_VR_EOF
when the end of the file is reached.

SEE ALSO

moReduce (in moXMLStream)

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLType

NAME

Constructor - create an XML item
GetType - return the type of this XML item

VERSION

Version: 1.2.0

SYNOPSIS

moXMLType(xml_type_t type, const moWCString& name, const moWCString& tag_name);
xml_type_t GetType(void) const;
const moWCString& GetTagName(void) const;
void SetPosition(size_t position);
size_t GetPosition(void) const;

PARAMETERS

type - the new XML data type (see below for a list of available types)
name - the full directory like name of this tag
tag_name - this tag name without its parent names
position - a position usually where the XML stream is at

DESCRIPTION

The moXMLType() base object is used to define different XML items. These objects are automatically created by the XML parser as it reads the given items in the XML input file.

An moXMLType is derived from an moWCString and thus is a string. The string of an moXMLType object represents the full name of the tag (for instance, in HTML it could like this: "/html/head/title"). The tag_name parameter is the name of this very tag without the parent names (in our last example, it is: "title")

Note that the other XML object types are all based on this one.

The GetType() function returns the type of this XML item. See the xml_type_t declaration for a complete list of types. At the time of writing the following were defined:

XML_TYPE_UNKNOWN should never be used for an XML object!

XML_TYPE_TAG_START a start tag (includes attributes and their values)

XML_TYPE_TAG_END an end tag

XML_TYPE_PI a PI, the name is the PI name and the data is what was read between the '<?name' and the '?>' markers

XML_TYPE_DATA data read between a start and end tag; it is transformed as required (the &...; that is)

XML_TYPE_CDATA data read between a '<![CDATA[' and a ']]>' marker; the data is not transformed in any way

XML_TYPE_COMMENT a standard XML comment written between ''

The SetPosition() and GetPosition() functions can be used to save and restore a size_t value. Most of the time, the SetPosition() is used to save the current moXMLStream position (in all cases, when an event occurs, the current position of the moXMLStream object is right after the data which just triggered the event). The GetPosition() will return the last saved value. In case of an OpenTag/CloseTag pair, these functions will be used to repeat the input multiple times (i.e. in case of an <mo:for ...>repeat this data from the input stream so it's always exactly the same</mo:for> or any similar loop).

SEE ALSO

moXMLData, moXMLTag

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLData

NAME

Constructor - create an XML item of type data
SetData - change the current data of this item
GetData - return the data of this XML item

VERSION

Version: 1.2.0

SYNOPSIS

moXMLData(xml_type_t type, const moWCString& name, const moWCString& tag_name);
void SetData(const moWCString& data);
const moWCString& GetData(void) const;

PARAMETERS

type - the new XML data type (see the moXMLType constructor for more info)
name - the full directory like name of this tag
tag_name - this tag name without its parent names

DESCRIPTION

The moXMLData class inherits the moXMLType class.

It will specifically be used with the following types:

XML_TYPE_PI, XML_TYPE_COMMENT, XML_TYPE_DATA, XML_TYPE_CDATA

SEE ALSO

moXMLType, moXMLTag

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLTag

NAME

Constructor - create an XML item of type tag
Get - get a named attribute
Set - set an attribute name and value
GetList - get the current list of attributes
MarkAsEmpty - mark this tag as being empty
IsEmpty - returns true if this is an empty tag

VERSION

Version: 1.2.0

SYNOPSIS

moXMLTag(const moWCString& name, const moWCString& tag_name);
moVariable *Get(const moWCString& attr) const;
moVariable *Set(const moVariable& var) const;
const moVariableList& GetList(void) const;
moVariableList& GetList(void);
void MarkAsEmpty(bool empty = true);
bool IsEmpty(void) const;

PARAMETERS

name - the name of this tag
attr - name of the attribute being queried
var - a variable to add to the list of attributes
empty - whether we mark this tag as empty or not

DESCRIPTION

The moXMLTag class inherits the moXMLType base class.

It will specifically be used to declare a starting tag (XML_TYPE_TAG_START) and it includes all the attributes of that tag.

The moXMLTag includes an moVariable variable member which can be accessed through different functions (Get, Set, GetList). The Get() and Set() functions of the moXMLTag are directly mapped on the Get() and Set() functions respectively of the moVariable class. If you need to use other function member of the variable list, then use the GetList() function first and use the returned moVariable reference to query the list of attributes (i.e. one can get the number of attributes in order to enumerate them all).

Note that the Set() function accepts a variable that is a string with a name.

A tag can be marked empty (call MarkAsEmpty() to change the current emptiness). When a tag was marked empty, the IsEmpty() function returns true.

SEE ALSO

moXMLType

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLEvent

NAME

Constructor - initialize an moXMLEvent object
Destructor - cleans up the moXMLEvent object
OnEvent - called whenever the corresponding type of data is found in the input
GetPriority - retrieve the priority of the object

VERSION

Version: 1.2.0

SYNOPSIS

moXMLEvent(int priority, const moWCString& name);
~moXMLEvent();

virtual bool OnEvent(moXMLParser& parser, moXMLType& type);
virtual compare_t Compare(const moBase& object) const;
virtual compare_t CompareNameOnly(const moBase& object) const;

PARAMETERS

parser - the moXMLParser object which found the corresponding input
type - the type and data found when this event occurs
object - another event handler

DESCRIPTION

You can create objects that you derive from the moXMLEvent class.

These objects can be registred with the moXMLParser using the RegisterEventHandler() function. Then, that moXMLParser will call the OnEvent() function each time it finds the corresponding event. That function being virtual, you can overwrite it with your own code to process the start/end tag, PI, [C]DATA or comment.

The priority is used to sort the different event handlers with the same name in the moXMLParser list of handlers. By default, handlers have a priority of 0. A handler with a larger priority (more positive) is called first.

The Compare() function will be used by the sorted lists. It compares two handlers names and priority (in that order).

The CompareNameOnly() function is used by the moXMLParser to search for all the event handlers of the same name.

NOTES

The same event handler can be used by different moXMLParser objects as required.

RETURN VALUE

The OnEvent() function can return true in order to break the loop of
event handlers being called and also to make sure that the tag or
data which generated the call to the handler isn't included in the
output.

SEE ALSO

moXMLParser, moXMLType

BUGS

The types COMMENT, DATA and CDATA events don't use names (all of the handlers are called each time). However, if you do specify a name, they will be sorted using the name and priority like the other types.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLElement::moXMLEntry

NAME

Constructor -- initialize an moXMLEntry object
Destructor -- cleans up the moXMLEntry object
SetType -- defines the type
SetRepeat -- defines the repeat mode
SetName -- sets the name of this entry
GetType -- retrieve the type of this entry
GetRepeat -- get the repeat mode
GetName -- get the name of the entry
HasPCDATA -- check whether one of the children is a #PCDATA
Count -- return the number of children entries
Get -- get a child entry
AddSubEntry -- add a sub-entry

VERSION

Version: 1.2.0

SYNOPSIS

moXMLEntry(void);
virtual ~moXMLEntry();

void SetType(type_t type);
void SetRepeat(repeat_t repeat);
void SetName(const moWCString& name);

type_t GetType(void) const;
repeat_t GetRepeat(void) const;
const moWCString& GetName(void) const;
bool HasPCDATA(void) const;

unsigned long Count(void) const;
moXMLEntry *Get(int idx) const;
void AddSubEntry(moXMLEntry *entry);

virtual compare_t Compare(const moBase& object) const;

PARAMETERS

type -- an entry type
repeat -- a repeat mode
name -- a string with the entry name
idx -- an entry index
entry -- a valid sub-entry object

DESCRIPTION

Whenever the XML processor reads a DTD file, it creates a list of elements. These elements can reference other elements. These references are defined in an entry.

An entry can be composed of names and sub-entries. The content of an entry can have a repeat mode and its type define whether the different sub-entries are used as choices or a sequence.

The SetType(), SetRepeat() and SetName() functions are used to initialize an entry. The AddSubEntry() is also an initialization function which adds a sub-entry to an entry. Note that the main entry is only composed of sub-entries.

All the other functions will be used to check the data in an entry.

The HasPCDATA() function checks all the sub-entries and return true if one of the sub-entries is a #PCDATA entry. Note that only the first sub-entry should be a #PCDATA in a valid DTD.

IMPORTANT NOTE: the HasPCDATA() returns false if the entry you are testing is a #PCDATA entry since it has no sub-entries.

The Count() tells you how many sub-entries this entry includes. An entry with 0 sub-entries is either a NAME, a PCDATA, an EMPTY or the special ANY entry. An entry with 1 or more sub-entries is either a CHOICE or a SEQUENCE.

You can use the Count() to know the largest index you can use with the Get() function.

The following list defines all the types:

ENTRY_EMPTY ENTRY_ANY ENTRY_PCDATA ENTRY_NAME ENTRY_CHOICE ENTRY_SEQUENCE

The GetRepeat() returns of of the following values:

REPEAT_ONCE REPEAT_ANY REPEAT_ONE_OR_MORE REPEAT_ZERO_OR_ONE

REPEAT_ONCE is the default when the user doesn't specify any repeat flag. It means the entry needs to be defined exactly once to be valid.

REPEAT_ANY represents the asterisk (*) meaning that you can have none, 1 or more.

REPEAT_ONE_OR_MORE represents the plus (+) meaning that you need to have at least one of the entry.

REPEAT_ZERO_OR_ONE represents the question mark (?) meaning that you have an optional entry which can appear once.

RETURN VALUE

GetType() returns one of the ENTRY_... enumeration values.

GetRepeat() returns one ofthe REPEAT_... enumeration values.

GetName() returns the name of the entry which represents an element
(i.e. a tag name).

HasPCDATA() returns true if one of the sub-entries of this entry is
a #PCDATA.

Count() returns the number of sub-entries. Can be zero.

Get() returns one of the sub-entries. Cannot be null.

Compare -- returns a comparison value MO_BASE_COMPARE_...

SEE ALSO

moXMLParser, moXMLElement

BUGS

The Get() instruction will throw an error if the index is out of range.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moXMLParser::moXMLElement::moXMLAttribute

NAME

Constructor -- initializes an attribute
Destructor -- cleans up an attribute
SetType -- sets the attribute type
SetValueType -- sets the type of value
AddUserTypeName -- add the user type name
SetDefaultValue -- set the default value of an attribute
GetName -- get the name of this attribute
GetType -- get the type of attribute (CDATA, ID, NMTOKEN, etc.)
GetValueType -- get the type of value (#IMPLIED, #REQUIRED, etc.)
Count -- return the number of enumeration names
GetUserTypeName -- get one of the enumeration name
GetDefault -- get the default value
Compare -- compare two attributes by name

VERSION

Version: 1.2.0

SYNOPSIS

moXMLAttribute(const moWCString& name);
virtual ~moXMLAttribute();

void SetType(type_t type);
void SetValueType(value_t value_type);
bool AddUserTypeName(const moWCString& user_name);
void SetDefaultValue(const moWCString& value);

const moWCString& GetName(void) const;
type_t GetType(void) const;
value_t GetValueType(void) const;
unsigned long Count(void) const;
const moWCString& GetUserTypeName(int idx) const;
const moWCString& GetDefault(void) const;

virtual compare_t Compare(const moBase& object) const;

PARAMETERS

name -- the name of the attribute
type -- the type of the attribute
value_type -- the type of the value of the attribute
user_name -- a user name (enumeration or notation)
value -- the default value
idx -- the index of the user name to retrieve
object -- another attribute to compare against

DESCRIPTION

The elements can accept a set of attributes. The DTD can define the attribute name, type and content.

The attribute name is a valid XML name.

The attribute type is one of the following:

ATTRIBUTE_CDATA ATTRIBUTE_ID ATTRIBUTE_IDREF ATTRIBUTE_IDREFS ATTRIBUTE_ENTITY ATTRIBUTE_ENTITIES ATTRIBUTE_NMTOKEN ATTRIBUTE_NMTOKENS ATTRIBUTE_NOTATION ATTRIBUTE_ENUMERATION

These types are defined in the XML reference. In XML, the ENUMERATION type is represented by names defined between parenthesis. The NOTATION type uses the same list of strings.

The Count() function returns the number of entries in the ENUMERATION and NOTATION lists of names. It is illegal DTD for the list to be empty in these cases, but of course, the list can be empty if the user did not define any name.

Note that names need to be unique and thus you cannot add duplicates.

The value of the attribute is also typed as follow:

VALUE_REQUIRED VALUE_IMPLIED VALUE_FIXED VALUE_DEFAULT

When REQUIRED, the user must include that attribute in any corresponding tag (tag with the attribute name, which is also the name of an element.)

The IMPLIED type means that wh