XML Namespaces

## XML Namespaces 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()` for the values of `defaults`.

`uri_handler` and `uri_context` parameters are ignored but are retained in the API for backwards compatibility. Internally the same uri handler as returned by `raptor_uri_get_handler()` will be used.

`raptor_init()` MUST have been called before calling this function. Use `raptor_new_namespaces_v2()` if using raptor_world APIs.

`uri_handler` : | URI handler function (ignored)
`uri_context` : | URI handler context data (ignored)
`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.

`uri_handler` and `uri_context` parameters are ignored but are retained in the API for backwards compatibility. Internally the same uri handler as returned by `raptor_uri_get_handler()` will be used.

`raptor_init()` MUST have been called before calling this function. Use `raptor_namespaces_init_v2()` if using raptor_world APIs.

`nstack` : | raptor_namespace_stack to initialise
`uri_handler` : | URI handler function (ignored)
`uri_context` : | context for URI handler (ignored)
`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);

`nstack` : |
`prefix` : |
`ns_uri_string` : |
`depth` : |
Returns : |

### 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