Instrument Neutral Distributed Interface INDI  2.0.0
Typedefs | Functions
lilxml.h File Reference

A little DOM-style library to handle parsing and processing an XML file. More...

#include <stdio.h>

Go to the source code of this file.

Typedefs

typedef struct xml_att_ XMLAtt
 
typedef struct xml_ele_ XMLEle
 
typedef struct LilXML_ LilXML
 

Functions

LilXMLnewLilXML ()
 Create a new lilxml parser. More...
 
void delLilXML (LilXML *lp)
 Delete a lilxml parser. More...
 
void delXMLEle (XMLEle *e)
 delXMLEle Delete XML element. More...
 
XMLEle ** parseXMLChunk (LilXML *lp, char *buf, int size, char errmsg[])
 Process an XML chunk. More...
 
XMLElereadXMLEle (LilXML *lp, int c, char errmsg[])
 Process an XML one char at a time. More...
 
XMLAttfindXMLAtt (XMLEle *e, const char *name)
 Find an XML attribute within an XML element. More...
 
XMLElefindXMLEle (XMLEle *e, const char *tag)
 Find an XML element within an XML element. More...
 
XMLElenextXMLEle (XMLEle *ep, int first)
 Iterate an XML element for a list of nesetd XML elements. More...
 
XMLAttnextXMLAtt (XMLEle *ep, int first)
 Iterate an XML element for a list of XML attributes. More...
 
XMLEleparentXMLEle (XMLEle *ep)
 Return the parent of an XML element. More...
 
XMLEleparentXMLAtt (XMLAtt *ap)
 Return the parent of an XML attribute. More...
 
char * tagXMLEle (XMLEle *ep)
 Return the tag of an XML element. More...
 
char * pcdataXMLEle (XMLEle *ep)
 Return the pcdata of an XML element. More...
 
char * nameXMLAtt (XMLAtt *ap)
 Return the name of an XML attribute. More...
 
char * valuXMLAtt (XMLAtt *ap)
 Return the value of an XML attribute. More...
 
int pcdatalenXMLEle (XMLEle *ep)
 Return the number of characters in pcdata in an XML element. More...
 
int nXMLEle (XMLEle *ep)
 Return the number of nested XML elements in a parent XML element. More...
 
int nXMLAtt (XMLEle *ep)
 Return the number of XML attributes in a parent XML element. More...
 
XMLEleaddXMLEle (XMLEle *parent, const char *tag)
 add an element with the given tag to the given element. parent can be NULL to make a new root. More...
 
XMLElesetXMLEleTag (XMLEle *ep, const char *tag)
 Update the tag of an element. More...
 
void editXMLEle (XMLEle *ep, const char *pcdata)
 set the pcdata of the given element More...
 
XMLAttaddXMLAtt (XMLEle *ep, const char *name, const char *value)
 Add an XML attribute to an existing XML element. More...
 
void rmXMLAtt (XMLEle *ep, const char *name)
 Remove an XML attribute from an XML element. More...
 
void editXMLAtt (XMLAtt *ap, const char *str)
 change the value of an attribute to str. More...
 
char * entityXML (char *str)
 return a string with all xml-sensitive characters within the passed string replaced with their entity sequence equivalents. N.B. caller must use the returned string before calling us again. Warning: This will sometime fail in impredictible way when used from multiple thread contexts More...
 
const char * findXMLAttValu (XMLEle *ep, const char *name)
 Find an XML element's attribute value. More...
 
XMLEleshallowCloneXMLEle (XMLEle *ele)
 return a surface copy of a node. Don't copy childs or cdata. More...
 
XMLElecloneXMLEle (XMLEle *ep, int(*replace)(void *self, XMLEle *source, XMLEle **replace), void *self)
 clone (deep) a xmlEle. Optional replacement function can be passed, to replace a whole subtree instead of copying More...
 
XMLElereadXMLFile (FILE *fp, LilXML *lp, char errmsg[])
 Handy wrapper to read one xml file. More...
 
void prXMLEle (FILE *fp, XMLEle *e, int level)
 Print an XML element. More...
 
size_t sprXMLEle (char *s, XMLEle *ep, int level)
 sample print ep to string s. N.B. s must be at least as large as that reported by sprlXMLEle()+1. N.B. set level = 0 on first call. More...
 
size_t sprlXMLEle (XMLEle *ep, int level)
 return number of bytes in a string guaranteed able to hold result of sprXLMEle(ep) (sans trailing \0@). N.B. set level = 0 on first call. More...
 
size_t sprXMLCDataOffset (XMLEle *root, XMLEle *child, int level)
 return exact position of cdata of child in printed representation of root N.B. set level = 0 on first call. More...
 
void indi_xmlMalloc (void *(*newmalloc)(size_t size), void *(*newrealloc)(void *ptr, size_t size), void(*newfree)(void *ptr))
 

Detailed Description

A little DOM-style library to handle parsing and processing an XML file.

It only handles elements, attributes and pcdata content. <! ... > and <? ... > are silently ignored. pcdata is collected into one string, sans leading whitespace first line.
The following is an example of a cannonical usage for the lilxml library. Initialize a lil xml context and read an XML file in a root element.

#include <lilxml.h>
LilXML *lp = newLilXML();
char errmsg[1024];
XMLEle *root, *ep;
int c;
while ((c = fgetc(stdin)) != EOF) {
root = readXMLEle (lp, c, errmsg);
if (root)
break;
if (errmsg[0])
error ("Error: %s\n", errmsg);
}
// print the tag and pcdata content of each child element within the root
for (ep = nextXMLEle (root, 1); ep != NULL; ep = nextXMLEle (root, 0))
printf ("%s: %s\n", tagXMLEle(ep), pcdataXMLEle(ep));
// finished with root element and with lil xml context
delXMLEle (root);
delLilXML (lp);
LilXML * newLilXML()
Create a new lilxml parser.
Definition: lilxml.cpp:150
char * pcdataXMLEle(XMLEle *ep)
Return the pcdata of an XML element.
Definition: lilxml.cpp:606
char * tagXMLEle(XMLEle *ep)
Return the tag of an XML element.
Definition: lilxml.cpp:600
XMLEle * readXMLEle(LilXML *lp, int newc, char ynot[])
Process an XML one char at a time.
Definition: lilxml.cpp:385
XMLEle * nextXMLEle(XMLEle *ep, int init)
Iterate an XML element for a list of nesetd XML elements.
Definition: lilxml.cpp:555
void delXMLEle(XMLEle *ep)
delXMLEle Delete XML element.
Definition: lilxml.cpp:167
void delLilXML(LilXML *lp)
Delete a lilxml parser.
Definition: lilxml.cpp:159
A little DOM-style library to handle parsing and processing an XML file.
@ error
throw a parse_error exception in case of a tag

Definition in file lilxml.h.

Typedef Documentation

◆ LilXML

typedef struct LilXML_ LilXML

Definition at line 1 of file lilxml.h.

◆ XMLAtt

typedef struct xml_att_ XMLAtt

Definition at line 1 of file lilxml.h.

◆ XMLEle

typedef struct xml_ele_ XMLEle

Definition at line 1 of file lilxml.h.

Function Documentation

◆ addXMLAtt()

XMLAtt* addXMLAtt ( XMLEle ep,
const char *  name,
const char *  value 
)

Add an XML attribute to an existing XML element.

Parameters
eppointer to an XML element
namethe name of the XML attribute to add.
valuethe value of the XML attribute to add.

Definition at line 706 of file lilxml.cpp.

◆ addXMLEle()

XMLEle* addXMLEle ( XMLEle parent,
const char *  tag 
)

add an element with the given tag to the given element. parent can be NULL to make a new root.

Returns
if parent is NULL, a new root is returned, otherwise, parent is returned.

Definition at line 670 of file lilxml.cpp.

◆ cloneXMLEle()

XMLEle* cloneXMLEle ( XMLEle ep,
int(*)(void *self, XMLEle *source, XMLEle **replace)  replace,
void *  self 
)

clone (deep) a xmlEle. Optional replacement function can be passed, to replace a whole subtree instead of copying

Parameters
elethe original tree
replacefunction which can provide replacement. Return 1 & set replace for replacement. Optional
selfadditional value passed to replace function
Returns
a new independant node

Definition at line 493 of file lilxml.cpp.

◆ delLilXML()

void delLilXML ( LilXML lp)

Delete a lilxml parser.

Parameters
lpa pointer to a lilxml parser to be deleted.

Definition at line 159 of file lilxml.cpp.

◆ delXMLEle()

void delXMLEle ( XMLEle e)

delXMLEle Delete XML element.

Parameters
ePointer to XML element to delete. If nullptr, no action is taken.

Definition at line 167 of file lilxml.cpp.

◆ editXMLAtt()

void editXMLAtt ( XMLAtt ap,
const char *  str 
)

change the value of an attribute to str.

Parameters
appointer to XML attribute
strnew attribute value

Definition at line 745 of file lilxml.cpp.

◆ editXMLEle()

void editXMLEle ( XMLEle ep,
const char *  pcdata 
)

set the pcdata of the given element

Parameters
eppointer to an XML element.
pcdatapcdata to set.

Definition at line 698 of file lilxml.cpp.

◆ entityXML()

char* entityXML ( char *  str)

return a string with all xml-sensitive characters within the passed string replaced with their entity sequence equivalents. N.B. caller must use the returned string before calling us again. Warning: This will sometime fail in impredictible way when used from multiple thread contexts

Definition at line 975 of file lilxml.cpp.

◆ findXMLAtt()

XMLAtt* findXMLAtt ( XMLEle e,
const char *  name 
)

Find an XML attribute within an XML element.

Parameters
ea pointer to the XML element to search.
namethe attribute name to search for.
Returns
A pointer to the XML attribute if found or NULL on failure.

Definition at line 524 of file lilxml.cpp.

◆ findXMLAttValu()

const char* findXMLAttValu ( XMLEle ep,
const char *  name 
)

Find an XML element's attribute value.

Parameters
epa pointer to an XML element.
namethe name of the XML attribute to retrieve its value.
Returns
the value string of an XML element on success. NULL on failure.

Definition at line 644 of file lilxml.cpp.

◆ findXMLEle()

XMLEle* findXMLEle ( XMLEle e,
const char *  tag 
)

Find an XML element within an XML element.

Parameters
ea pointer to the XML element to search.
tagthe element tag to search for.
Returns
A pointer to the XML element if found or NULL on failure.

Definition at line 537 of file lilxml.cpp.

◆ indi_xmlMalloc()

void indi_xmlMalloc ( void *(*)(size_t size)  newmalloc,
void *(*)(void *ptr, size_t size)  newrealloc,
void(*)(void *ptr)  newfree 
)

◆ nameXMLAtt()

char* nameXMLAtt ( XMLAtt ap)

Return the name of an XML attribute.

Parameters
apa pointer to an XML attribute.
Returns
the name string of the attribute.

Definition at line 618 of file lilxml.cpp.

◆ newLilXML()

LilXML* newLilXML ( )

Create a new lilxml parser.

Returns
a pointer to the lilxml parser on success. NULL on failure.

Definition at line 150 of file lilxml.cpp.

◆ nextXMLAtt()

XMLAtt* nextXMLAtt ( XMLEle ep,
int  first 
)

Iterate an XML element for a list of XML attributes.

Parameters
epa pointer to the XML element to iterate.
firstthe index of the starting XML attribute. Pass 1 to start iteration from the beginning of the XML element. Pass 0 to get the next attribute thereater.
Returns
On success, a pointer to the next XML attribute is returned. NULL when there are no more attributes.

Definition at line 572 of file lilxml.cpp.

◆ nextXMLEle()

XMLEle* nextXMLEle ( XMLEle ep,
int  first 
)

Iterate an XML element for a list of nesetd XML elements.

Parameters
epa pointer to the XML element to iterate.
firstthe index of the starting XML element. Pass 1 to start iteration from the beginning of the XML element. Pass 0 to get the next element thereater.
Returns
On success, a pointer to the next XML element is returned. NULL when there are no more elements.

Definition at line 555 of file lilxml.cpp.

◆ nXMLAtt()

int nXMLAtt ( XMLEle ep)

Return the number of XML attributes in a parent XML element.

Parameters
epa pointer to an XML element.
Returns
the number of XML attributes within the XML element.

Definition at line 636 of file lilxml.cpp.

◆ nXMLEle()

int nXMLEle ( XMLEle ep)

Return the number of nested XML elements in a parent XML element.

Parameters
epa pointer to an XML element.
Returns
the number of nested XML elements.

Definition at line 630 of file lilxml.cpp.

◆ parentXMLAtt()

XMLEle* parentXMLAtt ( XMLAtt ap)

Return the parent of an XML attribute.

Returns
a pointer to the XML element parent.

Definition at line 592 of file lilxml.cpp.

◆ parentXMLEle()

XMLEle* parentXMLEle ( XMLEle ep)

Return the parent of an XML element.

Returns
a pointer to the XML element parent.

Definition at line 586 of file lilxml.cpp.

◆ parseXMLChunk()

XMLEle** parseXMLChunk ( LilXML lp,
char *  buf,
int  size,
char  errmsg[] 
)

Process an XML chunk.

Parameters
lpa pointer to a lilxml parser.
bufbuffer to process.
sizesize of buf
errmsga buffer to store error messages if an error in parsing is encountered.
Returns
return a pointer to a NULL terminated array of parsed XML elements. An array of size 1 with on a NULL element means there is nothing to parse or a parsing is still in progress. A NULL pointer may be returned if a parsing error occurs. Check errmsg for errors if NULL is returned.

Definition at line 215 of file lilxml.cpp.

◆ pcdatalenXMLEle()

int pcdatalenXMLEle ( XMLEle ep)

Return the number of characters in pcdata in an XML element.

Parameters
epa pointer to an XML element.
Returns
the length of the pcdata string.

Definition at line 612 of file lilxml.cpp.

◆ pcdataXMLEle()

char* pcdataXMLEle ( XMLEle ep)

Return the pcdata of an XML element.

Parameters
epa pointer to an XML element.
Returns
the pcdata string on success.

Definition at line 606 of file lilxml.cpp.

◆ prXMLEle()

void prXMLEle ( FILE *  fp,
XMLEle e,
int  level 
)

Print an XML element.

Parameters
fpa pointer to FILE where the print output is directed.
ethe XML element to print.
levelthe printing level, set to 0 to print the whole element.

Definition at line 844 of file lilxml.cpp.

◆ readXMLEle()

XMLEle* readXMLEle ( LilXML lp,
int  c,
char  errmsg[] 
)

Process an XML one char at a time.

Parameters
lpa pointer to a lilxml parser.
cone character to process.
errmsga buffer to store error messages if an error in parsing is encounterd.
Returns
When the function parses a complete valid XML element, it will return a pointer to the XML element. A NULL is returned when parsing the element is still in progress, or if a parsing error occurs. Check errmsg for errors if NULL is returned.

Definition at line 385 of file lilxml.cpp.

◆ readXMLFile()

XMLEle* readXMLFile ( FILE *  fp,
LilXML lp,
char  errmsg[] 
)

Handy wrapper to read one xml file.

Parameters
fppointer to FILE to read.
lppointer to lilxml parser.
errmsga buffer to store error messages on failure.
Returns
root element else NULL with report in errmsg[].

Definition at line 653 of file lilxml.cpp.

◆ rmXMLAtt()

void rmXMLAtt ( XMLEle ep,
const char *  name 
)

Remove an XML attribute from an XML element.

Parameters
eppointer to an XML element.
namethe name of the XML attribute to remove

Definition at line 715 of file lilxml.cpp.

◆ setXMLEleTag()

XMLEle* setXMLEleTag ( XMLEle ep,
const char *  tag 
)

Update the tag of an element.

Parameters
eppointer to an XML element
tagthe new tag value to set

Definition at line 688 of file lilxml.cpp.

◆ shallowCloneXMLEle()

XMLEle* shallowCloneXMLEle ( XMLEle ele)

return a surface copy of a node. Don't copy childs or cdata.

Returns
a new independant node

Definition at line 731 of file lilxml.cpp.

◆ sprlXMLEle()

size_t sprlXMLEle ( XMLEle ep,
int  level 
)

return number of bytes in a string guaranteed able to hold result of sprXLMEle(ep) (sans trailing \0@). N.B. set level = 0 on first call.

Definition at line 922 of file lilxml.cpp.

◆ sprXMLCDataOffset()

size_t sprXMLCDataOffset ( XMLEle root,
XMLEle child,
int  level 
)

return exact position of cdata of child in printed representation of root N.B. set level = 0 on first call.

Definition at line 930 of file lilxml.cpp.

◆ sprXMLEle()

size_t sprXMLEle ( char *  s,
XMLEle ep,
int  level 
)

sample print ep to string s. N.B. s must be at least as large as that reported by sprlXMLEle()+1. N.B. set level = 0 on first call.

Returns
return length of resulting string (sans trailing \0@)

Definition at line 874 of file lilxml.cpp.

◆ tagXMLEle()

char* tagXMLEle ( XMLEle ep)

Return the tag of an XML element.

Parameters
epa pointer to an XML element.
Returns
the tag string.

Definition at line 600 of file lilxml.cpp.

◆ valuXMLAtt()

char* valuXMLAtt ( XMLAtt ap)

Return the value of an XML attribute.

Parameters
apa pointer to an XML attribute.
Returns
the value string of the attribute.

Definition at line 624 of file lilxml.cpp.