Detailed Description
and Rendering XMLNode's to files/string.
|
Functions | |
| static XMLNode | XMLNode::parseString (XMLCSTR lpXMLString, XMLCSTR tag=nullptr, XMLResults *pResults=nullptr) |
| Parse an XML string and return the root of a XMLNode tree representing the string. More... | |
| static XMLNode | XMLNode::parseFile (XMLCSTR filename, XMLCSTR tag=nullptr, XMLResults *pResults=nullptr) |
| Parse an XML file and return the root of a XMLNode tree representing the file. More... | |
| static XMLNode | XMLNode::openFileHelper (XMLCSTR filename, XMLCSTR tag=nullptr) |
| Parse an XML file and return the root of a XMLNode tree representing the file. More... | |
| static XMLCSTR | XMLNode::getError (XMLError error) |
| this gives you a More... | |
| XMLSTR | XMLNode::createXMLString (int nFormat=1, int *pnSize=nullptr) const |
| user-friendly explanation of the parsing error More... | |
| XMLError | XMLNode::writeToFile (XMLCSTR filename, const char *encoding=nullptr, char nFormat=1) const |
| Save the content of an xmlNode inside a file. More... | |
| static char | XMLNode::setGlobalOptions (XMLCharEncoding characterEncoding=XMLNode::char_encoding_UTF8, char guessWideCharChars=1, char dropWhiteSpace=1, char removeCommentsInMiddleOfText=1) |
| Sets the global options for the conversions. More... | |
| static XMLCharEncoding | XMLNode::guessCharEncoding (void *buffer, int bufLen, char useXMLEncodingAttribute=1) |
| Guess the character encoding of the string (ascii, utf8 or shift-JIS) More... | |
Function Documentation
◆ createXMLString()
| XMLSTR XMLNode::createXMLString | ( | int | nFormat = 1, |
| int * | pnSize = nullptr |
||
| ) | const |
user-friendly explanation of the parsing error
Create an XML string starting from the current XMLNode. The returned string should be free'd using the "freeXMLString" function.
If nFormat==0, no formatting is required otherwise this returns an user friendly XML string from a given element with appropriate white spaces and carriage returns. if pnSize is given it returns the size in character of the string.
Definition at line 2661 of file xmlParser.cpp.
References _CXML, XMLNode::CreateXMLStringR(), XMLNode::d, dropWhiteSpace, XMLCHAR, and XMLSTR.
Referenced by XMLNode::writeToFile().
◆ getError()
this gives you a
Definition at line 83 of file xmlParser.cpp.
References _CXML, eXMLErrorBase64DataSizeIsNotMultipleOf4, eXMLErrorBase64DecodeBufferTooSmall, eXMLErrorBase64DecodeIllegalCharacter, eXMLErrorBase64DecodeTruncatedData, eXMLErrorCannotOpenWriteFile, eXMLErrorCannotWriteFile, eXMLErrorCharacterCodeAbove255, eXMLErrorCharConversionError, eXMLErrorEmpty, eXMLErrorFileNotFound, eXMLErrorFirstTagNotFound, eXMLErrorMissingEndTag, eXMLErrorMissingEndTagName, eXMLErrorMissingTagName, eXMLErrorNoElements, eXMLErrorNone, eXMLErrorNoXMLTagFound, eXMLErrorUnexpectedToken, eXMLErrorUnknownCharacterEntity, eXMLErrorUnmatchedEndClearTag, and eXMLErrorUnmatchedEndTag.
Referenced by mrpt::utils::CSimpleDatabase::loadFromXML(), mrpt::obs::VelodyneCalibration::loadFromXMLFile(), mrpt::obs::VelodyneCalibration::loadFromXMLText(), and XMLNode::openFileHelper().
◆ guessCharEncoding()
|
static |
Guess the character encoding of the string (ascii, utf8 or shift-JIS)
The "guessCharEncoding" function try to guess the character encoding. You most-probably will never have to use this function. It then returns the appropriate value of the global parameter "characterEncoding" described in the XMLNode::setGlobalOptions. The guess is based on the content of a buffer of length "bufLen" bytes that contains the first bytes (minimum 25 bytes; 200 bytes is a good value) of the file to be parsed. The XMLNode::openFileHelper function is using this function to automatically compute the value of the "characterEncoding" global parameter. There are several heuristics used to do the guess. One of the heuristic is based on the "encoding" attribute. The original XML specifications forbids to use this attribute to do the guess but you can still use it if you set "useXMLEncodingAttribute" to 1 (this is the default behavior and the behavior of most parsers). If an inconsistency in the encoding is detected, then the return value is "0".
Definition at line 3541 of file xmlParser.cpp.
References XMLNode::char_encoding_Big5, XMLNode::char_encoding_error, XMLNode::char_encoding_GB2312, XMLNode::char_encoding_GBK, XMLNode::char_encoding_legacy, XMLNode::char_encoding_ShiftJIS, XMLNode::char_encoding_UTF8, guessWideCharChars, mrpt::system::os::memcpy(), mmin(), myIsTextWideChar(), XML_isSPACECHAR, XML_utf8ByteTable, and xstrnicmp().
Referenced by XMLNode::openFileHelper().
◆ openFileHelper()
Parse an XML file and return the root of a XMLNode tree representing the file.
A very crude error checking is made. An attempt to guess the Char Encoding used in the file is made. The "openFileHelper" function reports to the screen all the warnings and errors that occurred during parsing of the XML file. This function also tries to guess char Encoding (UTF-8, ASCII or SHIT-JIS) based on the first 200 bytes of the file. Since each application has its own way to report and deal with errors, you should rather use the "parseFile" function to parse XML files and program yourself thereafter an "error reporting" tailored for your needs (instead of using the very crude "error reporting" mechanism included inside the "openFileHelper" function).
If the XML document is corrupted, the "openFileHelper" method will:
- display an error message on the console (or inside a messageBox for windows).
- stop execution (exit).
I strongly suggest that you write your own "openFileHelper" method tailored to your needs. If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "xmlParser.cpp" file.
- Parameters
-
filename the path of the XML file to parse. tag the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>).
Definition at line 529 of file xmlParser.cpp.
References _CXML, dropWhiteSpace, XMLResults::error, eXMLErrorFirstTagNotFound, eXMLErrorNone, mrpt::system::os::fclose(), XMLNode::getError(), XMLNode::guessCharEncoding(), guessWideCharChars, XMLResults::nColumn, XMLResults::nLine, XMLNode::parseFile(), removeCommentsInMiddleOfText, XMLNode::setGlobalOptions(), mrpt::system::os::sprintf(), xfopen(), and XMLCSTR.
◆ parseFile()
|
static |
Parse an XML file and return the root of a XMLNode tree representing the file.
The "parseFile" function parse an XML file and return the root of a XMLNode tree. The "opposite" of this function is the function "writeToFile" that re-creates an XML file from an XMLNode tree. If the XML document is corrupted, the "parseFile" method will initialize the "pResults" variable with some information that can be used to trace the error. If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "xmlParser.cpp" file.
- Parameters
-
filename the path to the XML file to parse tag the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>). pResults a pointer to a XMLResults variable that will contain some information that can be used to trace the XML parsing error. You can have a user-friendly explanation of the parsing error with the "getError" function.
Definition at line 2283 of file xmlParser.cpp.
References _CXML, mrpt::obs::gnss::b2, XMLNode::char_encoding_legacy, XMLNode::char_encoding_UTF8, XMLNode::emptyXMLNode, XMLResults::error, eXMLErrorCharConversionError, eXMLErrorEmpty, eXMLErrorFileNotFound, mrpt::system::os::fclose(), guessWideCharChars, myIsTextWideChar(), myWideCharToMultiByte(), XMLResults::nColumn, XMLResults::nLine, XMLNode::parseString(), SEEK_END, SEEK_SET, xfopen(), and XMLSTR.
Referenced by mrpt::utils::CSimpleDatabase::loadFromXML(), mrpt::obs::VelodyneCalibration::loadFromXMLFile(), and XMLNode::openFileHelper().
◆ parseString()
|
static |
Parse an XML string and return the root of a XMLNode tree representing the string.
The "parseString" function parse an XML string and return the root of a XMLNode tree. The "opposite" of this function is the function "createXMLString" that re-creates an XML string from an XMLNode tree. If the XML document is corrupted, the "parseString" method will initialize the "pResults" variable with some information that can be used to trace the error. If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "xmlParser.cpp" file.
- Parameters
-
lpXMLString the XML string to parse tag the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>). pResults a pointer to a XMLResults variable that will contain some information that can be used to trace the XML parsing error. You can have a user-friendly explanation of the parsing error with the "getError" function.
Definition at line 2216 of file xmlParser.cpp.
References CountLinesAndColumns(), XMLNode::emptyXMLNode, mrpt::obs::gnss::error, XML::error, XMLResults::error, eXMLErrorFirstTagNotFound, eXMLErrorMissingEndTag, eXMLErrorNoElements, eXMLErrorNone, eXMLErrorNoXMLTagFound, FALSE, XMLNode::getChildNode(), XMLNode::getName(), XMLNode::isEmpty(), XML::lpXML, XMLNode::nChildNode(), XMLResults::nColumn, XMLNode::nElement(), XML::nIndex, XML::nIndexMissigEndTag, XMLResults::nLine, XMLNode::ParseXMLElement(), TRUE, XMLCSTR, and xstricmp().
Referenced by mrpt::obs::VelodyneCalibration::loadFromXMLText(), and XMLNode::parseFile().
◆ setGlobalOptions()
|
static |
Sets the global options for the conversions.
The "setGlobalOptions" function allows you to change four global parameters that affect string & file parsing. First of all, you most-probably will never have to change these 3 global parameters.
- Parameters
-
guessWideCharChars If "guessWideCharChars"=1 and if this library is compiled in WideChar mode, then the XMLNode::parseFile and XMLNode::openFileHelper functions will test if the file contains ASCII characters. If this is the case, then the file will be loaded and converted in memory to WideChar before being parsed. If 0, no conversion will be performed. guessWideCharChars If "guessWideCharChars"=1 and if this library is compiled in ASCII/UTF8/char* mode, then the XMLNode::parseFile and XMLNode::openFileHelper functions will test if the file contains WideChar characters. If this is the case, then the file will be loaded and converted in memory to ASCII/UTF8/char* before being parsed. If 0, no conversion will be performed. characterEncoding This parameter is only meaningful when compiling in char* mode (multibyte character mode). In wchar_t* (wide char mode), this parameter is ignored. This parameter should be one of the three currently recognized encodings: XMLNode::encoding_UTF8, XMLNode::encoding_ascii, XMLNode::encoding_ShiftJIS. dropWhiteSpace In most situations, text fields containing only white spaces (and carriage returns) are useless. Even more, these "empty" text fields are annoying because they increase the complexity of the user's code for parsing. So, 99% of the time, it's better to drop the "empty" text fields. However The XML specification indicates that no white spaces should be lost when parsing the file. So to be perfectly XML-compliant, you should set dropWhiteSpace=0. A note of caution: if you set "dropWhiteSpace=0", the parser will be slower and your code will be more complex. removeCommentsInMiddleOfText To explain this parameter, let's consider this code: If removeCommentsInMiddleOfText=0, then we will have: If removeCommentsInMiddleOfText=1, then we will have:world >chu</a>","a");
- Returns
- "0" when there are no errors. If you try to set an unrecognized encoding then the return value will be "1" to signal an error.
- Note
- Sometime, it's useful to set "guessWideCharChars=0" to disable any conversion because the test to detect the file-type (ASCII/UTF8/char* or WideChar) may fail (rarely).
Definition at line 3501 of file xmlParser.cpp.
References XMLNode::char_encoding_Big5, XMLNode::char_encoding_GB2312, XMLNode::char_encoding_GBK, XMLNode::char_encoding_legacy, XMLNode::char_encoding_ShiftJIS, XMLNode::char_encoding_UTF8, characterEncoding, dropWhiteSpace, guessWideCharChars, removeCommentsInMiddleOfText, XML_ByteTable, XML_gb2312ByteTable, XML_gbk_big5_ByteTable, XML_legacyByteTable, XML_sjisByteTable, and XML_utf8ByteTable.
Referenced by XMLNode::openFileHelper().
◆ writeToFile()
| XMLError XMLNode::writeToFile | ( | XMLCSTR | filename, |
| const char * | encoding = nullptr, |
||
| char | nFormat = 1 |
||
| ) | const |
Save the content of an xmlNode inside a file.
If nFormat==0, no formatting is required otherwise this returns an user friendly XML string from a given element with appropriate white spaces and carriage returns. If the global parameter "characterEncoding==encoding_UTF8", then the "encoding" parameter is ignored and always set to "utf-8". If the global parameter "characterEncoding==encoding_ShiftJIS", then the "encoding" parameter is ignored and always set to "SHIFT-JIS". If "_XMLWIDECHAR=1", then the "encoding" parameter is ignored and always set to "utf-16". If no "encoding" parameter is given the "ISO-8859-1" encoding is used.
Definition at line 806 of file xmlParser.cpp.
References _CXML, XMLNode::char_encoding_ShiftJIS, XMLNode::char_encoding_UTF8, characterEncoding, XMLNode::createXMLString(), XMLNode::d, eXMLErrorCannotOpenWriteFile, eXMLErrorCannotWriteFile, eXMLErrorNone, mrpt::system::os::fclose(), mrpt::system::os::fprintf(), XMLNode::getChildNode(), XMLNode::isDeclaration(), xfopen(), XMLCHAR, and XMLSTR.
Referenced by mrpt::utils::CSimpleDatabase::saveAsXML().
