[freehaven-dev] how to use tags.c ?

[dmolnar@belegost.mit.edu]

Hey Roger,

Not a specific question, just a "do I have this right" for the tag parser
in /src/haven/tags.c . Sent to the list in case it's useful for anyone else. 

-------

The idea here is that I want to take a file and figure out what tags of
the form <TAG> ... </TAG> exist, and what exactly goes between each tag.
So we have some (tag, content) pairs. These are stored as a
struct of type "tag_t", which is a node in a linked list of tags.
Each tag has a string associated with it. 

The function "build_tag_list_from_file" does exactly what it says.
A string filename goes in, and then the parser works its magic and
a tag_t comes out.

So if I have a file which looks like :

	<FOO>  blah </FOO>
	<BAR>  halb </BAR>
	<QUZ> want eat Moon </QUZ>

running "build_tag_list_from_file" on will return a pointer to a
tag_t struct  which identifies itself as tag "FOO", has as contents the
string "blah", and a pointer to a next tag. If I follow that pointer, I'll
get to "BAR", and so on. 

If I know the exact name of the tag I am looking for in a tag_t list, then
I use the function "get_tag" on the tag_t. Given the name of the tag,
it searches through the tag_t and returns the contents associated
with that tag.

So if the file above was named "parseme", I could say

tag_t parsed;
char* what_does_quz_want;
parsed = build_tag_list_from_file("parseme");
what_does_quz_want = get_tag(parsed, "QUZ");

and then 

what_does_quz_want = "want eat Moon"

In the comm module for sending, we get the message over a socket from
haven. We process it and then place the message in a file somewhere. Then
we call "build_tag_list_from_file" on the message, and get a tag_t
pointing to the first tag in the message.

Then the comm needs to know what kind of message it is sending (broadcast
or directed), so it calls get_tag(message, "TYPE"). Then it may call
something like get_tag(message, "DESTINATION") or otherwise switch off the
message type.

Thanks, 
-David