XML Namespaces
3
RAPTOR Library

# XML Namespaces

Namespaces in XML include stacks of Namespaces

## Synopsis

    typedef             raptor_namespace;
    raptor_namespace*   raptor_new_namespace_from_uri       (raptor_namespace_stack *nstack,
                                                             unsigned char *prefix,
                                                             raptor_uri *ns_uri,
                                                             int depth);
    raptor_namespace_stack* raptor_new_namespaces           (const 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,
                                                             const raptor_uri_handler *uri_handler,
                                                             void *uri_context,
                                                             raptor_simple_message_handler error_handler,
                                                             void *error_data,
                                                             int defaults);
    void                raptor_namespaces_clear             (raptor_namespace_stack *nstack);
    void                raptor_free_namespaces              (raptor_namespace_stack *nstack);
    void                raptor_namespaces_start_namespace   (raptor_namespace_stack *nstack,
                                                             raptor_namespace *nspace);
    int                 raptor_namespaces_start_namespace_full
                                                            (raptor_namespace_stack *nstack,
                                                             unsigned char *prefix,
                                                             unsigned char *ns_uri_string,
                                                             int depth);
    void                raptor_namespaces_end_for_depth     (raptor_namespace_stack *nstack,
                                                             int depth);
    raptor_namespace*   raptor_namespaces_get_default_namespace
                                                            (raptor_namespace_stack *nstack);
    raptor_namespace*   raptor_namespaces_find_namespace    (raptor_namespace_stack *nstack,
                                                             unsigned char *prefix,
                                                             int prefix_length);
    raptor_namespace*   raptor_namespaces_find_namespace_by_uri
                                                            (raptor_namespace_stack *nstack,
                                                             raptor_uri *ns_uri);
    int                 raptor_namespaces_namespace_in_scope
                                                            (raptor_namespace_stack *nstack,
                                                             const raptor_namespace *nspace);
    raptor_namespace*   raptor_new_namespace                (raptor_namespace_stack *nstack,
                                                             unsigned char *prefix,
                                                             unsigned char *ns_uri_string,
                                                             int depth);
    void                raptor_free_namespace               (raptor_namespace *ns);
    int                 raptor_namespace_copy               (raptor_namespace_stack *nstack,
                                                             raptor_namespace *ns,
                                                             int new_depth);
    raptor_uri*         raptor_namespace_get_uri            (const raptor_namespace *ns);
    const unsigned char* raptor_namespace_get_prefix        (const raptor_namespace *ns);
    const unsigned char* raptor_namespace_get_counted_prefix
                                                            (const raptor_namespace *ns,
                                                             size_t *length_p);
    unsigned char*      raptor_namespaces_format            (const raptor_namespace *ns,
                                                             size_t *length_p);
    int                 raptor_iostream_write_namespace     (raptor_iostream *iostr,
                                                             raptor_namespace *ns);
    int                 raptor_new_namespace_parts_from_string
                                                            (unsigned char *string,
                                                             unsigned char **prefix,
                                                             unsigned char **uri_string);
    typedef             raptor_namespace_stack;
    raptor_qname*       raptor_namespaces_qname_from_uri    (raptor_namespace_stack *nstack,
                                                             raptor_uri *uri,
                                                             int xml_version);

## Description

Two classes that provide an XML namespace - short prefix (or none) and absolute URI (or none) to match the form `xmlns...="..."` seen in XML. A stack of namespaces raptor_namespace_stack is also provided to handle in-scope namespace calculations that happen inside XML documents where inner namespaces can override outer ones.

## Details

### raptor_namespace

    raptor_namespace* raptor_namespace;

Raptor XML Namespace class

### raptor_new_namespace_from_uri ()

    raptor_namespace*   raptor_new_namespace_from_uri       (raptor_namespace_stack *nstack,
                                                             unsigned char *prefix,
                                                             raptor_uri *ns_uri,
                                                             int depth);

Constructor - create a new namespace from a prefix and URI object.

`nstack` :

  namespace stack

`prefix` :

  namespace prefix string

`ns_uri` :

  namespace URI

`depth` :

  depth of namespace in the stack

Returns :

  a new raptor_namespace or NULL on failure

### raptor_new_namespaces ()

    raptor_namespace_stack* raptor_new_namespaces           (const raptor_uri_handler *uri_handler,
                                                             void *uri_context,
                                                             raptor_simple_message_handler error_handler,
                                                             void *error_data,
                                                             int defaults);

Constructor - create a new raptor_namespace_stack.

See `raptor_namespaces_init()` fo the values of `defaults`.

`uri_handler` :

  URI handler function

`uri_context` :

  URI handler context data

`error_handler` :

  error handler function

`error_data` :

  error handler data

`defaults` :

  namespaces to initialise

Returns :

  a new namespace stack or NULL on failure

### raptor_namespaces_init ()

    int                 raptor_namespaces_init              (raptor_namespace_stack *nstack,
                                                             const raptor_uri_handler *uri_handler,
                                                             void *uri_context,
                                                             raptor_simple_message_handler error_handler,
                                                             void *error_data,
                                                             int defaults);

Initialise a namespaces stack some optional common namespaces.

`defaults` can be 0 for none, 1 for just XML, 2 for RDF, RDFS, OWL and XSD (RDQL uses this) or 3+ undefined.

`nstack` :

  raptor_namespace_stack to initialise

`uri_handler` :

  URI handler function

`uri_context` :

  context for URI handler

`error_handler` :

  error handler function

`error_data` :

  context for error handler

`defaults` :

  namespaces to initialise.

Returns :

  non-0 on error

### raptor_namespaces_clear ()

    void                raptor_namespaces_clear             (raptor_namespace_stack *nstack);

Empty a namespace stack of namespaces and any other resources.

`nstack` :

  namespace stack

### raptor_free_namespaces ()

    void                raptor_free_namespaces              (raptor_namespace_stack *nstack);

Destructor - destroy a namespace stack

`nstack` :

  namespace stack

### raptor_namespaces_start_namespace ()

    void                raptor_namespaces_start_namespace   (raptor_namespace_stack *nstack,
                                                             raptor_namespace *nspace);

Start a namespace on a stack of namespaces.

`nstack` :

  namespace stack

`nspace` :

  namespace to start

### raptor_namespaces_start_namespace_full ()

    int                 raptor_namespaces_start_namespace_full
                                                            (raptor_namespace_stack *nstack,
                                                             unsigned char *prefix,
                                                             unsigned char *ns_uri_string,
                                                             int depth);

Create a new namespace and start it on a stack of namespaces.

See `raptor_new_namespace()` for the meanings of `prefix`, `ns_uri_string` and `depth` for namespaces.

`nstack` :

  namespace stack

`prefix` :

  new namespace prefix (or NULL)

`ns_uri_string` :

  new namespace URI (or NULL)

`depth` :

  new namespace depth

Returns :

  non-0 on failure

### raptor_namespaces_end_for_depth ()

    void                raptor_namespaces_end_for_depth     (raptor_namespace_stack *nstack,
                                                             int depth);

End all namespaces at the given depth in the namespace stack.

`nstack` :

  namespace stack

`depth` :

  depth

### raptor_namespaces_get_default_namespace ()

    raptor_namespace*   raptor_namespaces_get_default_namespace
                                                            (raptor_namespace_stack *nstack);

Get the current default namespace in-scope in a stack.

`nstack` :

  namespace stack

Returns :

  raptor_namespace or NULL if no default namespace is in scope

### raptor_namespaces_find_namespace ()

    raptor_namespace*   raptor_namespaces_find_namespace    (raptor_namespace_stack *nstack,
                                                             unsigned char *prefix,
                                                             int prefix_length);

Find a namespace in a namespace stack by prefix.

Note that this uses the `length` so that the prefix may be a prefix (sic) of a longer string. If `prefix` is NULL, the default namespace will be returned if present, `prefix_length` length is ignored in this case.

`nstack` :

  namespace stack

`prefix` :

  namespace prefix to find

`prefix_length` :

  length of prefix.

Returns :

  raptor_namespace for the prefix or NULL on failure

### raptor_namespaces_find_namespace_by_uri ()

    raptor_namespace*   raptor_namespaces_find_namespace_by_uri
                                                            (raptor_namespace_stack *nstack,
                                                             raptor_uri *ns_uri);

Find a namespace in a namespace stack by namespace URI.

`nstack` :

  namespace stack

`ns_uri` :

  namespace URI to find

Returns :

  raptor_namespace for the URI or NULL on failure

### raptor_namespaces_namespace_in_scope ()

    int                 raptor_namespaces_namespace_in_scope
                                                            (raptor_namespace_stack *nstack,
                                                             const raptor_namespace *nspace);

Test if a given namespace is in-scope in the namespace stack.

`nstack` :

  namespace stack

`nspace` :

  namespace

Returns :

  non-0 if the namespace is in scope.

### raptor_new_namespace ()

    raptor_namespace*   raptor_new_namespace                (raptor_namespace_stack *nstack,
                                                             unsigned char *prefix,
                                                             unsigned char *ns_uri_string,
                                                             int depth);

Constructor - create a new namespace from a prefix and URI string.

`nstack` :

  namespace stack

`prefix` :

  namespace prefix string

`ns_uri_string` :

  namespace URI string

`depth` :

  depth of namespace in the stack

Returns :

  a new raptor_namespace or NULL on failure

### raptor_free_namespace ()

    void                raptor_free_namespace               (raptor_namespace *ns);

Destructor - destroy a namespace.

`ns` :

  namespace object

### raptor_namespace_copy ()

    int                 raptor_namespace_copy               (raptor_namespace_stack *nstack,
                                                             raptor_namespace *ns,
                                                             int new_depth);

Copy a namespace to a new namespace stack with a new depth.

`nstack` :

  namespace stack

`ns` :

  namespace

`new_depth` :

  new depth

Returns :

  non-0 on failure

### raptor_namespace_get_uri ()

    raptor_uri*         raptor_namespace_get_uri            (const raptor_namespace *ns);

Get the namespace URI.

`ns` :

  namespace object

Returns :

  namespace URI or NULL

### raptor_namespace_get_prefix ()

    const unsigned char* raptor_namespace_get_prefix        (const raptor_namespace *ns);

Get the namespace prefix.

`ns` :

  namespace object

Returns :

  prefix string or NULL

### raptor_namespace_get_counted_prefix ()

    const unsigned char* raptor_namespace_get_counted_prefix
                                                            (const raptor_namespace *ns,
                                                             size_t *length_p);

Get the namespace prefix and length.

`ns` :

  namespace object

`length_p` :

  pointer to store length or NULL

Returns :

  prefix string or NULL

### raptor_namespaces_format ()

    unsigned char*      raptor_namespaces_format            (const raptor_namespace *ns,
                                                             size_t *length_p);

Format a namespace in an XML style into a newly allocated string.

Generates a string of the form xmlns:prefix="uri", xmlns="uri", xmlns:prefix="" or xmlns="" depending on the namespace's prefix or URI. Double quotes are always used.

If `length_p` is not NULL, the length of the string is stored in the address it points to.

See also `raptor_new_namespace_parts_from_string()`

`ns` :

  namespace object

`length_p` :

  pointer to length (or NULL)

Returns :

  namespace formatted as newly allocated string or NULL on failure

### raptor_iostream_write_namespace ()

    int                 raptor_iostream_write_namespace     (raptor_iostream *iostr,
                                                             raptor_namespace *ns);

Write a formatted namespace to an iostream

`iostr` :

  raptor iosteram

`ns` :

  namespace to write

Returns :

  non-0 on failure

### raptor_new_namespace_parts_from_string ()

    int                 raptor_new_namespace_parts_from_string
                                                            (unsigned char *string,
                                                             unsigned char **prefix,
                                                             unsigned char **uri_string);

Parse a string containin an XML style namespace declaration into a namespace prefix and URI.

The string is of the form xmlns:prefix="uri", xmlns="uri", xmlns:prefix="" or xmlns="". The quotes can be single or double quotes.

Two values are returned from this function into *`prefix` and *`uri_string` neither of which may be NULL.

See also `raptor_namespaces_format()`

`string` :

  string to parse

`prefix` :

  pointer to location to store namespace prefix

`uri_string` :

  pointer to location to store namespace URI

Returns :

  non-0 on failure.

### raptor_namespace_stack

    raptor_namespace_stack* raptor_namespace_stack;

Raptor XML Namespace Stack class

### raptor_namespaces_qname_from_uri ()

    raptor_qname*       raptor_namespaces_qname_from_uri    (raptor_namespace_stack *nstack,
                                                             raptor_uri *uri,
                                                             int xml_version);

Make an appropriate XML Qname from the namespaces on a namespace stack

Makes a qname from the in-scope namespaces in a stack if the URI matches the prefix and the rest is a legal XML name.

`nstack` :

  namespace stack

`uri` :

  URI to use to make qname

`xml_version` :

  XML Version

Returns :

  raptor_qname for the URI or NULL on failure