If you have suggestions about other useful tools send them to me. They can build upon these basic tools. I will include them (and credit of course!) in the archive.
Even if you don't have code, but an idea let me know - and I'll see if I can code it up for you, if I haven't already got it.
Now to the gory details. First an overview:
An SGML file is stored as a linked list. This list doesn't currently use VP list tools (tut tut) because it is ported from the classic and I have a platform independant list library that works with Linux. I do include the header PLists.H for you to use.
Each node in the list points to an SGMLBLOCK structure. The SGMLBLOCK structure indicates if this node is a tag or pure data. Note, the "level" of this node is stored in the list node and not the SGMLBLOCK structure for speed sakes. The level indicates the indentation level or the nested level whichever way you want to look at it. E.G. the HTML tag would be level 0, the HEAD inside it would be level 1.
Each SGMLBLOCK structure has a linked list of arguments which has a similar structure, an SGMLLINK which points to an SGMLARG structure.
To get the pointer to the SGMLBLOCK or SGMLARG structures from the SGMLLINK node, use NodeData() in PLists.H. sgmlblk = NodeData(link);
The tstlist.c file is an example program to demonstrate parsing of the list, and tools for finding specific tags/args etc. I have yet to update this with the latest tools - watch out for updates.
Each tool is listed and described (briefly) below.
| LoadSGML | lib/mlt/sgmlio/LoadSGML.00 |
SGMLIOERR LoadSGML(char *Filename,SGMLIO *SgmlIO_ptr,SGML *Sgml_ptr,SGMLERR *SgmlErr_ptr)
LoadSGML fills out Sgml_ptr with the address of the SGML list after loading file Filename. See Also: mlt/tstlist.c, FreeSGML | |
| ReadSGMLFile | lib/mlt/sgmlio/ReadSGMLFile.00 |
SGML ReadSGMLFile(SGMLIO Handle,STRING filename) ReadSGMLFile reads the file filename and returns an SGML handle. The SGMLIO handle is used to maintain buffers during the reading of the file. ReadSGMLFile is called from LoadSGML. See Also: mlt/tstlist.c, LoadSGML | |
| ReadSGMLBlock | lib/mlt/sgmlio/ReadSGMLBlock.00 |
SGMLBLOCK ReadBlock(SGMLIO IOHandle,void *src,unsigned long bufsize) ReadSGMLBlock is used to read read a block of data (be it a tag or data). It is called from ReadSGMLFile. It takes the IOHandle of the file being read, and one of two configurations for the src parameter. If the buffersize is 0. src is the FILE filehandle being read, otherwise it is the buffer pointer and the buffersize indicates its size. See Also: mlt/tstlist.c, LoadSGML | |
| NewSGMLHandle | lib/mlt/sgmlio/NewSGMLHandle.00 |
SGMLIO NewSGMLHandle(void) NewSGMLHandle is used to allocate an IO handle. See Also: mlt/tstlist.c, FreeSGMLHandle | |
| FreeSGMLHandle | lib/mlt/sgmlio/FreeSGMLHandle.00 |
void FreeSGMLHandle(SGMLIO) NewSGMLHandle is used to free an IO handle allocated with NewSGMLHandle. See Also: mlt/tstlist.c, NewSGMLHandle | |
| WriteSGMLFile | lib/mlt/sgmlio/WriteSGMLFile.00 |
SGMLIOERR WriteSGMLFile(SGML Sgml,SGMLIO Handle,STRING filename) WriteSGMLFile takes an SGML handle and writes it to the given filename. Right now, you must pass in an SGMLIO handle but it is used to return an error code at this point. It is not read. This will change in the future. See Also: mlt/tstlist.c, WriteSGMLBlock, WriteSGMLTag, WriteSubSGML | |
| WriteSGMLBlock | lib/mlt/sgmlio/WriteSGMLBlock.00 |
SGMLLINK WriteSGML(SGML Sgml,SGMLIO Handle,FILE *writefile,SGMLLINK link) WriteSGMLBlock is used to write a block of markup (SGMLBLOCK). It is called from WriteSGMLFile but could be used else where to save sections of a file. It takes an SGML handle and a link for a specific block of markup, and writes it to the given file descriptor. Right now, you must pass in an SGMLIO handle but it is used to return an error code at this point. It is not read. This will change in the future. See Also: mlt/tstlist.c, WriteSGMLFile, WriteSGMLBlock | |
| WriteSGMLTag | lib/mlt/sgmlio/WriteSGMLTag.00 |
void WriteSGMLTag(SGML Sgml,SGMLIO Handle,FILE *writefile,SGMLBLOCK blk) WriteSGMLTag is used to write a block of markup (SGMLBLOCK) that is an actual SGML tag (IE has < > around it). (Its args are also written) It is called from WriteSGMLBlock but could be used else where to save specific markup. It takes an SGML handle and the SGMLBLOCK structure for a specific block of markup, and writes it to the given file descriptor. Right now, you must pass in an SGMLIO handle but it is used to return an error code at this point. It is not read. This will change in the future. See Also: mlt/tstlist.c, WriteSGMLFile, WriteSGMLBlock | |
| WriteSubSGML | lib/mlt/sgmlio/WriteSubSGML.00 |
SGMLLINK WriteSubSGML(SGML Sgml,SGMLIO Handle,FILE *writefile,SGMLLINK link) WriteSubSGML is used to write a all the child blocks of a given markup block (SGMLBLOCK). (IE all the markup within <...> </...>). It recursively calls the above tools/functions. It is called from WriteSGMLBlock but could be used else where to save specific markup. It takes an SGML handle and the SGMLLINK for a specific block of markup, and writes it to the given file descriptor. Right now, you must pass in an SGMLIO handle but it is used to return an error code at this point. It is not read. This will change in the future. See Also: mlt/tstlist.c, WriteSGMLFile, WriteSGMLBlock | |
| SGMLIOERROR | lib/mlt/sgmlio/SGMLIOERROR.00 |
SGMLIOERR SGMLIOERROR(SGMLIO Handle) SGMLIOERROR is used to get the error field of an IO handle (SGMLIO). It is recommended that this tool/function is used instead of accessing the field directly. See Also: mlt/tstlist.c | |
| NewSGML | lib/mlt/sgml/NewSGML.00 |
SGML NewSGML() NewSGML allocates an SGML handle. The handle is basically a linked list. See Also: mlt/tstlist.c, FreeSGML, LoadSGML | |
| NewSGMLArg | lib/mlt/sgml/NewSGMLArg.00 |
SGMLARG NewSGMLArg() NewSGMLArg allocates an SGMLARG structure. See Also: mlt/tstlist.c, FreeSGMLArg | |
| NewSGMLBlock | lib/mlt/sgml/NewSGMLBlock.00 |
SGMLARG NewSGMLArg() NewSGMLArg allocates an SGMLBLOCK structure. See Also: mlt/tstlist.c, FreeSGMLBlock | |
| NewSGMLLink | SGML/SGMLLINKS.H |
SGMLLINK NewSGMLLink() NewSGMLLink allocates a linked list SGMLLINK structure. This is a macro and should probably be a tool..... SGMLLINK structures are used to tie together the SGML list and the arg lists for each SGML tag. See Also: mlt/tstlist.c, FreeSGMLLink, LinkData | |
| SGMLArgList | lib/mlt/sgml/SGMLArgList.00 |
SGMLERR SGMLArgList(SGMLBLOCK blk) SGMLArgList is used to convert an SGMLBLOCK that has been identified as a tag in to a tag with a list of args. This is used while reading a file. The data field of the block has the args when the SGMLBLOCK is passed in, but when the tool returns it has stripped the args from the data and created the linked list of args. See Also: mlt/tstlist.c, ReadSGMLBlock | |
| FreeSGML | lib/mlt/sgml/FreeSGML.00 |
void FreeSGML(SGML Sgml) FreeSGML frees an SGML list returned from NewSGML or LoadSGML. This will free everything associated with this SGML handle. Read the test code for an example. See Also: mlt/tstlist.c, NewSGML, LoadSGML | |
| RemoveSGMLLevel | lib/mlt/sgml/RemoveSGMLLevel.00 |
void RemoveSGMLLevel(SGMLLINK link) RemoveSGMLLevel will remove an SGMLLINK, and all the child tags. As each link, block and arg is removed it is freed. This is like doing a delete on a whole See Also: mlt/tstlist.c, FindSGML, FreeSGMLBlock, FreeSGMLLink, FreeSGMLArg | |
| FreeSGMLArg | lib/mlt/sgml/FreeSGMLArg.00 |
void FreeSGML(SGMLARG Sgmlarg) FreeSGMLArg frees an SGMLARG structure allocated with NewSGMLArg. See Also: mlt/tstlist.c, NewSGMLArg | |
| FreeSGMLBlock | lib/mlt/sgml/FreeSGMLBlock.00 |
void FreeSGML(SGMLBLOCK Sgml) FreeSGMLBlock frees an SGML block structure allocated with NewSGMLBlock. See Also: mlt/tstlist.c, NewSGMLBlock | |
| FreeSGMLBlock | lib/mlt/sgml/FreeSGMLBlock.00 |
void FreeSGML(SGMLBLOCK Sgml) FreeSGMLBlock frees an SGML block structure allocated with NewSGMLBlock. See Also: mlt/tstlist.c, NewSGMLBlock | |
| FreeSGMLLink | lib/mlt/sgml/FreeSGMLLink.00 |
void FreeSGML(SGML Sgml) FreeSGMLLink frees an SGML link that is used in the SGML list and argument list. See Also: mlt/tstlist.c, NewSGMLLink, LoadSGML | |
| FindTag | lib/mlt/sgml/FindTag.00 |
SGMLLINK FindTag(SGML Sgml,char *Name) FindTag returns a link containing the SGMLBLOCK structure with the name Name. NULL is returned if no tag exists with the given Name. Read the test code for an example. See Also: mlt/tstlist.c, FindNextTag, FindSGMLArg, SoftLib/PLists/PLists.H | |
| FindNextTag | lib/mlt/sgml/FindNextTag.00 |
SGMLLINK FindNextTag(SGMLLINK link,char *Name) Given a link, FindNextTag will find the next tag with the given Name. This can be used to find a TR following a TABLE eg: t = FindTag(sgml,"TABLE"); t = FindNextTag(t."TR"); Of course you should check t is not NULL in each case. See Also: mlt/tstlist.c, FindTag, FindSGMLArg, SoftLib/PLists/PLists.H | |
| SkipToNext | lib/mlt/sgml/SkipToNext.00 |
SGMLLINK SkipToNext(SGMLLINK link) Given a link, SkipToNext will find the next SGMLLINK at the same level, skipping over any tags that are considered children of the given link. You must check to see if the end of the list has been reached upon returning this function. See Also: mlt/tstlist.c, FindTag, FindSGMLArg, SoftLib/PLists/PLists.H | |
| FindSGMLArg | lib/mlt/sgml/FindSGMLArg.00 |
SGMLLINK FindSGMLArg(SGMLBLOCK blk,char *Name,char **Value) FindSGMLArg returns a link containing the SGMLARG structure for the argument named Name and the address of the value of the argument in Value. Read the test code for an example. See Also: mlt/tstlist.c, FindTag, FindNextTag, SoftLib/PLists/PLists.H | |
| Copy_SGML | lib/mlt/sgml/CopySGML.00 |
SGMLBLOCK Copy_Block(SGMLBLOCK blk) CopySGML duplicates an SGMLBLOCK structure returning a newly allocated copy. See Also: mlt/tstlist.c, FindTag, FindNextTag | |
| IsSGMLTag | lib/mlt/sgml/IsSGMLTag.00 |
int IsSGMLTag(SGMLLINK l) IsSGMLTag is used to determine if an SGMLBLOCK structure holds date for markup (< >), or contents. It is recommended that this tool/function is used instead of reading the SGMLBLOCK structure directly. It hides from the caller the details of whether an end tag exists or not. Returns 1 for a tag, 0 for data. See Also: mlt/tstlist.c, FindTag, FindNextTag | |
| MatchStartTag | lib/mlt/sgml/MatchStartTag.00 |
SGMLLINK MatchStartTag(SGML sgmlhandle,SGMLBLOCK sgmlblk,SGMLLINK prevlnk) MatchStartTag is used to find the starting tag of a given end tag. It works by searching back in the list for the last open tag at the correct level with the same name. For this reason the SGMLLINK of the end tag is passed in, and the SGMLLINK of the starting tag is returned. The SGMLBLOCK of the end tag is also passed in with the SGML handle. NULL is returned if no start tag is found but this shouldn't happen in a well structured file... See Also: mlt/tstlist.c, FindTag, FindNextTag | |
| SGMLLINKS | SGML/SGMLLINKS.H |
This file contains macros which access the SGML linked list. It
basically abstracts the linked list macro from PLists.H with
names to make the code more readable.
SGMLBLOCK LinkData(SGMLLINK)
LinkData returns the data structure associated with an SGMLLINK.
Although the return structure is an SGMLBLOCK, it could be an SGMLARG
and the caller must cast it if working on the argument list for and SGMLBLOCK.
void LinkBlock(SGMLLINK,SGMLBLOCK)
LinkBlock ties an SGMLBLOCK structure to an SGMLLINK so it can be stored in
a linked list.
void LinkArg(SGMLLINK,SGMLARG)
LinkArg ties an SGMLArg structure to an SGMLLINK so it can be stored in
a linked list.
SGMLLINK FirstLink(SGML)
FirstLink returns the first SGMLLINK in the SGML list.
SGMLLINK LastLink(SGML)
LastLink returns the first SGMLLINK in the SGML list.
SGMLLINK NxtLink(SGMLLINK)
NxtLink returns the next SGMLLINK in the SGML list.
SGMLLINK PrevLink(SGMLLINK)
PrevLink returns the previous SGMLLINK in the SGML list.
SGMLLINK InsertLink(SGML,SGMLLINK l,SGMLLINK p)
InsertLink inserts link l after link p in the list.
SGMLLINK AddHLink(SGML,SGMLLINK)
AddHLink adds the link to the head of the list.
SGMLLINK AddTLink(SGML,SGMLLINK) AddTLink adds the link to the tail of the list. See Also: mlt/tstlist.c, PLists.H | |
| PLists | tx/port/vp/Softlib/PLists/PLists.H |
|
The PLists header allows you to manipulate the linked list that makes the SGML
file. It will at some point be made to use the elate tools but currently doesn't.
It is not recommended that you try using the elate tools for lists instead of
these because the memory may have a different layout on different CPUs. The SGMLLINK datatype is defined as "Node *" so you can use node macros on it.
The macros available are (most are self explanatory):
Node *NxtNode(Node *)
Node *PrvNode(Node *)
Node *FirstNode(Node *)
Node *LastNode(Node *)
void *NodeData(Node *)
void SetData(Node *,void *)
SetSubLevel(Node *,long)
SubLevel(Node *)
IncLevel(Node *)
DecLevel(Node *)
Make sure you have "#define SUBTREES" somewhere, or you won't get the right structure definition and sublevel macros. Read the header and test code for details. | |
Questions? Drop the author an email.