   Copyright (C) 2001 The GNUpdate Project.

   This file documents the GNUpdate RDF Library (libgnurdf) v0.3.0.

Overview
********

   The libgnurdf (GNUpdate RDF) library provides quick and easy access
to RDF (XML Resource Description Format) files.

   Libgnurdf makes it easy to create, modify, and search RDF files from
any C/C++ (and soon Perl and Python) programs. GNUpdate uses this to
access its database and to generate queries for online package
databases running gnups.

Usage
*****

   The following C program parses an RDF file and prints out a list of
RDF descriptions, as well as the contents of the descriptions.

     #include <stdio.h>
     #include <stdlib.h>
     #include <gnurdf.h>

     int
     main(int argc, char **argv)
     {
         RdfSchema      *rdf;
         RdfDescription *description;
         RdfNamespace   *myNamespace;
         RdfElement     *element;
         char           *about, *value;
         char           *filename;

         if (argc < 2)
         {
             fprintf(stderr, "Usage: %s <file>\n", argv[0]);
             exit(1);
         }

         filename = argv[1];

         /* Read in the file. */
         rdf = rdfReadFile(filename);

         if (rdf == NULL)
         {
             fprintf(stderr, "Unable to open %s.\n", filename);
             exit(1);
         }

         /* Locate the namespace. */
         myNamespace = rdfGetNamespace(rdf, "urn:MyStuff:MyNamespace");

         if (myNamespace == NULL)
         {
             fprintf(stderr, "Namespace not found!\n");
             exit(1);
         }

         /* Loop through the descriptions. */
         for (description = rdfFirstDescription(rdf);
              description != NULL;
              description = rdfNextDescription(description))
         {
             about = rdfGetDescriptionAbout(rdf, description);

             printf("\tAbout: %s\n", about);

             free(about);

             for (element = rdfFirstProperty(description);
                  element != NULL;
                  element = rdfNextProperty(element))
             {
                 value = rdfGetElementValue(element);

                 printf("\t\tName:      %s\n",
                        rdfGetElementPropertyName(element));
                 printf("\t\tValue:     %s\n", value);
                 printf("\t\tNamespace: %s\n\n",
                        rdfGetNamespaceURI(rdfGetElementNamespace(element)));

                 free(value);
             }
         }

         /* Clean up. */
         rdfDestroySchema(rdf);

         return 0;
     }

Reference
*********

Macro Definitions
*****************

   * RDF_LEAF

     A string of text.

   * RDF_BAG

     A <RDF:Bag>.

   * RDF_SEQ

     A <RDF:Seq>.

   * RDF_ALT

     A <RDF:Alt>.

   * RDF_DESC

     A <RDF:Description>.

Functions
*********

Schema Functions
****************

   * Function: RdfSchema *rdfNewSchema(void)

     Creates and returns a new, blank RdfSchema.

   * Function: void rdfDestroySchema(RdfSchema *schema)

     Destroys an RdfSchema.

        - schema: The RdfSchema to destroy.

File I/O Functions
******************

   * Function: RdfSchema *rdfReadBuffer(char *buffer)

     Reads RDF from a buffer and returns a new RdfSchema. If the buffer
     does not contain valid RDF, NULL is returned.

        - buffer: The buffer containing the RDF.

   * Function: RdfSchema *rdfReadFile(const char *filename)

     Reads an RDF file and returns a new RdfSchema. If the filename
     does not exist, or is not a valid RDF file, NULL is returned.

        - filename: The filename to read in.

   * Function: void rdfWriteBuffer(RdfSchema *schema, char **buffer,
     int *size)

     Writes RDF to a string buffer.

        - schema: The document schema to write.

        - buffer: A pointer to the buffer to store the RDF in.

        - size: A pointer to an integer which will contain the new size
          of the buffer.

   * Function: void rdfWriteFile(RdfSchema *schema, const char
     *filename)

     Writes RDF to a file.

        - schema: The document schema to write.

        - filename: The name of the file to write to.

   * Function: void rdfSetCompressionLevel(RdfSchema *schema, int level)

     Sets the schema's gzip compression level.

        - schema: The document schema to compress.

        - level: The gzip compression level.

   * Function: int rdfGetCompressionLevel(RdfSchema *schema)

     Returns the gzip compression level of the schema.

        - schema: The document schema.

Namespace Functions
*******************

   * Function: RdfNamespace *rdfNewNamespace(RdfSchema *schema, const
     char *uri, const char *prefix)

     Creates and returns a new namespace with the specified URI and
     prefix.

     For example, to create a namespace such as the one used in the
     following tag:

          <SomeTag xmlns:myns="http://www.foo.com/myns">

     You would do:

          RdfNamespace *ns;

          ns = rdfNewNamespace(schema, "http://www.foo.com/myns", "myns");

        - schema: The document schema.

        - uri: The URI of the namespace.

        - prefix: The namespace prefix.

   * Function: RdfNamespace *rdfGetNamespace(RdfSchema *schema, const
     char *uri);

     Returns the namespace with the specified URI.

        - schema: The document schema.

        - uri: The URI of the namespace.

   * Function: RdfNamespace *rdfGetRdfNamespace(RdfSchema *schema)

     Returns the RDF namespace.

        - schema: The document schema.

   * Function: const char *rdfGetNamespaceURI(RdfNamespace *ns)

     Returns the URI of the specified namespace.

        - ns: The namespace.

   * Function: const char *rdfGetNamespacePrefix(RdfNamespace *ns)

     Returns the prefix of the specified namespace.

        - ns: The namespace.

Description Functions
*********************

   * Function: RdfDescription *rdfFirstDescription(RdfSchema *schema)

     Returns the first description in the schema.

        - schema: The schema containing the descriptions.

   * Function: RdfDescription *rdfNextDescription(RdfDescription *desc)

     Returns the next description in the schema.

        - desc: The previous description.

   * Function: RdfDescription *rdfAddDescription(RdfSchema *schema,
     const char *id, const char *about)

     Adds a description to the schema.

     Returns the new description.

        - schema: The schema to add the description to.

        - id: The id of the new description.

        - about: The about URI of the new description.

   * Function: RdfDescription *rdfGetDescriptionFromAbout(RdfSchema
     *schema, const char *about)

     Returns the description with the specified about URI.

        - schema: The schema containing the descriptions.

        - about: The about URI to search for.

   * Function: RdfDescription *rdfGetDescriptionFromId(RdfSchema
     *schema, const char *id)

     Returns the description with the specified ID.

        - schema: The schema containing the descriptions.

        - id: The ID to search for.

   * Function: void rdfSetDescriptionId(RdfDescription *desc, const
     char *id)

     Sets a description's ID.

        - desc: The description.

        - id: The new ID.

   * Function: char *rdfGetDescriptionId(RdfDescription *desc)

     Returns a description's ID.

     Note: The returned ID must be freed.

        - desc: The description containing the ID.

   * Function: void rdfSetDescriptionAbout(RdfDescription *desc, const
     char *about)

     Sets a description's About URI.

     If this finds an About or about attributes (in that order), it
     will set that attribute.  Otherwise, it will set the about
     attribute.

        - desc: The description.

        - about: The new About URI.

   * Function: char *rdfGetDescriptionAbout(RdfDescription *desc)

     Returns a description's About URI.

     Note: The returned About URI must be freed.

        - desc: The description containing the About URI.

Attribute Functions
*******************

   * Function: void rdfSetAttribute(RdfElement *element, const char
     *attname, const char *value)

     Sets an element's attribute.

        - element: The element containing the attribute.

        - attname: The name of the attribute.

        - value: The attribute's value.

   * Function: char *rdfGetAttribute(RdfElement *element, const char
     *attname)

     Returns an attribute's value.

     Note: The returned attribute must be freed.

        - element: The element containing the attribute.

        - attname: The name of the attribute.

   * Function: void rdfSetNsAttribute(RdfElement *element, const char
     *attname, const char *value, RdfNamespace *ns)

     Sets the value of an attribute in the specified namespace.

        - element: The element containing the attribute.

        - attname: The name of the attribute.

        - value: The attribute's value.

   * Function: char *rdfGetNsAttribute(RdfElement *element, const char
     *attname, RdfNamespace *ns)

     Returns the value of an attribute in the specified namespace.

     Note: The returned attribute must be freed.

        - element: The element containing the attribute.

        - attname: The name of the attribute.

        - ns: The namespace of the attribute.

Property Functions
******************

   * Function: int rdfGetProperty(RdfElement *parent, const char
     *property, RdfNamespace *ns, char **value, RdfElement **element)

     Returns the element or its value with the specified name in a
     description or container.

     To return only the property's value, pass a pointer to a string for
     value and NULL for element.

     Likewise, you can retrieve only the element by passing a pointer
     to a pointer of an RdfElement for element and NULL for value.

     If you wish to retrieve both the value and the element, pass a
     pointer to a string for value and a pointer to a pointer of an
     RdfElement to element.

     If the property found is a Bag container, RDF_BAG is returned.  If
     it's a Sequence container, RDF_SEQ is returned.  If it's an
     Alternate container, RDF_ALT is returned.  If it's an RDF
     description, RDF_DESC is returned.  If the property is a normal
     property, 0 is returned.  If the property was not found, -1 is
     returned.

        - parent: The description containing the property.

        - property: The name of the property to retrieve.

        - ns: The namespace of the property.

        - value: The returned value, unless NULL is passed.

        - element: The returned element, unless NULL is passed.

   * Function: RdfElement *rdfSetProperty(RdfElement *parent, const
     char *property, RdfNamespace *ns, const char *value)

     Sets the value of a property in a description or container.

     The new element is returned.

        - parent: The description or container which will hold the
          property.

        - property: The name of the property.

        - ns: The namespace of the property.

        - value: The property's value.

   * Function: RdfElement *rdfSetElement(RdfElement *parent, const char
     *property, RdfNamespace *ns, RdfElement *element)

     Sets the element of a property in a description or container.

     The element is returned.

        - parent: The description or container which will hold the
          property.

        - property: The name of the property.

        - ns: The namespace of the property.

        - element: The property's element.

   * Function: void rdfRemoveProperty(RdfElement *parent, const char
     *property, RdfNamespace *ns)

     Removes a property from a description or container.

        - parent: The description or container which holds the property.

        - property: The property's name.

        - ns: The property's namespace.

   * Function: void rdfRemoveElement(RdfElement *element)

     Removes an element from a description or container.

        - element: The element to remove.

Element Functions
*****************

   * Function: int rdfGetElementType(RdfElement *element)

     Returns the type of the specified element (see Definitions).
     If the type is unknown, this returns 0. If the element is NULL,
     this returns -1.

        - element: The element.

   * Function: char *rdfGetElementValue(RdfElement *element)

     Returns the value of the specified element.

     Note: The returned value must be freed.

        - element: The element.

   * Function: const char *rdfGetElementPropertyName(RdfElement
     *element)

     Returns the name of the specified element.

        - element: The element.

   * Function: RdfNamespace *rdfGetElementNamespace(RdfElement *element)

     Returns the namespace of the specified element.

        - element: The element.

   * Function: void rdfSetElementValue(RdfElement *element, const char
     *value)

     Sets the value of the specified namespace.

        - element: The element.

        - value: The new value for the element.

   * Function: void rdfSetElementResource(RdfElement *element, const
     char *uri)

     Sets an element's resource.

        - element: The element.

        - uri: The URI of the resource.

   * Function: char *rdfGetElementResource(RdfElement *element)

     Returns an element's resource.

     Note: The returned resource must be freed!

        - element: The element.

   * Function: RdfSchema *rdfGetElementSchema(RdfElement *element)

     Returns an element's parent schema.

        - element: The element.

Container Functions
*******************

Bag Containers
**************

   * Function: RdfBag *rdfCreateBag(RdfElement *parent, const char
     *property, RdfNamespace *ns)

     Creates and returns a new bag container.

        - parent: The parent which will hold the bag container.

        - property: The name of the bag container's property.

        - ns: The bag container's namespace.

   * Function: RdfElement *rdfBagAddValue(RdfBag *bag, const char
     *property, RdfNamespace *ns, const char *value, RdfElement
     *element)

     Adds and returns a property to the bag container.

        - bag: The bag container.

        - property: The property's name.

        - ns: The property's namespace.

        - value: The value of the property, if not NULL.

        - element: The property's element, if not NULL.

Sequence Containers
*******************

   * Function: RdfSeq *rdfCreateSeq(RdfElement *parent, const char
     *property, RdfNamespace *ns)

     Creates and returns a new sequence container.

        - parent: The parent  which will hold the sequence container.

        - property: The name of the sequence container's property.

        - ns: The sequence container's namespace.

   * Function: RdfElement *rdfSeqAddValue(RdfSeq *seq, const char
     *property, RdfNamespace *ns, const char *value, RdfElement
     *element)

     Adds and returns a property to the sequence container.

        - seq: The sequence container.

        - property: The property's name.

        - ns: The property's namespace.

        - value: The value of the property, if not NULL.

        - element: The property's element, if not NULL.

Alternate Containers
********************

   * Function: RdfAlt *rdfCreateAlt(RdfElement *parent, const char
     *property, RdfNamespace *ns)

     Creates and returns a new alternative container.

        - parent: The parent which will hold the alternative container.

        - property: The name of the alternative container's property.

        - ns: The alternative container's namespace.

   * Function: RdfElement *rdfAltAddValue(RdfAlt *alt, const char
     *property, RdfNamespace *ns, const char *value, RdfElement
     *element)

     Adds a property to the alternative container.

     Returns the new element.

        - alt: The alternative container.

        - property: The property's name.

        - ns: The property's namespace.

        - value: The value of the property, if not NULL.

        - element: The property's element, if not NULL.

Search Functions
****************

   * Function: RdfElement *rdfFindElementWithValue(RdfContainer
     *container, const char *value)

     Returns the element with the specified value, or NULL if not found.

        - container: The container to search.

        - value: The value to search for.

   * Function: RdfElement *rdfFindElementWithResource(RdfContainer
     *container, const char *resource)

     Returns the element with the specified resource, or NULL if not
     found.

        - container: The container to search.

        - resource: The resource to search for.

Iteration Functions
*******************

   * Function: RdfElement *rdfFirstProperty(RdfContainer *container)

     Returns the first property in a container.

        - container: The container containing the properties.

   * Function: RdfElement *rdfNextProperty(RdfElement *element)

     Returns the previous property in the container.

        - element: The previuos element in the container.

Miscellaneous Functions
***********************

   * Function: void rdfCleanupParser()

     Cleans up the parser

     This function is called automatically upon completion of the
     program.  Only call it if you are absolutely done with the library
     ahead of time and want to free up some memory.