


libraptor(3)                                         libraptor(3)


NAME
       libraptor - Raptor RDF parser and serializer library

SYNOPSIS
       #include <raptor.h>

       raptor_init();
       raptor_parser *p=raptor_new_parser("rdfxml");
       raptor_set_statement_handler(p,NULL,print_triples);
       raptor_uri *file_uri=raptor_new_uri("http://example.org/");
       raptor_parse_file(p,file_uri,base_uri);
       raptor_parse_uri(p,uri,NULL);
       raptor_free_parser(p);
       raptor_free_uri(file_uri);
       raptor_finish();

       cc file.c -lraptor

DESCRIPTION
       The  Raptor library provides a high-level interface to a set of parsers
       and serializers that  generate  Resource  Description  Framework  (RDF)
       triples by parsing syntaxes or serialize the triples into syntaxes.

       The  supported parsing syntaxes are RDF/XML, N-Triples, Turtle, RSS tag
       soup including Atom 0.3 and the serializing syntaxes  are  RDF/XML,  N-
       Triples and RSS 1.0.  The RDF/XML parser can use either expat or libxml
       XML parsers for providing the SAX event stream.  The library  functions
       are arranged in an object-oriented style with constructors, destructors
       and method calls.  The statements and error messages are delivered  via
       callback functions.

       Raptor  contains  a URI-reference parsing and resolving (not retrieval)
       class (raptor_uri) sufficient for dealing  with  URI-references  inside
       RDF.   This  functionality is modular and can be transparently replaced
       with another existing and compatible URI implementation.

       It also provides a URI-retrieval class (raptor_www) for wrapping exist-
       ing library such as libcurl, libxml2 or BSD libfetch that provides full
       or partial retrieval of data from URIs and an  I/O  stream  abstraction
       (raptor_iostream) for supportin serializing to a variety of outputs.

       Raptor  uses  Unicode  strings  for RDF literals and URIs and preserves
       them throughout the library.  It uses the UTF-8 encoding of Unicode  at
       the  API  for  passing in or returning Unicode strings.  It is intended
       that the preservation of Unicode for URIs will  support  International-
       ized  Resource Identifiers (IRIs) which are still under development and
       standardisation.

LIBRARY INITIALISATION AND CLEANUP
       raptor_init()

       raptor_finish()
              Initialise and cleanup the library.  These must be called before
              any raptor class such as raptor_parser, raptor_uri is created or



                            2008-06-19                          1





libraptor(3)                                         libraptor(3)


              used.

PARSER CLASS
       This class provides the functionality  of  turning  syntaxes  into  RDF
       triples - RDF parsing.

PARSER CONSTRUCTORS
       raptor_parser* raptor_new_parser(name)
              Create  a new raptor parser object for the parser with name name
              currently either "rdfxml", "turtle" or  "rss-tag-soup"  for  the
              RSS Tag Soup parser.

       raptor_parser*   raptor_new_parser_for_content(raptor_uri   *uri,
       const  char     *mime_type, const unsigned char  *buffer,  size_t  len,
       const  unsigned  char *identifier)
              Create a new raptor parser object for a syntax identified by URI
              uri, MIME type mime_type, some initial content  buffer  of  size
              len  or  content  with  identifier  identifier.   See  the  rap-
              tor_guess_parser_name description for further details.

PARSER DESTRUCTOR
       void raptor_free_parser(raptor_parser *parser)
              Destroy a Raptor parser object.

PARSER MESSAGE CALLBACK METHODS
       Several methods can be registered for the parser that  return  a  vari-
       able-argument  message  in the style of printf(3).  These also return a
       raptor_locator that can contain URI, file, line, column and byte counts
       of where the message is about. This structure can be used with the rap-
       tor_format_locator, raptor_print_locator functions below or the  struc-
       tures fields directly, which are defined in raptor.h

       void  raptor_set_fatal_error_handler(raptor_parser*  parser,  void
       *user_data, raptor_message_handler handler)
              Set the parser fatal error handler callback.

       void  raptor_set_error_handler(raptor_parser*  parser,  void
       *user_data, rap- tor_message_handler handler)
              Set the parser non-fatal error handler callback.

       void  raptor_set_warning_handler(raptor_parser*  parser, void
       *user_data, rap- tor_message_handler handler)
              Set the parser warning message handler callback.

       raptor_set_namespace_handler(raptor_parser*   parser,  void*
       user_data,  rap- tor_namespace_handler handler)
              Set the namespace declaration handler callback.

PARSER STATEMENT CALLBACK METHOD
       The parser allows the registration of a callback function to return the
       statements to the application.

       void raptor_set_statement_handler(raptor_parser* parser, void
       *user_data, rap- tor_statement_handler handler)



                            2008-06-19                          2





libraptor(3)                                         libraptor(3)


              Set the statement callback function for the  parser.   The  rap-
              tor_statement  structure  is  defined  in  raptor.h and includes
              fields for the subject,  predicate,  object  of  the  statements
              along  with their types and for literals, language and datatype.

PARSER PARSING METHODS
       These methods perform the entire parsing  in  one  method.   Statements
       warnings,  errors  and  fatal  errors  are delivered via the registered
       statement, error etc. handler functions.

       In both of these methods, the base URI  is  required  for  the  RDF/XML
       parser  (name  "rdfxml")  and  Turtle  parser  (name "turtle").  The N-
       Triples parser (name "ntriples") or RSS Tag Soup parser (name "rss-tag-
       soup") do not use this.

       int  raptor_parse_file(raptor_parser*  parser,   raptor_uri  *uri,
       raptor_uri *base_uri)
              Parse the given filename (a URI like file:filename) according to
              the optional base URI base_uri.  If uri is NULL, read from stan-
              dard input and base_uri is then required.

       int  raptor_parse_file_stream(raptor_parser* parser, FILE* stream,
       const char* filename, raptor_uri *base_uri)
              Parse  the  given  C  FILE*  stream  according  to  the base URI
              base_uri (required).  filename is optional and if given, is used
              for error messages via the raptor_locator structure.

       int   raptor_parse_uri(raptor_parser*  parser,   raptor_uri*  uri,
       raptor_uri *base_uri)
              Parse the URI according to the base URI base_uri, or NULL if not
              needed.  If no base URI is given, the uri is used.  This  method
              depends  on  the  raptor_www  subsystem  (see  WWW Class section
              below) and an existing underlying URI  retrieval  implementation
              such as libcurl, libxml or BSD libfetch to retrieve the content.

PARSER CHUNKED PARSING METHODS
       These methods perform the parsing  in  parts  by  working  on  multiple
       chunks  of  memory  passed  by  the  application.  Statements warnings,
       errors and fatal errors are delivered  via  the  registered  statement,
       error etc. handler functions.

       int raptor_start_parse(raptor_parser* parser, const char *uri)
              Start  a  parse of chunked content with the base URI uri or NULL
              if not needed.  The base URI is required for the RDF/XML  parser
              (name  "rdfxml")  and  Turtle  parser  (name  "turtle").  The N-
              Triples parser (name "ntriples") or RSS Tag  Soup  parser  (name
              "rss-tag-soup") do not use this.

       int  raptor_parse_chunk(raptor_parser*  parser,   const unsigned char
       *buffer, size_t len, int is_end)
              Parse  the memory at buffer of size len returning statements via
              the statement handler callback.  If is_end is non-zero, it indi-
              cates  the  end  of the parsing stream.  This method can only be
              called after raptor_start_parse().



                            2008-06-19                          3





libraptor(3)                                         libraptor(3)


PARSER UTILITY METHODS
       const char* raptor_get_mime_type(raptor_parser* rdf_parser)
              Return the MIME type for the parser.

       void raptor_set_parser_strict(raptor_parser *parser, int is_strict)
              Set the parser to strict (is_strict not zero) or  lax  (default)
              mode.   The  detail  of the strictness can be controlled by rap-
              tor_set_feature.

       int  raptor_set_feature(raptor_parser  *parser,  raptor_feature
       feature,  int value)
              Set a parser feature feature to a particular value.  Returns non
              0  on failure or if the feature is unknown.  The current defined
              parser features are:
                Feature                                 Values
                RAPTOR_FEATURE_ALLOW_BAGID              Boolean (non 0 true)
                RAPTOR_FEATURE_ALLOW_NON_NS_ATTRIBUTES  Boolean (non 0 true)
                RAPTOR_FEATURE_ALLOW_OTHER_PARSETYPES   Boolean (non 0 true)
                RAPTOR_FEATURE_ALLOW_RDF_TYPE_RDF_LIST  Boolean (non 0 true)
                RAPTOR_FEATURE_ASSUME_IS_RDF            Boolean (non 0 true)
                RAPTOR_FEATURE_CHECK_RDF_ID             Boolean (non 0 true)
                RAPTOR_FEATURE_HTML_LINK                Boolean (non 0 true)
                RAPTOR_FEATURE_HTML_TAG_SOUP            Boolean (non 0 true)
                RAPTOR_FEATURE_MICROFORMATS             Boolean (non 0 true)
                RAPTOR_FEATURE_NON_NFC_FATAL            Boolean (non 0 true)
                RAPTOR_FEATURE_NORMALIZE_LANGUAGE       Boolean (non 0 true)
                RAPTOR_FEATURE_NO_NET                   Boolean (non 0 true)
                RAPTOR_FEATURE_RELATIVE_URIS            Boolean (non 0 true)
                RAPTOR_FEATURE_SCANNING                 Boolean (non 0 true)
                RAPTOR_FEATURE_WARN_OTHER_PARSETYPES    Boolean (non 0 true)
                RAPTOR_FEATURE_WWW_TIMEOUT              Integer
                RAPTOR_FEATURE_WWW_HTTP_CACHE_CONTROL   String
                RAPTOR_FEATURE_WWW_HTTP_USER_AGENT      String

       If the allow_bagid feature is true  (default  true)  then  the  RDF/XML
       parser  will  support the rdf:bagID attribute that was removed from the
       RDF/XML language when it was revised.  This support may be  removed  in
       future.

       If the allow_non_ns_attributes feature is true (default true), then the
       RDF/XML parser will allow non-XML namespaced attributes to be  accepted
       as well as rdf: namespaced ones.  For example, 'about' and 'ID' will be
       interpreted as if they were rdf:about and rdf:ID respectively.

       If the allow_other_parsetypes feature is true (default true)  then  the
       RDF/XML  parser  will  allow  unknown parsetypes to be present and will
       pass them on to the user.  Unimplemented at present.

       If the allow_rdf_type_rdf_list feature is true (default false) then the
       RDF/XML parser will generate the idList rdf:type rdf:List triple in the
       handling of rdf:parseType="Collection".  This triple was removed during
       the revising of RDF/XML after collections were initially added.

       If  the assume_is_rdf feature is true (default false), then the RDF/XML



                            2008-06-19                          4





libraptor(3)                                         libraptor(3)


       parser will assume the content is RDF/XML,  not  require  that  rdf:RDF
       root element, and immediately interpret the content as RDF/XML.

       If  the  check_rdf_id feature is true (default true) then rdf:ID values
       will be checked for duplicates and cause an error if found.

       if the  html_link  feature  is  true  (default  true),  look  for  head
       &lt;link&gt; to type rdf/xml for GRDDL parser

       If  the  html_tag_soup  feature  is true (default true), use a lax HTML
       parser if an XML parser fails when read HTML for GRDDL parser.

       If the microformats feature is true (default true), look for  microfor-
       mats for GRDDL parser.

       If  the non_nfc_fatal feature is true (default false) then illegal Uni-
       code Normal Form C in literals will give a fatal  error,  otherwise  it
       gives a warning.

       If  the normalize_language feature is true (default true) then XML lan-
       guage values such as from xml:lang will be normalized to lowercase.

       If the no_net feature is true (default false) then network requests are
       denied.

       If  the  scanning  feature  is  true  (default false), then the RDF/XML
       parser will look for embedded rdf:RDF elements inside the XML  content,
       and not require that the XML start with an rdf:RDF root element.

       If  the www_timeout feature is set to an integer larger than 0, it sets
       the timeout in seconds for internal WWW  URI  requests  for  the  GRDDL
       parser.

       If the www_http_cache_control feature is set to a string value (default
       none), it is sent as the value of the  HTTP  Cache-Control:  header  in
       requests.

       If the www_http_user_agent feature is set to a string value, it is sent
       as the value of the HTTP User-Agent: header in requests.

       raptor_parser_set_feature_string(raptor_parser  *parser,
       raptor_feature  fea- ture, const unsigned char *value)
              Set a parser feature  feature  to  a  particular  string  value.
              Returns non 0 on failure or if the feature is unknown.  The cur-
              rent defined parser features are given in raptor_set_feature and
              at present only take integer values. If an integer value feature
              is set with this function, value is interpreted  as  an  integer
              and then that value is used.

       int raptor_get_feature(raptor_parser* parser, raptor_feature feature)
              Get  parser  feature integer values.  The allowed feature values
              and types are given under raptor_features_enumerate.





                            2008-06-19                          5





libraptor(3)                                         libraptor(3)


       const unsigned char*  raptor_parser_get_feature_string(raptor_parser
       *parser, raptor_feature feature)
              Get parser feature string values. The allowed feature values and
              types are given under raptor_features_enumerate.

       unsigned int raptor_get_feature_count(void)
              Get  the  count  of  features  defined.  Prefered to the compile
              time-only symbol RAPTOR_FEATURE_LAST which returns  the  maximum
              value, not the count.  Added raptor_get_need_base_uri

       int raptor_feature_value_type(const raptor_feature feature)
              Get a raptor feature value tyype - integer or string.

       raptor_locator* raptor_get_locator(raptor_parser* rdf_parser)
              Return  the  current raptor_locator object for the parser.  This
              is a public structure defined  in  raptor.h  that  can  be  used
              directly, or formatted via raptor_print_locator.

       void raptor_get_name(raptor_parser *parser)
              Return the string short name for the parser.

       void raptor_get_label(raptor_parser *parser)
              Return a string label for the parser.

       void raptor_set_default_generate_id_parameters(raptor_parser*
       rdf_parser, char *prefix, int base)
              Control the default method for generation of IDs for blank nodes
              and bags.  The method uses a short string prefix and an  integer
              base  to generate the identifier which is not guaranteed to be a
              strict concatenation.  If prefix is NULL, the default  is  used.
              If base is less than 1, it is initialised to 1.

       void  raptor_set_generate_id_handler(raptor_parser*  parser,  void
       *user_data, raptor_generate_id_handler handler)
              Allow full customisation of the generated IDs by setting a call-
              back handler and associated user_data that is called whenever  a
              blank  node  or bag identifier is required.  The memory returned
              is deallocated inside raptor.  Some systems require this  to  be
              allocated  inside  the  same  library,  in  which  case the rap-
              tor_alloc_memory function may be useful.

       void   raptor_parser_set_uri_filter(raptor_parser*   parser,   rap-
       tor_uri_fil- ter_func filter, void* user_data)
              Set the URI filter function filter  for  URIs  retrieved  during
              parsing by the the raptor_parser.

       int raptor_get_need_base_uri(raptor_parser* rdf_parser)
              Get  a  boolean  whether  this  parser needs a base URI to start
              parsing.

       unsigned  char*  raptor_parser_generate_id(raptor_parser*   rdf_parser,
       rap- tor_genid_type type)
              Generate  an  ID  for  a  parser  of  type  type,  either   RAP-
              TOR_GENID_TYPE_BNODEID  or  RAPTOR_GENID_TYPE_BAGID.   This uses



                            2008-06-19                          6





libraptor(3)                                         libraptor(3)


              any configuration set by raptor_set_generate_id_handler.

       void raptor_set_graph_handler(raptor_parser*  parser,  void*
       user_data,  rap- tor_graph_handler handler)
              Set the graph handler callback.

PARSER UTILITY FUNCTIONS
       int raptor_parsers_enumerate(const unsigned int counter,  const  char
       **name, const char **label)
              Return the parser name/label for a parser with a  given  integer
              counter,  returning  non-zero  if  no such parser at that offset
              exists.  The counter should start from 0 and be incremented by 1
              until the function returns non-zero.

       int  raptor_syntaxes_enumerate(const  unsigned int counter, const char
       **name, const char **label, const char **mime_type, const unsigned char
       **uri-string)
              Return the name, label, mime type or URI string  (all  optional)
              for a parser syntax with a given integer counter, returning non-
              zero if no such  syntax  parser  at  that  offset  exists.   The
              counter  should  start  from 0 and be incremented by 1 until the
              function returns non-zero.

       int raptor_features_enumerate(const raptor_feature feature, const char
       **name, raptor_uri **uri, const char **label)
              Return the name, URI, string label (all optional) for  a  parser
              feature, returning non-zero if no such feature exists.

       Raptor features have URIs that are constructed from the URI http://fea-
       ture.librdf.org/raptor- and the name so for example feature  scanForRDF
       has URI http://feature.librdf.org/raptor-scanForRDF

       int raptor_syntax_name_check(const char *name)
              Check name is a known syntax name.

       const  char*  raptor_guess_parser_name(raptor_uri *uri, const char
       *mime_type,     const unsigned char *buffer, size_t len, const unsigned
       char *identifier)
              Guess a parser name for a syntax identified  by  URI  uri,  MIME
              type  mime_type, some initial content buffer of size len or with
              content identifier identifier.   All  of  these  parameters  are
              optional  and  only  used  if not NULL.  The parser is chosen by
              scoring the hints that are given.

       raptor_feature raptor_feature_from_uri(raptor_uri *uri)
              Turn a URI uri into a raptor feature identifier, or  <0  if  the
              feature   is   unknown.   The  URIs  are  described  below  rap-
              tor_set_feature.

STATEMENT UTILITY FUNCTIONS
       int raptor_statement_compare(const raptor_statement *s1,  const  rap-
       tor_state- ment *s2)
              Compare two statements and return an ordering between them.




                            2008-06-19                          7





libraptor(3)                                         libraptor(3)


       void  raptor_print_statement(const  raptor_statement*  const
       statement,  FILE *stream)
              Print a raptor statement object in a simple format for debugging
              only.  The format of this output is not guaranteed to remain the
              same between releases.

       void  raptor_print_statement_as_ntriples(const  raptor_statement*
       statement, FILE *stream)
              Print a raptor statement object in N-Triples format,  using  all
              the   escapes   as   defined  in  http://www.w3.org/TR/rdf-test-
              cases/#ntriples

       raptor_statement_part_as_counted_string(const   void   *term,   rap-
       tor_identi-     fier_type  type,  raptor_uri*  literal_datatype,  const
       unsigned  char  *lit- eral_language, size_t* len_p)

       char* raptor_statement_part_as_string(const void *term, raptor_identi-
       fier_type type, raptor_uri* literal_datatype, const unsigned char *lit-
       eral_language)
              Turns  part of raptor statement into N-Triples format, using all
              the  escapes  as   defined   in   http://www.w3.org/TR/rdf-test-
              cases/#ntriples  The  part  (subject,  predicate, object) of the
              raptor_statement is passed in  as  term,  the  part  type  (sub-
              ject_type,  predicate_type,  object_type)  is passed in as type.
              When the part  is  a  literal,  the  literal_datatype  and  lit-
              eral_language   fields   are   set,   otherwise   NULL  (usually
              object_datatype, object_literal_language).

              If raptor_statement_part_as_counted_string is used,  the  length
              of the returned string is stored in *len_p if not NULL.

LOCATOR UTILITY FUNCTIONS
       int  raptor_format_locator(char  *buffer, size_t length,
       raptor_locator* loca- tor)
              This method takes a raptor_locator object as passed to an error,
              warning or other handler callback and formats it into the buffer
              of  size  length bytes.  If buffer is NULL or length is insuffi-
              cient for the size of the formatted locator, returns the  number
              of additional bytes required in the buffer to write the locator.

              In particular, if this form is used:
                length=raptor_format_locator(NULL, 0, locator) it will  return
              in length the size of a buffer that can be allocated for locator
              and a second call will perform the formatting:
                raptor_format_locator(buffer, length, locator)


       void raptor_print_locator(FILE *stream, raptor_locator* locator)
              This method takes a raptor_locator object as passed to an error,
              warning  or other handler callback, formats and prints it to the
              given stdio stream.

       int raptor_locator_line(raptor_locator *locator)
              Returns the line number in a locator  structure  or  <0  if  not



                            2008-06-19                          8





libraptor(3)                                         libraptor(3)


              available.

       int raptor_locator_column(raptor_locator *locator)
              Returns  the  column  number in a locator structure or <0 if not
              available.

       int raptor_locator_byte(raptor_locator *locator)
              Returns the byte offset in a locator  structure  or  <0  if  not
              available.

       const char * raptor_locator_file(raptor_locator *locator)
              Returns  the  filename  in  a  locator  structure or NULL if not
              available.  Note the returned pointer is to a shared string that
              must be copied if needed.

       const char * raptor_locator_uri(raptor_locator *locator)
              Returns  the  URI  string  in a locator structure or NULL if not
              available.  Note this does not return a raptor_uri* pointer  and
              the  returned  pointer is to a shared string that must be copied
              if needed.

N-TRIPLES UTILITY FUNCTIONS
       void raptor_print_ntriples_string(FILE* stream, const char* string,
       const char delim)
              This is a standalone  function  that  prints  the  given  string
              according  to  N-Triples  escaping rules, expecting to be termi-
              nated by delimiter delim which is usually either ',  or <.  If a
              null delimiter \0 is given, no extra escaping is performed.

       int    raptor_iostream_write_string_ntriples(raptor_iostream   *iostr,
       const unsigned char *string, size_t len, const char delim)
              Write  an  N-Triples  encoded  version  of  the  given string to
              iostream iostr.  If delim is given, that is the ending delimeter
              of  the  encoded  string and it will be escaped in the output as
              appropriate.  Useful delim values are ',   and  >.   If  a  null
              delimiter \0 is given, no extra escaping is performed.

       int raptor_iostream_write_string_python(raptor_iostream *iostr, const
       unsigned char *string, size_t len, const char delim, int flags)
              Write  string  encoded to an iostream according to the delimeter
              delim and encoding flags.  The  flag  value  selects  formatting
              according to the appropriate Python-related languages such as N-
              Triples (0), Turtle (1), Turtle long  quoted  string  (2),  JSON
              (3).

       void  raptor_iostream_write_statement_ntriples(raptor_iostream*  iostr,
       const raptor_statement *statement)
              Write  an  N-Triples  encoded  version  of  the raptor_statement
              statement to iostream iostr.

       void   raptor_iostream_write_string_turtle(raptor_iostream*    iostr,
       const unsigned char* string, size_t len)
              DEPRECATED in 1.4.17 -  use  raptor_iostream_write_string_python
              instead.   Write  an UTF-8 string of length len using the Turtle



                            2008-06-19                          9





libraptor(3)                                         libraptor(3)


              "longString" triple quoting format to the iostream iostr.

       const char* raptor_ntriples_term_as_string (raptor_ntriples_term_type
       term)
              Deprecated, for internal use.

XML UTILITY FUNCTIONS
       int  raptor_xml_any_escape_string(const  unsigned  char*  string,
       size_t len,       unsigned char* buffer, size_t length, char quote, int
       xml_version, raptor_sim-       ple_message_handler error_handler, void*
       error_data)

       int raptor_xml_escape_string(const unsigned char *string, size_t len,
       unsigned                       char *buffer, size_t length, char quote,
       raptor_message_handler error_handler, void *error_data)
              Apply the XML escaping rules to the  string  given  in  (string,
              len)  into  the  buffer  of size length.  If quote is given, the
              escaped content is for an  XML  attribute  and  the  appropriate
              quote character XML element content (CDATA).   The error_handler
              method along with error_data allow error reporting to be  given.
              If  buffer  is  NULL, returns the size of the buffer required to
              escape.  Otherwise the return value is the number of bytes  used
              or <0 on failure.

              When  an xml_version argument is present and has a value 10 (XML
              1.0) or 11 (XML 1.1) then that version  is  used.   The  default
              with no argument is to generate XML 1.0.

       int raptor_iostream_write_xml_any_escaped_string(raptor_iostream*
       iostr, const        unsigned char* string, size_t len, char quote,  int
       xml_version,  raptor_sim-      ple_message_handler error_handler, void*
       error_data)

       int  raptor_iostream_write_xml_escaped_string(raptor_iostream*  iostr,
       const      unsigned  char  *string, size_t len, char quote, raptor_sim-
       ple_message_handler error_handler, void *error_data)
              Write an XML-escaped version of the  string  given  in  (string,
              len)  to iostream iostr.  If quote is given, the escaped content
              is for an XML attribute and the appropriate quote  character  is
              used,   otherwise  it  is  XML  element  content  (CDATA).   The
              error_handler method along with error_data allow error reporting
              to be given.

              When  an xml_version argument is present and has a value 10 (XML
              1.0) or 11 (XML 1.1) then that version  is  used.   The  default
              with no argument is to generate XML 1.0.

       int  raptor_xml_name_check(const  unsigned  char  *string,  size_t
       length, int xml_version)
              Check  that the given string of length bytes is a legal XML name
              according to XML 1.0 or XML 1.1.  xml_version is set to 10 or 11
              respectively.  Returns non-zero if the name is legal.





                            2008-06-19                         10





libraptor(3)                                         libraptor(3)


MEMORY UTILITY FUNCTIONS
       void raptor_free_memory(void *ptr)
              Free  memory allocated inside raptor.  Some systems require mem-
              ory allocated  in  a  library  to  be  deallocated  inside  that
              library.   This  function  can be used in that situation to free
              memory allocated by raptor, such as the result of the _to_ meth-
              ods that return allocated memory such as raptor_uri_to_filename,
              raptor_uri_to_string, raptor_uri_to_relative_counted_uri_string,
              raptor_uri_to_relative_uri_string      or      raptor_new_names-
              pace_parts_from_string.

       void* raptor_alloc_memory(size_t size)
              Allocate memory inside the raptor library.  Some systems require
              memory  allocated  in  a  library  to be deallocated inside that
              library.  This function can be used in that situation  to  allo-
              cate memory for raptor to free later, such as inside the handler
              function  declared  with  raptor_set_generate_id_handler   which
              returns new memory.

       void* raptor_calloc_memory(size_t nmemb, size_t size)
              Allocate  zeroed  array  of  items  inside raptor.  Some systems
              require memory allocated in a library to be  deallocated  inside
              that  library.   This  function can be used in that situation to
              clear an array of allocated memory for raptor to use, for  free-
              ing  later,  such  as  inside the handler function declared with
              raptor_set_generate_id_handler which returns new memory.

UNICODE UTILITY FUNCTIONS
       int raptor_unicode_char_to_utf8(raptor_unichar c, unsigned char *out-
       put)
              Turn  a  Unicode  character  into UTF8 bytes in output of size c
              bytes which must be of sufficient size.  Returns the  number  of
              bytes encoded or <0 on failure.

       int  raptor_utf8_to_unicode_char(raptor_unichar  *output,  const
       unsigned char *input, int length)
              Decode a sequence UTF8 bytes in input of size length into a Uni-
              code character in output returning the number of bytes  used  or
              <0 on failure.

       int raptor_utf8_check(const unsigned char *string, size_t length)
              Check  that  a given string is legal UTF-8 encoding and includes
              only legal  Unicode  characters  U+0  to  U+0x10ffff  inclusive.
              Returns non-0 if the string is good.

       int raptor_unicode_is_xml11_namestartchar(raptor_unichar c)

       int raptor_unicode_is_xml10_namestartchar(raptor_unichar c)

       int raptor_unicode_is_xml11_namechar(raptor_unichar c)

       int raptor_unicode_is_xml10_namechar(raptor-unichar c)
              Check  that  given  Unicode characters are allowed as XML 1.0 or
              XML   1.0   names   -   either   as   the   starting   character



                            2008-06-19                         11





libraptor(3)                                         libraptor(3)


              (*_namestartchar) or continuing character (*_namechar).  Returns
              non-0 if the character is allowed.

ERROR UTILITY FUNCTIONS
       void raptor_error_handlers_init(raptor_error_handlers* error_handlers)
              Initialise an error_handlers structure after the log level  han-
              dlers and user data pointers have been set.

MISCELLANEOUS UTILITY FUNCTIONS
       char* raptor_vsnprintf(const char *message, va_list arguments)
              Compatibility wrapper around vsnprintf.

STATIC VARIABLES
       There are several read-only static variables in the raptor library:

       const char * const raptor_short_copyright_string
              Short copyright string, suitable for one line.

       const char * const raptor_copyright_string
              Full copyright over several lines including URLs.

       const char * const raptor_version_string
              The version as a string

       const unsigned int raptor_version_major
              The major version number as an integer.

       const unsigned int raptor_version_minor
              The minor version number as an integer.

       const unsigned int raptor_version_release
              The release version number as an integer.

       const unsigned int raptor_version_decimal
              The version number as a single decimal.

       const char * const raptor_license_string
              The license string over several lines including URLs.

       const char * const raptor_home_url_string
              The home page URL as a string.

SERIALIZER CLASS
       This  class provides the functionality of turning RDF triples into syn-
       taxes - RDF serializing.

SERIALIZER CONSTRUCTOR
       raptor_serializer* raptor_new_serializer(const char *name)
              Create a new raptor serializer object for  the  serializer  with
              name name currently either "rdfxml" or "ntriples".  or "rss-1.0"
              for the RSS 1.0 serializer.

SERIALIZER DESTRUCTOR




                            2008-06-19                         12





libraptor(3)                                         libraptor(3)


       void raptor_free_serializer(raptor_serializer* rdf_serializer)
              Destroy a Raptor serializer object.

SERIALIZER SERIALIZING METHODS
       int raptor_serialize_start(raptor_serializer* rdf_serializer,
       raptor_uri *uri, raptor_iostream *iostream)
              Start to serialize content using the given iostream to write  to
              with  optional  base  URI uri. The iostream becomes owned by the
              serializer object and is destroyed at  the  end  of  serializing
              when raptor_serialize_end() is called.  Note that  some syntaxes
              may refuse to serialize without a base URI, such as RDF/XML.

       int raptor_serialize_start_to_iostream(raptor_serializer*
       rdf_serializer, rap- tor_uri* uri, raptor_iostream* iostream)
              Start to serialize content using the given iostream to write  to
              with  optional base URI uri.  The iostream does NOT become owned
              by the serializer object and the caller may continue to write to
              it  after  serializing is finished.  Note that some syntaxes may
              refuse to serialize without a base URI, such as RDF/XML.

       int   raptor_serialize_start_to_filename(raptor_serializer*
       rdf_serializer, const char *filename)
              Start to serialize content to the file filename which is  opened
              for writing. The base URI is calculated from the file name.

       int  raptor_serialize_start_to_string(raptor_serializer*
       rdf_serializer, rap- tor_uri *uri, void **string_p, size_t *length_p)
              Start  to serialize content to a string.  string_p must point to
              a void* pointer that will be used at the end of  serializing  to
              store the newly allocated string.  length_p if not NULL, it will
              be used to store the length of the new string.  The  serializing
              is  done  with  optional  base URI uri however some syntaxes may
              refuse to serialize without a base URI, such as RDF/XML.

       int  raptor_serialize_start_to_file_handle(raptor_serializer*
       rdf_serializer, raptor_uri *uri, FILE *handle)
              Start to serialize content to the already open  C  Standard  I/O
              FILE* handle with the base URI uri, which is optional and may be
              NULL.  Note that some syntaxes may refuse to serialize without a
              base URI, such as RDF/XML.

       int  raptor_serialize_statement(raptor_serializer*  rdf_serializer,
       const rap- tor_statement *statement)
              Serialize a single statement using the serializer.

       int raptor_serialize_end(raptor_serializer* rdf_serializer)
              End  the  serializing.  This may close and delete resources used
              in serializing.  No more calls to raptor_serialize_statement  or
              raptor_serialize_end may be done at this point.

       raptor_iostream* raptor_serializer_get_iostream(raptor_serializer
       *serializer)
              Return a pointer to the raptor_iostream* used by the serializer.




                            2008-06-19                         13





libraptor(3)                                         libraptor(3)


       int raptor_serializer_set_namespace(raptor_serializer* serializer,
       raptor_uri *uri, const char *prefix)
              Set a suggested namespace URI/prefix mapping for use in  serial-
              izing.

SERIALIZER UTILITY METHODS
       void  raptor_serializer_set_error_handler(raptor_serializer*
       serializer, void *user_data, raptor_message_handler handler)
              Set the serializer non-fatal error handler callback.

       void raptor_serializer_set_warning_handler(raptor_serializer*
       serializer, void *user_data, raptor_message_handler handler)
              Set the serializer warning message handler callback.

       raptor_locator*  raptor_serializer_get_locator(raptor_serializer*
       rdf_serial- izer)
              Return  the  current  raptor_locator  object for the serializer.
              This is a public structure defined in raptor.h that can be  used
              directly, or formatted via raptor_print_locator.

       int  raptor_serializer_set_feature(raptor_serializer  *serializer, rap-
       tor_fea- ture feature, int value)
              Set a serializer feature feature to a particular value.  Returns
              non 0 on failure or if the  feature  is  unknown.   The  current
              defined serializer features are:
                Feature                                 Values
                RAPTOR_FEATURE_RELATIVE_URIS            Boolean (non 0 true)
                RAPTOR_FEATURE_WRITE_BASE_URI           Boolean (non 0 true)
                RAPTOR_FEATURE_START_URI                URI String
                RAPTOR_FEATURE_BNODE_BORDER             String
                RAPTOR_FEATURE_BNODE_FILL               String
                RAPTOR_FEATURE_JSON_CALLBACK            String
                RAPTOR_FEATURE_JSON_EXTRA_DATA          String
                RAPTOR_FEATURE_LITERAL_BORDER           String
                RAPTOR_FEATURE_LITERAL_FILL             String
                RAPTOR_FEATURE_RESOURCE_BORDER          String
                RAPTOR_FEATURE_RESOURCE_FILL            String
                RAPTOR_FEATURE_RSS_TRIPLES              String
                RAPTOR_FEATURE_ATOM_ENTRY_URI           String


       If  the relative_uris feature is true (default false) then when serial-
       ising, preference is given to generating relative URIs where  possible.

       If  the  write_base_uri  feature  is true (default true) then the atom,
       rdfxml, rdfxml-abbrev and turtle serializers will  write  an  @base  or
       xml:base directive in the output.

       If  the  start_uri feature is set to a URI it is used by the serializer
       to start serializing from.

       If the bnode_border feature is set, the DOT serializer uses it  as  the
       bnode border colour.




                            2008-06-19                         14





libraptor(3)                                         libraptor(3)


       If  the  bnode_fill  feature  is set, the DOT serializer uses it as the
       bnode fill colour.

       If the json_callback feature is set, the JSON serializers use it as the
       name of the callback to wrap the outer JSON object.

       If  the  json_extra_data feature is set, the JSON serializers use it as
       extra data inside the outer JSON object.

       If the literal_border feature is set, the DOT serializer uses it as the
       literal border colour.

       If  the  literal_fill feature is set, the DOT serializer uses it as the
       literal fill colour.

       If the resource_border feature is set, the DOT serializer  uses  it  as
       the resource border colour.

       If  the resource_fill feature is set, the DOT serializer uses it as the
       resource fill colour.

       If the rss_triples feature is set  to  the  string  "rdf-xml"  for  the
       rss-1.0 serializer or "atom-triples" for the atom serializer, it writes
       extra rdf triples into the serialized output.

       If the atom_entry_uri feature is set to a URI string,  it  is  used  to
       trigger generation of an atom entry document for the atom serializer.

       int  raptor_serializer_get_feature(raptor_serializer*  serializer, rap-
       tor_fea- ture feature)
              Get  serializer  features, the allowed feature values are avail-
              able

SERIALIZER UTILITY FUNCTIONS
       int  raptor_serializers_enumerate(const  unsigned  int  counter,  const
       char   **name,  const  char  **label,  const  char  **mime_type,  const
       unsigned char **uri_string)
              Return the serializer name/label for a serializer with  a  given
              integer  counter,  returning  non-zero if no such parser at that
              offset exists.  The counter should start from 0  and  be  incre-
              mented by 1 until the function returns non-zero.

       int raptor_serializer_syntax_name_check(const char *name)
              Check name is a known serializer syntax name.

URI CLASS
       Raptor has a raptor_uri class must be used for manipulating and passing
       URI references.  The default internal implementation uses char* strings
       for  URIs, manipulating them and constructing them.  This URI implemen-
       tation can be replaced by any other that provides the equivalent  func-
       tionality, using the raptor_uri_set_handler function.

URI CONSTRUCTORS
       There  a  several  constructors for raptor_uri to build them from char*



                            2008-06-19                         15





libraptor(3)                                         libraptor(3)


       strings and existing raptor_uri objects.

       raptor_uri* raptor_new_uri(const unsigned char* uri_string)
              Create a raptor URI from a string URI-reference uri_string.

       raptor_uri* raptor_new_uri_from_uri_local_name(raptor_uri* uri, const
       unsigned char* local_name)
              Create a raptor URI from a string URI-reference local_name rela-
              tive  to an existing URI-reference.  This performs concatenation
              of the local_name to the uri and not  relative  URI  resolution,
              which  is  done by the raptor_new_uri_relative_to_base construc-
              tor.

       raptor_uri*   raptor_new_uri_relative_to_base(raptor_uri*   base_uri,
       const unsigned char* uri_string)
              Create a raptor URI from a string URI-reference uri_string using
              relative URI resolution to the base_uri.

       raptor_uri*  raptor_new_uri_from_id(raptor_uri* base_uri, const
       unsigned char* id)
              Create  a raptor URI from a string RDF ID id concatenated to the
              base_uri base URI.

       raptor_uri* raptor_new_uri_for_rdf_concept(const char* name)
              Create a raptor URI for the RDF namespace concept name.

       raptor_uri* raptor_new_uri_for_xmlbase(raptor_uri* old_uri))
              Create a raptor URI suitable for use with xml:base  (throw  away
              fragment)

URI DESTRUCTOR
       void raptor_free_uri(raptor_uri* uri)
              Destroy a raptor URI object.

URI METHODS
       int raptor_uri_equals(raptor_uri* uri1, raptor_uri* uri2)
              Return non-zero if the given URIs are equal.

       raptor_uri* raptor_uri_copy(raptor_uri* uri)
              Return a copy of the given raptor URI uri.

       unsigned char* raptor_uri_as_counted_string(raptor_uri *uri, size_t*
       len_p)

       unsigned char* raptor_uri_as_string(raptor_uri* uri)
              Return a shared pointer to a string representation of the  given
              raptor  URI  uri.   This  string is shared and must not be freed
              (otherwise see the  raptor_uri_to_*  methods  below).   If  rap-
              tor_uri_as_counted_string  is  used,  the length of the returned
              string is stored in *len_p if not NULL.

       unsigned char* raptor_uri_to_counted_string(raptor_uri *uri, size_t
       *len_p)




                            2008-06-19                         16





libraptor(3)                                         libraptor(3)


       unsigned char* raptor_uri_to_string(raptor_uri *uri)
              Return  a  to a newly alloced string representation of the given
              raptor URI uri.  This string must be freed by the  caller  using
              raptor_free_memory.   If  raptor_uri_to_counted_string  is used,
              the length of the returned string is stored  in  *len_p  if  not
              NULL.

       unsigned char* raptor_uri_to_relative_counted_uri_string(raptor_uri
       *base_uri, raptor_uri *reference_uri, size_t *length_p)

       unsigned  char*  raptor_uri_to_relative_uri_string(raptor_uri
       *base_uri, rap- tor_uri *reference_uri)
              Return  a new relative URI string of a URI reference_uri against
              a base URI base_uri.  The returned string  must  be  freed  with
              raptor_free_memory.  If raptor_uri_to_relative_counted_string is
              used, the length of the returned string is stored in  *len_p  if
              not NULL.

       void raptor_uri_print(const raptor_uri* uri, FILE *stream)
              Print URI uri to the file handle stream.

       int raptor_iostream_write_uri(raptor_iostream* iostr,  raptor_uri* uri)
              Write the raptor_uri uri to the iostream ostr.

URI UTILITY FUNCTIONS
       void raptor_uri_resolve_uri_reference (const unsigned  char*  base_uri,
       const       unsigned char* reference_uri, char unsigned* buffer, size_t
       length)
              This  is  a  standalone  function that resolves the relative URI
              reference_uri against the base URI base_uri according to the URI
              resolution  rules  in  RFC2396.   The resulting URI is stored in
              buffer which is of length bytes.  If this is too small, no  work
              will be done.

       char *raptor_uri_filename_to_uri_string(const unsigned char* filename)
              This  is a standalone function that turns a local filename (Win-
              dows or Unix style as  appropriate  for  platform)  into  a  URI
              string (file).
               The  returned  string must be freed by the caller. Some systems
              require memory allocated in a library to be  deallocated  inside
              that library in which case raptor_free_memory may be used.

       char *raptor_uri_uri_string_to_filename(const unsigned char*
       uri_string)

       char  *raptor_uri_uri_string_to_filename(const  unsigned   char*
       uri_string, unsigned char **fragment_p)
              These are standalone functions that turn a URI string that  rep-
              resents  a local filename (file:) into a filename, with optional
              URI fragment.  If fragment_p is not NULL it points to the  loca-
              tion  to store a newly allocated string containing the fragment.
              The returned strings must be freed by the caller.  Some  systems
              require  memory  allocated in a library to be deallocated inside
              that library in which case raptor_free_memory may be used.



                            2008-06-19                         17





libraptor(3)                                         libraptor(3)


       int raptor_uri_is_file_uri(const unsigned char* uri_string)
              DEPRECATED in 1.4.9.  Returns non-zero if the given  URI  string
              represents a filename.  Use raptor_uri_uri_string_is_file_uri in
              preference.

       int raptor_uri_uri_string_is_file_uri(const unsigned char* uri_string)
              Returns non-zero if the given URI string represents a  filename.

URI CLASS IMPLEMENTATION
       void raptor_uri_set_handler(const raptor_uri_handler *handler, void
       *context)
              Change the URI class implementation to the functions provided by
              the handler URI implementation.  The context user data is passed
              in to the handler URI implementation calls.

       void raptor_uri_get_handler(raptor_uri_handler **handler, void **con-
       text)
              Return  the  current raptor URI class implementation handler and
              context


WWW CLASS
       This is a small wrapper class around existing WWW libraries in order to
       provide  HTTP  GET  or  better  URI  retrieval  for  Raptor.  It is not
       intended to be a general purpose WWW retrieval interface.

WWW CLASS INITIALISATION AND CLEANUP
       void raptor_www_init(void)

       void raptor_www_finish(void)
              Initialise or terminate  the  raptor_www  infrastructure.   rap-
              tor_www_init  and  raptor_finish  are  called by raptor_init and
              raptor_finish respecitively, otherwise must be called once each.

       NOTE   Several  of  the  WWW  library implementations require once-only
              initialisation and termination functions to be  called,  however
              raptor  cannot determine whether this is already done before the
              library is initialised in raptor_www_init or terminated in  rap-
              tor_www_finish,  so  always performs it.  This can be changed by
              raptor_www_no_www_library_init_finish.

       void raptor_www_no_www_library_init_finish(void)
              If this is called before raptor_www_init, it will not  call  the
              underlying WWW library global initialise or terminate functions.
              The application code must perform both operations.

              For example with curl, after this function  is  called,  neither
              curl_global_init  nor  curl_global_cleanup will be called during
              raptor_www_init or raptor_www_finish respectively.

WWW CONSTRUCTORS
       raptor_www *raptor_www_new(void)





                            2008-06-19                         18





libraptor(3)                                         libraptor(3)


       raptor_www *raptor_www_new_with_connection(void* connection)
              Create a raptor WWW object capable of URI retrieval.  If connec-
              tion is given, it must match the connection object of the under-
              lying WWW implementation.  At present, this is only for libcurl,
              and  allows  you  to  re-use an existing curl handle, or use one
              which has been set up with some desired qualities.

WWW DESTRUCTOR
       void raptor_www_free(raptor_www *www)
              Destroy a raptor WWW object.

WWW METHODS
       void raptor_www_set_user_agent(raptor_www *www, const char *user_agent)
              Set the HTTP User-Agent header value.

       int  raptor_www_set_http_cache_control(raptor_www* www, const char*
       cache_con- trol)
              Set the HTTP Cache-Control header value.

       void raptor_www_set_proxy(raptor_www *www, const char *proxy)
              Set   the   HTTP   proxy   -   usually  a  string  of  the  form
              http://server:port

       raptor_www_set_write_bytes_handler(raptor_www            *www,
       rap- tor_www_write_bytes_handler handler, void *user_data)
              Set the handler to  receive  bytes  written  by  the  raptor_www
              implementation.

       void   raptor_www_set_content_type_handler(raptor_www   *www,  rap-
       tor_www_con- tent_type_handler handler, void *user_data)
              Set  the handler to receive the HTTP Content-Type value, when/if
              discovered during retrieval by the raptor_www implementation.

       void raptor_www_set_http_accept(raptor_www *www, const char *value)
              Set the WWW HTTP Accept: header to value.  If value is NULL,  an
              empty header is sent.

       void   raptor_www_set_error_handler(raptor_www   *www,  raptor_mes-
       sage_handler error_handler, void *error_data)
              Set  the  error  handler routine for the raptor_www class.  This
              takes the same arguments as  the  raptor_parser  error,  warning
              handler methods.

       void raptor_www_set_uri_filter(raptor_www* www, raptor_uri_filter_func
       filter, void* user_data)
              Set  the  URI  filter  function filter for URIs retrieved by the
              raptor_www object.

       void* raptor_www_get_connection(raptor_www *www)
              Return the underlying WWW library connection object.  For  exam-
              ple, for libcurl this is the curl_handle.

       void raptor_www_set_connection_timeout(raptor_www* www, int timeout)
              Set the WWW connection timeout in seconds.



                            2008-06-19                         19





libraptor(3)                                         libraptor(3)


       raptor_uri* raptor_www_get_final_uri(raptor_www* www)
              Get  the final URI from a WWW retrieval, which may include redi-
              rections.

WWW ACTION METHODS
       int raptor_www_fetch(raptor_www *www, raptor_uri *uri)
              Retrieve the given URL, returning non zero on failure.

       int  raptor_www_fetch_to_string(raptor_www   *www,   raptor_uri   *uri,
       void       **string_p, size_t *length_p, void *(*malloc_handler)(size_t
       size))
              Retrieve  the  given  URL to a string.  string_p must point to a
              void* pointer that will be used to  store  the  newly  allocated
              string.   length_p  if  not  NULL,  it will be used to store the
              length of the new string.

       void raptor_www_abort(raptor_www *www, const char *reason)
              Abort an ongoing raptor WWW operation. Typically used within one
              of the raptor WWW handlers.

QNAME CLASS
       This  is  a  class for handling XML QNames consisting of the pair of (a
       URI from a namespace, a local name) along with  an  optional  value  --
       useful  for  XML  attributes.   This  is  used  with  the raptor_names-
       pace_stack and raptor_namespace classes  to  handle  a  stack  of  rap-
       tor_namespace that build on raptor_qname.

QNAME CONSTRUCTORS
       There  are  two  constructors  for  raptor_qname  to  build qnames with
       optional values on a stack of names.

       raptor_qname* raptor_new_qname(raptor_namespace_stack *nstack, const
       unsigned   char   *name,   const   unsigned  char  *value,  raptor_sim-
       ple_message_handler error_handler, void *error_data)
              Create a raptor QName name (a possibly  :-separated  name)  with
              name  to  be  resolved against the given nstack namespace stack.
              An optional value can be given, and if there is  an  error,  the
              error_handler  and  error_data  will be used to invoke the call-
              back.

       raptor_qname*   raptor_new_qname_from_namespace_local_name   (rap-
       tor_namespace *ns, const unsigned char *local_name, const unsigned char
       *value)
              Create  a  raptor  QName  using  the  namespace name of the rap-
              tor_namespace ns and  the  local  name  local_name,  along  with
              optional  value value.  Errors are reported using the error han-
              dling and data of the namespace.

       raptor_qname* raptor_qname_copy(raptor_qname *qname)
              Create a raptor QName from an existing one,  returning  NULL  on
              failure.

QNAME DESTRUCTOR




                            2008-06-19                         20





libraptor(3)                                         libraptor(3)


       void raptor_free_qname(raptor_qname* name)
              Destroy a raptor qname object.

QNAME METHODS
       int raptor_qname_equal(raptor_qname* name1, raptor_qname *name2)
              Return non-zero if the given QNames are equal.

       int raptor_iostream_write_qname(raptor_iostream* iostr, raptor_qname
       *qname)
              Write the raptor_qname qname to the iostream ostr.

       const unsigned char* raptor_qname_get_local_name(raptor_qname* name)
              Get the local name of the QName.

       const unsigned char* raptor_qname_get_value(raptor_qname* name)
              Get the value of the QName for an XML attribute QName.

       const  unsigned   char*   raptor_qname_get_counted_value(raptor_qname*
       name, size_t* length_p)
              Get the value fo the QName along with the length (if length_p is
              not NULL) for an XML attribute QName.

       unsigned   char*   raptor_qname_to_counted_name(raptor_qname*  qname,
       size_t* length_p)
              Get  the formatted QName as a newly allocated counted string (if
              length_p is not NULL).

QNAME UTILITY FUNCTIONS
       raptor_uri* raptor_qname_string_to_uri(raptor_namespace_stack *nstack,
       const                             unsigned char *name, size_t name_len,
       raptor_simple_message_handler error_han- dler, void *error_data)
              Return the URI corresponding to the QName according to  the  RDF
              method;  concatenating the namespace's name (URI) with the local
              name.  Takes the same arguments as raptor_new_qname but does not
              create a raptor_qname object.

       raptor_namespace* raptor_qname_get_namespace(raptor_qname* name)
              Return  the  raptor_namespace  used by the QName.  Will never be
              NULL even for the default namespace in which case the URI of the
              returned namespace object will be NULL.

NAMESPACE CLASS
       An  XML  namespace  class  - each entry is on a stack and consists of a
       name (URI) and prefix.  The prefix or the name  but  not  both  may  be
       empty.   If the prefix is empty, it defines the default prefix.  If the
       name is empty, it undefines the given prefix.

NAMESPACE CONSTRUCTORS
       raptor_namespace* raptor_new_namespace(raptor_namespace_stack  *nstack,
       const    unsigned char *prefix, const unsigned char *ns_uri_string, int
       depth)

       raptor_namespace*         raptor_new_namespace_from_uri(raptor_names-
       pace_stack    *nstack, const unsigned char *prefix, raptor_uri* ns_uri,



                            2008-06-19                         21





libraptor(3)                                         libraptor(3)


       int depth)
              Create a new raptor_namespace  object  on  the  given  namespace
              stack  nstack  with prefix prefix and namespace name either from
              URI string ns_uri_string or from copying URI ns_uri.

       If prefix is NULL, it defines the URI for the default namespace prefix.
       If  the  namespace name (ns_uri_string or ns_uri) is NULL, it undefines
       the given prefix in the current scope.  Both prefix and URI may be NULL
       to undefine the default namespace.  depth signifies the position of the
       namespace on the stack; 0 is the bottom of the stack and generally  the
       first depth for user namespace declarations.

       Namespaces declared on the same depth (such as on the same XML element,
       typically) can be handily  freed  with  raptor_namespaces_end_for_depth
       method on the namespace stack class.

NAMESPACE DESTRUCTOR
       void raptor_free_namespace(raptor_namespace *ns)
              Destroy a raptor namespace object.

NAMESPACE METHODS
       raptor_uri* raptor_namespace_get_uri(const raptor_namespace *ns)
              Return the namespace name (URI) of the namespace.

       const unsigned char* raptor_namespace_get_prefix(const raptor_namespace
       *ns)
              Return the prefix of the namespace.

       const unsigned char*  raptor_namespace_get_counted_prefix(const  rap-
       tor_names- pace* ns, size_t* length_p)
              Return the prefix of the namespace as  a  string  with  optional
              count stored in the variable address length_p if it is not NULL.

       unsigned char  *raptor_namespaces_format(const  raptor_namespace  *ns,
       size_t *length_p)
              Format the namespace as a string and return it as a new  string,
              returning  the  length of the resulting string in length_p if it
              is not NULL.  The string format is suitable for emitting in  XML
              to declare the namespace.

       int  raptor_iostream_write_namespace(raptor_iostream*  iostr, rap-
       tor_namespace *ns)
              Write  a  formatted  namespace  declaration  like xmlns... to an
              iostream iostr.

NAMESPACE UTILITY FUNCTIONS
       int  raptor_namespace_copy(raptor_namespace_stack  *nstack,   rap-
       tor_namespace *ns, int new_depth)
              Copy the namespace from the current stack to the new one, nstack
              at depth new_depth.

       int  raptor_new_namespace_parts_from_string(unsigned  char  *string,
       unsigned char **prefix, unsigned char **uri_string)
              Parse  string  with  an  XML-style  namespace  declaration  like



                            2008-06-19                         22





libraptor(3)                                         libraptor(3)


              xmlns="",  xmlns="uri",  xmlns:prefix=""  or  xmlns:prefix="uri"
              into  the  strings pointed to by prefix string and a uri_string.
              Empty  prefixes  or  namespace  names  return   NULL   pointers.
              Returned  strings  must  be  freed  by  the  caller  using  rap-
              tor_free_memory.

NAMESPACE STACK CLASS
       A stack of raptor_namespace objects where the namespaces on top of  the
       stack  have wider scope and override earlier (lower) namespace declara-
       tions.  Intended to match the XML namespace declaring  semantics  using
       xmlns attributes.

NAMESPACE STACK CONSTRUCTORS
       raptor_namespace_stack* raptor_new_namespaces(raptor_uri_handler
       *uri_handler,      void   *uri_context,   raptor_simple_message_handler
       error_handler,    void *error_data, int defaults)

       int  raptor_namespaces_init(raptor_namespace_stack *nstack, rap-
       tor_uri_handler                               *handler, void  *context,
       raptor_simple_message_handler  error_handler,  void    *error_data, int
       defaults)
              Create or initialise a new  raptor_namespace_stack  object  with
              the  given  URI and error handlers.  raptor_namespaces_new allo-
              cates new memory  for  the  namespace  stack  and  raptor_names-
              paces_init  initialises an existing declared nstack, which could
              be statically allocated.  Note that  raptor_uri_get_handler  can
              be useful to return the current raptor URI handler/context.  The
              defaults  argument  describes  which  default   namespaces   are
              declared  in the empty stack.  At present, 0 is none, 1 for just
              the XML namespace and 2 is for a typical set of namespaces  used
              for RDF, RDFS, Dublin Core, OWL, ...  that may vary over time.

              In  versions  1.4.16  or  newer  this returns an integer result,
              non-0 on failure.

NAMESPACE STACK DESTRUCTORS
       void raptor_free_namespaces(raptor_namespace_stack *nstack)
              Destroy a namespace stack object, freeing the nstack (goes  with
              raptor_new_namespaces).

       void raptor_namespaces_clear(raptor_namespace_stack *nstack)
              Clear  a statically allocated namespace stack; does not free the
              nstack.  (goes with raptor_namespaces_init).

NAMESPACE STACK METHODS
       void  raptor_namespaces_start_namespace(raptor_namespace_stack
       *nstack,  rap- tor_namespace *nspace)
              Start the given nspace  on  the  stack,  at  the  depth  already
              defined.

       int   raptor_namespaces_start_namespace_full(raptor_namespace_stack
       *nstack,  const unsigned char *prefix, const unsigned char *nspace, int
       depth)
              Create a new raptor_namespace and start it on  the  stack.   See



                            2008-06-19                         23





libraptor(3)                                         libraptor(3)


              raptor_new_namespace for the meaning of the argumens.

       void   raptor_namespaces_end_for_depth(raptor_namespace_stack
       *nstack,   int depth)
              End (and free) all namespaces on the stack at the given depth.

       raptor_namespace*    raptor_namespaces_get_default_namespace    (rap-
       tor_names- pace_stack *nstack)
              Return  the  current  default  raptor_namespace of the namespace
              stack or NULL if there is none.

       raptor_namespace*        raptor_namespaces_find_namespace_by_uri(rap-
       tor_names- pace_stack *nstack, raptor_uri *ns_uri)
              Find the first namespace on the stack with the given uri  ns_uri
              or NULL if there is none.

       raptor_namespace        *raptor_namespaces_find_namespace_by_uri(rap-
       tor_names-    pace_stack *nstack, const unsigned char *prefix, int pre-
       fix_length)
              Find the first namespace on the stack with the  given  namespace
              prefix or NULL if there is none.

       int raptor_namespaces_namespace_in_scope(raptor_namespace_stack
       *nstack, const raptor_namespace *nspace)
              Return  non-zero  if  the raptor_namespace nspace is declared on
              the stack; i.e. in scope if this is a stack of XML namespaces.

NAMESPACE STACK UTILITY FUNCTIONS
       raptor_qname* raptor_namespaces_qname_from_uri(raptor_namespace_stack*
       nstack, raptor_uri* uri, int xml_version)
              Create a raptor QName from the URI uri if the URI is  squal  one
              of  the  namespace  URIs on the namespace stack nstack URIs con-
              catenated to a legal XML name for the given XML  version.   URIs
              are  created  and  errors are reported using the namespace stack
              fields.  Fails if it cannot be legally described with any of the
              namespaces.

SEQUENCE CLASS
       A  class  for  ordered  sequences of items, adding at either end of the
       sequence.  The method names should be familiar to Perl users.

SEQUENCE CONSTRUCTOR
       raptor_sequence*  raptor_new_sequence(raptor_sequence_free_handler*
       free_han- dler, raptor_sequence_print_handler* print_handler)
              Create a new empty sequence, with optional handler  for  freeing
              elements  (as used by raptor_free_sequence and printing out ele-
              ments (used by raptor_sequence_print).

SEQUENCE DESTRUCTOR
       void raptor_free_sequence(raptor_sequence* seq)
              Destoy a sequence object, freeing any items if the free  handler
              was defined in the constructor.





                            2008-06-19                         24





libraptor(3)                                         libraptor(3)


SEQUENCE METHODS
       int raptor_sequence_size(raptor_sequence* seq)
              Return the number of items in the sequence.

       int raptor_sequence_set_at(raptor_sequence* seq, int idx, void *data)
              Set  the sequence item at index idx to the value data, extending
              it if necessary.

       int raptor_sequence_push(raptor_sequence* seq, void *data)
              Add item data to the end of the sequence.

       int raptor_sequence_shift(raptor_sequence* seq, void *data)
              Add item data to the start of the sequence.

       void* raptor_sequence_get_at(raptor_sequence* seq, int idx)
              Get the sequence item at index idx or  NULL  if  no  such  index
              exists.

       void* raptor_sequence_pop(raptor_sequence* seq)
              Remove  and return an item from the end of the sequence, or NULL
              if is empty.

       void* raptor_sequence_unshift(raptor_sequence* seq)
              Remove and return an item from the start  of  the  sequence,  or
              NULL if is empty.

       void  raptor_sequence_sort(raptor_sequence*  seq,  int(*compare)(const
       void *, const void *))
              Sort  the  sequence  using the given comparison function compare
              which is passed to qsort(3) internally.

       int raptor_compare_strings(const void *a, const void *b)
              Helper function useful with raptor_sequence_sort.

       void     raptor_sequence_set_print_handler(raptor_sequence     *seq,
       rap- tor_sequence_print_handler *print_handler)
              Set the print handler for the sequence, an alternative  to  set-
              ting it in the constructor.

       void raptor_sequence_print_string(char *data, FILE *fh)
              Helper  print handler function useful for printing out sequences
              of strings.

       void raptor_sequence_print_uri(char *data, FILE *fh)
              Helper print handler function useful for printing out  sequences
              of raptor_uri* objects.

       void raptor_sequence_print(raptor_sequence* seq, FILE* fh)
              Print  out the sequence in a debug format to the given file han-
              dler fh.  NOTE: The exact format is not guaranteed to remain the
              same between releases.

       int raptor_sequence_join(raptor_sequence* dest, raptor_sequence *src)
              Join two sequences moving all items from sequence src to the end



                            2008-06-19                         25





libraptor(3)                                         libraptor(3)


              of sequence dest.  After this operation, sequence  src  will  be
              empty  (zero  size)  but  will  have  the  same item capacity as
              before.

       void* raptor_sequence_delete_at(raptor_sequence* seq, int idx)
              Remove an item from position idx in the sequence, returning  it.

STRINGBUFFER CLASS
       A class for growing strings, small chunks at a time.

STRINGBUFFER CONSTRUCTOR
       raptor_stringbuffer* raptor_new_stringbuffer(void)
              Create a new stringbuffer.

STRINGBUFFER DESTRUCTOR
       void raptor_free_stringbuffer(raptor_stringbuffer* stringbuffer)
              Destroy a stringbuffer.

STRINGBUFFER METHODS
       int   raptor_stringbuffer_append_counted_string(raptor_stringbuffer*
       string-         buffer, const unsigned char *string, size_t length, int
       do_copy)
              Append a string of length bytes to a  stringbuffer,  copying  it
              only if do_copy is non-0.

       int raptor_stringbuffer_append_string(raptor_stringbuffer*
       stringbuffer, const unsigned char* string, int do_copy)
              Append a string to a stringbuffer, copying it only if do_copy is
              non-0.

       int raptor_stringbuffer_append_decimal(raptor_stringbuffer*
       stringbuffer,  int integer)
              Append a formatted decimal integer to a stringbuffer.

       int raptor_stringbuffer_append_stringbuffer(raptor_stringbuffer*
       stringbuffer, raptor_stringbuffer* append)
              Append a stringbuffer append  to  a  stringbuffer.   The  append
              stringbuffer is emptied but not destroyed.

       int   raptor_stringbuffer_prepend_counted_string(raptor_stringbuffer*
       string-         buffer, const unsigned char* string, size_t length, int
       do_copy)
              Prepend a string of length bytes to the start of a stringbuffer,
              copying it only if do_copy is non-0.

       int    raptor_stringbuffer_prepend_string(raptor_stringbuffer*
       stringbuffer, const unsigned char* string, int do_copy)
              Prepend a string to the start of a stringbuffer, copying it only
              if do_copy is non-0.

       unsigned  char  *  raptor_stringbuffer_as_string(raptor_stringbuffer*
       string- buffer)
              Return the stringbuffer as  a  single  string.   The  string  is
              shared and should be copied if needed.



                            2008-06-19                         26





libraptor(3)                                         libraptor(3)


       size_t raptor_stringbuffer_length(raptor_stringbuffer* stringbuffer)
              Return the length of the stringbuffer.

       int    raptor_stringbuffer_copy_to_string(raptor_stringbuffer*
       stringbuffer, unsigned char *string, size_t length)
              Copy the stringbuffer into a single string buffer string of size
              length.  Returns non-0 on failure.

IOSTREAM CLASS
       This class provides an I/O stream that can write to  filenames,  FILE*,
       strings and user-defined output via callbacks.

IOSTREAM CONSTRUCTOR
       raptor_iostream*  raptor_new_iostream_from_handler2(void*  context,
       const rap- tor_iostream_handler2 *handler)
              Create  a  new raptor read or write iostream from a user-defined
              raptor_iostream_handler2 handler that is called with the passed-
              in context for the write operations.

       raptor_iostream*  raptor_new_iostream_from_handler(void*  context,
       const rap- tor_iostream_handler *handler)
              DEPRECATED  in  1.4.17 - use raptor_new_iostream_from_handler2()
              with the new handler format.  Create a new raptor read  iostream
              from  a  user-defined  raptor_iostream_handler  handler  that is
              called with the passed-in context for the write operations.

       raptor_iostream* raptor_new_iostream_to_sink(void)
              Create a new raptor write iostream  that  discards  all  written
              output.

       raptor_iostream* raptor_new_iostream_to_filename(const char *filename)
              Create  a new raptor write iostream that creates and writes to a
              new file filename.

       raptor_iostream* raptor_new_iostream_to_file_handle(FILE *handle)
              Create a new raptor write iostream that creates and writes to an
              existing, already opened, C Standard I/O handle FILE* handle.

       raptor_iostream*    raptor_new_iostream_to_string(void    **string_p,
       size_t *length_p, void *(*malloc_handler)(size_t size))
              Create  a  new  raptor write iostream which creates a new string
              once raptor_free_iostream is called.  The new string pointer  is
              written  in string, the length in length_p (if not NULL) and the
              memory allocation is made using the malloc_handler, or if  NULL,
              raptor's default memory allocator.

       raptor_iostream* raptor_new_iostream_from_sink(void)
              Create  a  new raptor read iostream that is immediately finished
              and returns end of file.

       raptor_iostream* raptor_new_iostream_from_filename(const char *file-
       name)
              Create  a  new  raptor read iostream from an existing file file-
              name.



                            2008-06-19                         27





libraptor(3)                                         libraptor(3)


       raptor_iostream* raptor_new_iostream_from_file_handle(FILE *handle)
              Create a new raptor read iostream  from  an  already  opened,  C
              Standard I/O handle FILE* handler.

       raptor_iostream* raptor_new_iostream_from_string(void *string, size_t
       length)
              Create a new raptor  read  iostream  reading  from  an  existing
              string of length bytes.

IOSTREAM DESTRUCTOR
       void raptor_free_iostream(raptor_iostream *iostr)
              Destroy a Raptor iostream object.

IOSTREAM METHODS
       int   raptor_iostream_write_bytes(raptor_iostream  *iostr,  const  void
       *ptr, size_t size, size_t nmemb)
              Write  a  counted  set of elements to an iostream. Inmemb is the
              count of elements of size size, starting at memory ptr.  Similar
              to fwrite(3) and write(2).

       int raptor_iostream_write_byte(raptor_iostream *iostr, const int byte)
              Write a single byte an iostream.  Similar to fputc(3).

       void raptor_iostream_write_end(raptor_iostream *iostr)
              Finish writing to an iostream.

       int raptor_iostream_write_string(raptor_iostream *iostr, const void
       *string)
              Write a  NUL-terminated  string  to  an  iostream.   Similar  to
              fputs(3).

       int  raptor_iostream_write_counted_string(raptor_iostream  *iostr,
       const void *string, size_t len)
              Write a string of length len to an iostream.

       unsigned long raptor_iostream_tell(raptor_iostream *iostr)
              Return the byte offset into the iostream.

       size_t raptor_iostream_get_bytes_written_count(raptor_iostream *iostr)
              DEPRECATED  in  1.4.17  for  raptor_iostream_tell().  Return the
              number of bytes written so far to the iostream.

       int raptor_iostream_write_decimal(raptor_iostream *iostr, int integer)
              Write a decimal formatted integer integer to the iostream.

       int raptor_iostream_format_hexadecimal(raptor_iostream  *iostr,
       unsigned  int integer, int width)
              Write a hexadecimal formatted unsigned integer to the  iostream,
              left-padded with '0's to width columns.

       int  raptor_iostream_write_stringbuffer(raptor_iostream* iostr, rap-
       tor_string- buffer *sb)
              Write the stringbuffer to an iostream iostr.




                            2008-06-19                         28





libraptor(3)                                         libraptor(3)


       int raptor_iostream_read_bytes(raptor_iostream* iostr, void *ptr,
       size_t size, size_t nmemb)
              Read  bytes  from  the iostream into buffer ptr up to nmemb ele-
              ments of size size.

       int raptor_iostream_read_eof(raptor_iostream *iostr)
              Return non-0 if the iostream is finished.

XML SAX2 READER CLASS
       This class provides the functionality  to  generate  SAX2  events  from
       parsing XML content, including XML namespace support.

XML SAX2 CONSTRUCTOR
       raptor_sax2*     raptor_new_sax2(void    *user_data,    rap-
       tor_error_handlers* error_handlers)
              Create  a  new  SAX2  XML  reader  with  the given error handler
              object.

XML WRITER DESTRUCTOR
       void raptor_free_sax2(raptor_sax2 *sax2)
              Destroy a SAX2 XML reader object.

SAX2 SET HANDLER METHODS
       void     raptor_sax2_set_start_element_handler(raptor_sax2     *sax2,
       rap- tor_sax2_start_element_handler handler)
              Set the SAX2 start element handler.

       void     raptor_sax2_set_end_element_handler(raptor_sax2      *sax2,
       rap- tor_sax2_end_element_handler handler)
              Set the SAX2 end element handler.

       void raptor_sax2_set_characters_handler(raptor_sax2 *sax2, rap-
       tor_sax2_charac- ters_handler handler)
              Set the SAX2 character data element handler.

       void raptor_sax2_set_cdata_handler(raptor_sax2  *sax2,  rap-
       tor_sax2_cdata_han- dler handler)
              Set the SAX2 CDATA section element handler.

       void   raptor_sax2_set_comment_handler(raptor_sax2   *sax2,   rap-
       tor_sax2_com- ment_handler handler)
              Set the SAX2 XML comment handler.

       void  raptor_sax2_set_unparsed_entity_decl_handler(raptor_sax2   *sax2,
       rap- tor_sax2_unparsed_entity_decl_handler handler)
              Set the SAX2 XML unparsed entity declaration handler.

       void   raptor_sax2_set_external_entity_ref_handler(raptor_sax2   *sax2,
       rap- tor_sax2_external_entity_ref_handler handler)
              Set the SAX2 XML external entity reference handler.

       void   raptor_sax2_set_namespace_handler(raptor_sax2   *sax2,    rap-
       tor_names- pace_handler handler)
              Set the SAX2 XML  namespace  declaration  handler  when  an  XML



                            2008-06-19                         29





libraptor(3)                                         libraptor(3)


              namespace is declared.

SAX2 PARSING METHODS
       void raptor_sax2_parse_start(raptor_sax2 *sax2, raptor_uri *base_uri)
              Start a SAX2 parse of XML content with the base URI uri.

       int  raptor_sax2_parse_chunk(raptor_sax2  *sax2,  const unsigned char
       *buffer, size_t len, int is_end)
              Parse  the  XML  content  in  buffer  of size len returning SAX2
              events via handlers.  If is_end is non-zero,  it  indicates  the
              end  of  the parsing.  This method can only be called after rap-
              tor_sax2_parse_start().

SAX2 SCOPE METHODS
       const unsigned char* raptor_sax2_inscope_xml_language(raptor_sax2
       *sax2)
              Get the current in-scope XML language (xml:lang) value.

       raptor_uri* raptor_sax2_inscope_base_uri(raptor_sax2 *sax2)
              Get  the current in-scope Base URI (xml:base or document or pro-
              tocol) value.

XML ELEMENT CLASS
       This class provides an XML element that can be used with the XML Writer
       Class to generate XML documents.

XML ELEMENT CONSTRUCTORS
       raptor_xml_element*  raptor_new_xml_element(raptor_qname* name, const
       unsigned char* xml_language, raptor_uri* xml_base)
              Create  a new XML element with the element name name in the con-
              text of xml:lang xml_language and base URI xml_base.

       raptor_xml_element*      raptor_new_xml_element_from_names-
       pace_local_name(rap-   tor_namespace  *ns,  const  unsigned char *name,
       const unsigned char* xml_lan- guage, raptor_uri* xml_base
              Create a new XML element based on the given  XML  namespace  and
              localname in the context of xml:lang xml_languageFP and base URI
              xml_base.

XML ELEMENT DESTRUCTOR
       void raptor_free_xml_element(raptor_xml_element *element)
              Destroy a XML element object.

XML ELEMENT METHODS
       raptor_qname* raptor_xml_element_get_name(raptor_xml_element* xml_ele-
       ment)
              Get the XML element QName of XML element xml_element.

       void  raptor_xml_element_set_attributes(raptor_xml_element*
       xml_element, rap- tor_qname **attributes, int count)
              Set  the  attributes  on XML element xml_element to the array of
              QNames in array attributes of size count.





                            2008-06-19                         30





libraptor(3)                                         libraptor(3)


       raptor_qname** raptor_xml_element_get_attributes(raptor_xml_element*
       xml_ele- ment)
              Get the attributes of an XML element xml_element as an array  of
              QNames.  As set by void raptor_xml_element_set_attributes.

       int raptor_xml_element_get_attributes_count(raptor_xml_element*
       xml_element)
              Get the number of attributes of an XML  element  xml_element  as
              set by void raptor_xml_element_set_attributes.

       int raptor_xml_element_declare_namespace(raptor_xml_element*
       xml_element, rap- tor_namespace* nspace)
              Declare  an  XML  namespace  nspace  expliclitly  on XML element
              xml_element.  Namespaces used in the element or attribute  names
              are  automatically  declared, this method allows additional ones
              to be done.

       int raptor_xml_element_is_empty(raptor_xml_element* xml_element)
              Return non-0 if the XML element is empty.

       int raptor_iostream_write_xml_element(raptor_iostream* iostr,  rap-
       tor_xml_ele-        ment  *element, raptor_namespace_stack* nstack, int
       is_empty, int is_end, rap-    tor_simple_message_handler error_handler,
       void* error_data, int depth)
              Write  a XML element xml_element to iostream ostr.  This is done
              in context of an XML namespace stack nstack and at  depth  depth
              in the stack (see Namespace class constructors).

              The  element  may be an empty element if is_empty is non-zero or
              may be a close element if is_end is non-zero (else  is  a  start
              element).   The error_handler method along with error_data allow
              error reporting to be given.

       const   unsigned   char*   raptor_xml_element_get_language(rap-
       tor_xml_element* xml_element)
              Get the xml:lang language of the XML element.

XML WRITER CLASS
       This class provides the functionality to generate simple XML  documents
       consisting  of  elements  with attributes, character data and comments.
       The documents can be written to an iostream.

XML WRITER CONSTRUCTOR
       raptor_xml_writer* raptor_new_xml_writer(raptor_namespace_stack*
       nstack,  rap-         tor_uri_handler*  uri_handler, void* uri_context,
       raptor_iostream* iostr, rap-  tor_simple_message_handler error_handler,
       void *error_data, int canonicalize)
              Create  a  new  XML  Writer  writing  to  iostream  iostr.   The
              error_handler method along with error_data allow error reporting
              to be given.  nstack is either an existing namespace stack to be
              used or if NULL, a new one with only the XML  namespace  defined
              is  created.   Note that raptor_uri_get_handler can be useful to
              return the current raptor URI handler/context.  canonicalize  is
              currently  unused  and  should  be  set  to 1 but may allow non-



                            2008-06-19                         31





libraptor(3)                                         libraptor(3)


              canonical XML writing to be allowed in future.

XML WRITER DESTRUCTOR
       void raptor_free_xml_writer(raptor_xml_writer* xml_writer)
              Destroy a XML Writer object.

XML WRITER METHODS
       void   raptor_xml_writer_empty_element(raptor_xml_writer*   xml_writer,
       rap- tor_xml_element *element)
              Write XML element element as an empty element (no  element  con-
              tent) to the XML Writer xml_writer.

       void   raptor_xml_writer_start_element(raptor_xml_writer*   xml_writer,
       rap- tor_xml_element *element)
              Write  a  start  element  along with an attributes and namespace
              declarations  for  XML  element  element  to  the   XML   Writer
              xml_writer.

       void    raptor_xml_writer_end_element(raptor_xml_writer*    xml_writer,
       rap- tor_xml_element *element)
              Write  an  end  element  form for XML element element to the XML
              Writer xml_writer.

       void  raptor_xml_writer_cdata(raptor_xml_writer*  xml_writer,  const
       unsigned char *str)
              Write XML character data in str to the  XML  Writer  xml_writer.
              The characters in str will be XML escaped.

       void   raptor_xml_writer_cdata_counted(raptor_xml_writer*   xml_writer,
       const unsigned char* str, unsigned int length)
              Write  XML  character  data  in  str of length length to the XML
              Writer xml_writer.  The characters in str will be XML escaped.

       void raptor_xml_writer_raw(raptor_xml_writer* xml_writer, const
       unsigned char* str)
              Write character data in str length to the XML Writer  xml_writer
              without XML escaping.

       void    raptor_xml_writer_raw_counted(raptor_xml_writer*   xml_writer,
       const unsigned char* str, unsigned int length)
              Write  character  data in str of length length to the XML Writer
              xml_writer without XML escaping.

       void raptor_xml_writer_comment(raptor_xml_writer* xml_writer,  const
       unsigned char* str)
              Write an XML comment in str to the XML Writer xml_writer.

       void  raptor_xml_writer_comment_counted(raptor_xml_writer*  xml_writer,
       const unsigned char* str, unsigned int length)
              Write an XML comment in str of length length to the  XML  Writer
              xml_writer.

       int  raptor_xml_writer_features_enumerate(const  raptor_feature
       feature, const char **name, raptor_uri **uri, const char **label)



                            2008-06-19                         32





libraptor(3)                                         libraptor(3)


              Return  the  name,  URI,  string label (all optional) for an XML
              write feature, returning non-zero if no such feature exists.

       Raptor features have URIs that are constructed from the URI http://fea-
       ture.librdf.org/raptor-  and the name so for example feature scanForRDF
       has URI http://feature.librdf.org/raptor-scanForRDF

       int raptor_xml_writer_set_feature(raptor_xml_writer*  xml_writer,  rap-
       tor_fea- ture feature, int value)
              Set an  XML  writer  feature  feature  to  a  particular  value.
              Returns non 0 on failure or if the feature is unknown.  The cur-
              rent defined writer features are:
                Feature                                 Values
                RAPTOR_FEATURE_WRITER_AUTO_INDENT       Boolean (non 0 true)
                RAPTOR_FEATURE_WRITER_AUTO_EMPTY        Boolean (non 0 true)
                RAPTOR_FEATURE_WRITER_INDENT_WIDTH      Integer
                RAPTOR_FEATURE_WRITER_XML_DECLARATION   Boolean (non 0 true)

       If the writer_auto_indent feature is set (default true), the XML writer
       will automatically indent the output.

       If  the writer_auto_empty feature is set (default true), the XML writer
       will automatically generate  empty  elements  if  a  start/end  element
       sequence has no content.

       If the writer_indent_width feature is set (default 2) if the XML writer
       is outputing indented XML, it will use that many spaces.

       If the writer_xml_declaration feature is set  (default  true)  the  XML
       declaration is written at the start of serialized XML.

       int  raptor_xml_writer_set_feature_string(raptor_xml_writer
       *xml_writer, rap- tor_feature feature, const unsigned char *value)
              Set  an XML writer feature feature to a particular string value.
              Returns non 0 on failure or if the feature is unknown.  The cur-
              rent   defined   XML   writer   features   are   given  in  rap-
              tor_xml_writer_set_feature and at present only take integer val-
              ues.  If  an  integer  value  feature is set with this function,
              value is interpreted as an integer and then that value is  used.

       int  raptor_xml_writer_get_feature(raptor_xml_writer*  xml_writer, rap-
       tor_fea- ture feature)
              Get XML writer feature integer values.  The allowed feature val-
              ues and types are given under raptor_xml_writer_features_enumer-
              ate.

       const  unsigned  char *raptor_xml_writer_get_feature_string(rap-
       tor_xml_writer* xml_writer, raptor_feature feature)
              Get XML writer feature string values. The allowed feature values
              and types are given under  raptor_xml_writer_features_enumerate.

       int raptor_xml_writer_get_depth(raptor_xml_writer* xml_writer)
              Get the current XML writer element stack depth.




                            2008-06-19                         33





libraptor(3)                                         libraptor(3)


       void raptor_xml_writer_flush(raptor_xml_writer* xml_writer)
              Flush the XML writer output for any pending writes.

       void raptor_xml_writer_newline(raptor_xml_writer* xml_writer)
              Write  a  newline to the XML writer (which may trigger indenting
              before the next item).

API CHANGES
   1.4.18
       Added atom serializer

       Added rdfa parser

       Added serializer features  RAPTOR_FEATURE_RSS_TRIPLES  and  RAPTOR_FEA-
       TURE_ATOM_ENTRY_URI

       Added raptor_qname_to_counted_name

       Added raptor_serialize_start_to_iostream

       Added raptor_sequence_delete_at

       Added raptor_xml_writer_newline

       Added raptor_xml_writer_flush

       Added raptor_xml_writer_get_depth

   1.4.17
       Added  SAX2  class  raptor_sax2.   Added  new  SAX2  API typedefs: rap-
       tor_sax2_start_element_handler,  raptor_sax2_end_element_handler,  rap-
       tor_sax2_characters_handler,       raptor_sax2_cdata_handler,      rap-
       tor_sax2_comment_handler, raptor_sax2_unparsed_entity_decl_handler  and
       raptor_sax2_external_entity_ref_handler.  Added new SAX2 API functions:
       raptor_new_sax2(),    raptor_free_sax2(),    raptor_sax2_set_start_ele-
       ment_handler(),       raptor_sax2_set_end_element_handler(),       rap-
       tor_sax2_set_characters_handler(),     raptor_sax2_set_cdata_handler(),
       raptor_sax2_set_comment_handler(),                                 rap-
       tor_sax2_set_unparsed_entity_decl_handler(),     raptor_sax2_set_exter-
       nal_entity_ref_handler(),   raptor_sax2_set_namespace_handler(),   rap-
       tor_sax2_parse_start(),         raptor_sax2_parse_chunk(),         rap-
       tor_sax2_inscope_xml_language() and raptor_sax2_inscope_base_uri()

       Added      features      RAPTOR_FEATURE_WRITE_BASE_URI,     RAPTOR_FEA-
       TURE_WWW_HTTP_CACHE_CONTROL,  RAPTOR_FEATURE_WWW_HTTP_USER_AGENT,  RAP-
       TOR_FEATURE_JSON_CALLBACK and RAPTOR_FEATURE_JSON_EXTRA_DATA

       Added raptor_handler_closure structure for error handlers.

       Added raptor_statement_compare()

       Added   raptor_iostream_write_string_python()   and   deprecated   rap-
       tor_iostream_write_string_turtle()




                            2008-06-19                         34





libraptor(3)                                         libraptor(3)


       raptor_uri_set_handler(),  raptor_uri_get_handler(),  raptor_new_names-
       paces(),  raptor_namespaces_init() and raptor_new_xml_writer() now take
       const handler pointers.

       Added raptor_www_set_http_cache_control()

       Added  QName   class   methods:   raptor_qname_get_local_name(),   rap-
       tor_qname_get_value() and raptor_qname_get_counted_value()

       Added      raptor_iostream      read      handler     typedefs     rap-
       tor_iostream_read_bytes_func, raptor_iostream_read_eof_func  and  added
       new   structure   raptor_iostream_handler2  replacing  deprecated  rap-
       tor_iostream_handler.

       Added  raptor_new_iostream_from_handler2()  replacing  deprecated  rap-
       tor_new_iostream_from_handler()

       Added  raptor_new_iostream_from_sink(),  raptor_new_iostream_from_file-
       name(),      raptor_new_iostream_from_file_handle()      and       rap-
       tor_new_iostream_from_string().

       Added  raptor_iostream_tell deprecating raptor_iostream_get_bytes_writ-
       ten_count().

       Added raptor_iostream_read_bytes() and raptor_iostream_read_eof().

       Added raptor_xml_element_get_language().

       Added new enum raptor_log_level.

       Added  new  typedef  raptor_error_handlers.   and  new  function   rap-
       tor_error_handlers_init().

   1.4.16
       raptor_namespaces_init now returns an integer status

       Added raptor_new_xml_element_from_namespace_local_name

       Added raptor_uri_compare.

       Added    new    features    for   the   'grddl'   parser:   RAPTOR_FEA-
       TURE_HTML_TAG_SOUP,   RAPTOR_FEATURE_MICROFORMATS    and    RAPTOR_FEA-
       TURE_HTML_LINK.

       Added parser feature RAPTOR_FEATURE_WWW_TIMEOUT

       Added raptor_graph_handler typedef and raptor_set_graph_handler

       Added      raptor_www_final_uri_handler      typedef      and      rap-
       tor_www_set_final_uri_handler

       Added raptor_www_set_connection_timeout

       Added raptor_www_get_final_uri



                            2008-06-19                         35





libraptor(3)                                         libraptor(3)


   1.4.15
       No changes.

   1.4.14
       Add  two  new   exported   strings   raptor_license_string   and   rap-
       tor_home_url_string.

       Added    new   features   for   the   'dot'   serializer:   RAPTOR_FEA-
       TURE_RESOURCE_BORDER,    RAPTOR_FEATURE_LITERAL_BORDER,     RAPTOR_FEA-
       TURE_BNODE_BORDER,   RAPTOR_FEATURE_RESOURCE_FILL,  RAPTOR_FEATURE_LIT-
       ERAL_FILL and RAPTOR_FEATURE_BNODE_FILL

       Added raptor_parser_generate_id

       Added raptor_iostream_write_string_turtle

   1.4.13
       No API changes.

   1.4.12
       No API changes.

   1.4.11
       Added raptor_get_feature_count

       Added raptor_get_need_base_uri

       Added parser feature RAPTOR_FEATURE_NO_NET

       Added raptor_www_set_uri_filter, raptor_parser_set_uri_filter with fil-
       ter type raptor_uri_filter_func

   1.4.10
       No API changes.

   1.4.9
       Added raptor_parser_get_accept_header

       Added raptor_xml_element_is_empty

       Added raptor_qname_get_namespace

       Added raptor_iostream_write_uri

       Added raptor_namespaces_qname_from_uri.

       Added raptor_namespace_get_counted_prefix

       Added raptor_serialize_set_namespace_from_namespace

       Deprecated        raptor_uri_is_file_uri       for       new       rap-
       tor_uri_string_is_file_uri.

       Added               raptor_xml_element_get_attributes               and



                            2008-06-19                         36





libraptor(3)                                         libraptor(3)


       raptor_xml_element_get_attributes_count

   1.4.8
       Added raptor_set_namespace_handler.

       Added    XML    1.1    serializing    support,    feature   RAPTOR_FEA-
       TURE_WRITER_XML_VERSION with shortname xmlVersion  for  serializer  and
       xml writer classes to support it.  Added XML writer feature RAPTOR_FEA-
       TURE_WRITER_XML_DECLARATION to control generation of the  XML  declara-
       tion.    Added  new  functions  raptor_xml_any_escape_string  and  rap-
       tor_iostream_write_xml_any_escaped_string to allow generating  XML  1.1
       or XML 1.0.

       RAPTOR_IDENTIFIER_TYPE_PREDICATE  will no longer be generated from ver-
       sion 1.4.9 onwards as the type of returned statement predicates.   RAP-
       TOR_IDENTIFIER_TYPE_RESOURCE will be returned.

       RAPTOR_IDENTIFIER_TYPE_ORDINAL  may no longer be generated from version
       1.4.9 onwards, RAPTOR_IDENTIFIER_TYPE_RESOURCE may replace it.

   1.4.7
       No changes.

   1.4.6
       No changes.

   1.4.5
       Deprecated  raptor_ntriples_string_as_utf8_string   (never   documented
       above)  since  it can only work with a raptor_parser object which makes
       it rather unusable alone.

       Added XML writer features and support functions  raptor_xml_writer_fea-
       tures_enumerate,           raptor_xml_writer_set_feature,          rap-
       tor_xml_writer_set_feature_string,  raptor_xml_writer_get_feature   and
       raptor_xml_writer_get_feature_string

   1.4.3
       Added  XML Writer class (raptor_xml_writer) and XML Element class (rap-
       tor_xml_element)

       Added     raptor_parser_get_feature_string,      raptor_parser_set_fea-
       ture_string,    raptor_serializer_set_feature_string,    raptor_serial-
       izer_get_feature_string and raptor_feature_value_type.

       Added  raptor_serializer_set_namespace,   raptor_serializer_set_feature
       and raptor_serializer_get_feature.

       Added          raptor_new_namespace_from_uri,         raptor_new_names-
       pace_parts_from_string, Added  raptor_namespaces_find_namespace_by_uri.
       and raptor_iostream_write_namespace to write a namespace declaration to
       an iostream.

       Added     copy     constructor     raptor_qname_copy      and      rap-
       tor_iostream_write_qname to write a qname to an iostream.



                            2008-06-19                         37





libraptor(3)                                         libraptor(3)


       Added raptor_sequence_join to join two sequences, leaving one empty.

       Added  raptor_iostream_write_stringbuffer to write a stringbuffer to an
       iostream.

       Added   N-Triples   raptor_iostream_write_string_ntriples   and    rap-
       tor_iostream_write_statement_ntriples  utility functions for writing to
       raptor_iostreams.

       Added  raptor_uri_to_relative_counted_uri_string,   raptor_uri_to_rela-
       tive_uri_string.   raptor_uri_print,  raptor_uri_to_counted_string  and
       raptor_uri_to_string

       Added unicode name checking utility functions for XML 1.0 and  XML  1.1
       name  starting  character  and  continued  name character.  raptor_uni-
       code_is_xml10_namestartchar   raptor_unicode_is_xml10_namechar,    rap-
       tor_unicode_is_xml11_namechar     and    raptor_unicode_is_xml11_names-
       tartchar.

       Added raptor_xml_name_check to check if a name is a legal  XML  1.0  or
       1.0  name.   and  raptor_iostream_write_xml_escaped_string  to write an
       XML-escaped string to an iostream.

       Added UTF8-checking utility function raptor_utf8_check.

   1.4.2
       No changes.

   1.4.1
       The raptor_xml_escape_string now returns <0 on failure rather  than  0,
       so that if an empty string is escaped, 0 bytes required is returned.

   1.4.0
       Added  new raptor_serializer class supporting RDF/XML (name rdfxml) and
       N-Triples (name ntriples).
       Added new raptor_iostream class
       Added raptor_stringbuffer_copy_to_string to allow efficient copy-out of
       a constructed string.
       Added  raptor_www_fetch_to_string to allow retrieving of web content as
       a single string.

   1.3.3
       Added raptor_calloc_memory to provide a calloc inside raptor.
       Added feature check_rdf_id (see raptor_set_feature documentation).

   1.3.2
       Added raptor_alloc_memory to allocate memory inside raptor.

       Added accessor functions for the public raptor_locator structure:

       raptor_locator_line
       raptor_locator_column
       raptor_locator_byte
       raptor_locator_file



                            2008-06-19                         38





libraptor(3)                                         libraptor(3)


       raptor_locator_uri

   1.3.1
       Correct raptor_print_statement declaration argument statement  to  have
       one less 'const', to match the code.

   1.3.0
       Added  the  following  parser methods, utility methods and helper func-
       tions:

       raptor_new_parser_for_content (Parser class constructor)
       raptor_get_mime_type
       raptor_get_feature
       raptor_syntax_name_check
       raptor_guess_parser_name
       raptor_features_enumerate
       raptor_feature_from_uri
       raptor_www_set_http_accept (WWW class)

       Changed raptor_set_feature to now return an int success or failure.

       Added the following functions:
       raptor_free_memory
       raptor_unicode_char_to_utf8
       raptor_utf8_to_unicode_char
       raptor_vsnprintf

       Added the raptor_sequence class, its constructor,  destructor,  methods
       and helper functions.

       Added  the  raptor_stringbuffer  class  and constructor, destructor and
       methods.

       Deprecated raptor_print_statement_detailed always intended to be inter-
       nal.

   1.2.0
       Added  raptor_syntaxes_enumerate to get full information on syntax mime
       type and URIs as well as name and label.

       N-Triples Plus parser renamed to Turtle (name turtle)

   1.1.0
       Added N-Triples Plus parser (name ntriples-plus)

       Made URI class constructors, methods and factory  methods  as  well  as
       some  other  utility functions using or returning URIs or literals take
       unsigned char* rather than char*.  The affected calls are:

       URI factory methods changed to all take/return unsigned char*  for  URI
       strings:
       raptor_new_uri_func
       raptor_new_uri_from_local_name_func
       raptor_new_uri_relative_to_base_func



                            2008-06-19                         39





libraptor(3)                                         libraptor(3)


       raptor_uri_as_string_func
       raptor_uri_as_counted_string_func

       Constructors  and methods changed to take/return unsigned char* for URI
       strings:
       raptor_statement_part_as_counted_string
       raptor_statement_part_as_string
       raptor_new_uri
       raptor_new_uri_from_uri_local_name
       raptor_new_uri_relative_to_base
       raptor_uri_as_string
       raptor_uri_as_counted_string
       raptor_print_ntriples_string

       Changed to use unsigned char* for URI strings, char* for filenames:
       raptor_uri_resolve_uri_reference
       raptor_uri_filename_to_uri_string
       raptor_uri_uri_string_to_filename
       raptor_uri_uri_string_to_filename_fragment
       raptor_uri_is_file_uri

       Changed to return unsigned char* for UTF8 string:
       raptor_ntriples_string_as_utf8_string

       Added raptor_parsers_enumerate to discover supported parsers.

       Added raptor_uri_uri_string_to_filename_fragment with fragment  arg  to
       return the URI fragment.

       Made  the  raptor_namespace,  raptor_namespace_stack  and  raptor_qname
       class and APIs public.

       Added feature non_nfc_fatal (see raptor_set_feature documentation).

   1.0.0
       Removed the following  deprecated  methods  and  functions  (see  0.9.6
       changes for the new names):
       raptor_free,   raptor_new,  raptor_ntriples_free,  raptor_ntriples_new,
       raptor_ntriples_parse_file,   raptor_ntriples_set_error_handler,   rap-
       tor_ntriples_set_fatal_error_handler,        raptor_ntriples_set_state-
       ment_handler and raptor_parser_abort.

       Added raptor_parse_file_stream for reading FILE* streams without neces-
       sarily having a file.

   0.9.12
       Added  raptor_new_uri_for_retrieval  to  turn  URI references into URIs
       suitable for retrieval (no fragments).

   0.9.11
       Added raptor_get_name and raptor_get_label.

       raptor_xml_escape_string now takes error message handler, data pointer,
       loses parser argument.



                            2008-06-19                         40





libraptor(3)                                         libraptor(3)


       Added  raptor_set_default_generate_id_parameters  and raptor_set_gener-
       ate_id_handler to control the default generation  of  IDs,  allow  full
       customisation.

   0.9.10
       Added  raptor_set_parser_strict and raptor_www_no_www_library_init_fin-
       ish.

       raptor_xml_escape_string now takes an output string length pointer.

       Added      raptor_statement_part_as_counted_string,       raptor_state-
       ment_part_as_string and raptor_parse_abort.

       Deprecated raptor_parser_abort.

   0.9.9
       Added  raptor_www  class and all its constructors, destructor, methods,
       calls.

       Added        raptor_parse_uri,        raptor_parser_abort,         rap-
       tor_ntriples_term_as_string and raptor_xml_escape_string.

   0.9.7
       raptor_parse_chunk,  raptor_new_uri_from_id, arguments are now unsigned
       char.

       Added raptor_new_uri_for_xmlbase.

   0.9.6
       In this version, the raptor/ntriples parser calling APIs were modified.
       The following table lists the changes:

       OLD API                                  NEW API (0.9.6+)
       raptor_new()                             raptor_new_parser("rdfxml")
       ntriples_new()                           raptor_new_parser("ntriples")
       raptor_free                              raptor_free_parser
       ntriples_free                            raptor_ntriples_parser
       raptor_ntriples_parse_file               raptor_parse_file
       raptor_ntriples_set_error_handler        raptor_set_error_handler
       raptor_ntriples_set_fatal_error_handler  raptor_set_fatal_error_handler
       raptor_ntriples_set_statement_handler    raptor_set_statement_handler

CONFORMING TO
       RDF/XML Syntax  (Revised),  Dave  Beckett  (ed.)   W3C  Recommendation,
       http://www.w3.org/TR/rdf-syntax-grammar/

       N-Triples,  in  RDF  Test Cases, Jan Grant and Dave Beckett (eds.)  W3C
       Recommendation, http://www.w3.org/TR/rdf-testcases/#ntriples

       Turtle    -    Terse    RDF    Triple    Language,    Dave     Beckett,
       http://www.dajobe.org/2004/01/turtle/

       RSS     0.91     spec     revision     3,    Dan    Libby,    Netscape,
       http://my.netscape.com/publish/formats/rss-spec-0.91.html



                            2008-06-19                         41





libraptor(3)                                         libraptor(3)


       RDF Site Summary (RSS) 1.0, http://purl.org/rss/1.0/spec

       Atom       1.0       syndication        format,        RFC        4287,
       http://www.ietf.org/rfc/rfc4287.txt

       Gleaning  Resource Descriptions from Dialects of Languages (GRDDL), Dan
       Connolly       (ed.),       W3C       Recommendation,       2007-09-11,
       http://www.w3.org/TR/2007/REC-grddl-20070911/


SEE ALSO
       rapper(1),raptor-config(1)

AUTHOR
       Dave Beckett - http://purl.org/net/dajobe/










































                            2008-06-19                         42


