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,
                                                             const unsigned char *prefix,
                                                             raptor_uri *ns_uri,
                                                             int depth);
    raptor_namespace_stack * raptor_new_namespaces          (raptor_world *world,
                                                             int defaults);
    int                 raptor_namespaces_init              (raptor_world *world,
                                                             raptor_namespace_stack *nstack,
                                                             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,
                                                             const unsigned char *prefix,
                                                             const 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,
                                                             const 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,
                                                             const unsigned char *prefix,
                                                             const unsigned char *ns_uri_string,
                                                             int depth);
    void                raptor_free_namespace               (raptor_namespace *ns);
    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);
    int                 raptor_namespace_write              (raptor_namespace *ns,
                                                             raptor_iostream *iostr);
    typedef             raptor_namespace_stack;
    int                 raptor_namespace_stack_start_namespace
                                                            (raptor_namespace_stack *nstack,
                                                             raptor_namespace *ns,
                                                             int new_depth);
    unsigned char *     raptor_namespace_format_as_xml      (const raptor_namespace *ns,
                                                             size_t *length_p);
    int                 raptor_xml_namespace_string_parse   (const unsigned char *string,
                                                             unsigned char **prefix,
                                                             unsigned char **uri_string);

## 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,
                                                             const unsigned char *prefix,
                                                             raptor_uri *ns_uri,
                                                             int depth);

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

This declares but does not enable the namespace declaration (or 'start' it) Use `raptor_namespaces_start_namespace()` to make the namespace enabled and in scope for binding prefixes.

Alternatively use `raptor_namespaces_start_namespace_full()` can construct and enable a namespace in one call.

`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          (raptor_world *world,
                                                             int defaults);

Constructor - create a new raptor_namespace_stack.

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

`world` : | raptor_world object
`defaults` : | namespaces to initialise
Returns : | a new namespace stack or NULL on failure

### raptor_namespaces_init ()

    int                 raptor_namespaces_init              (raptor_world *world,
                                                             raptor_namespace_stack *nstack,
                                                             int defaults);

Initialise an existing namespaces stack object

This sets up the stack optionally with some common RDF namespaces.

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

`world` : | raptor_world object
`nstack` : | raptor_namespace_stack to initialise
`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,
                                                             const unsigned char *prefix,
                                                             const 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,
                                                             const 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,
                                                             const unsigned char *prefix,
                                                             const unsigned char *ns_uri_string,
                                                             int depth);

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

This declares but does not enable the namespace declaration (or 'start' it) Use `raptor_namespaces_start_namespace()` to make the namespace enabled and in scope for binding prefixes.

Alternatively use `raptor_namespaces_start_namespace_full()` can construct and enable a namespace in one call.

The `depth` is a way to use the stack of namespaces for providing scoped namespaces where inner scope namespaces override outer scope namespaces. This is primarily for RDF/XML and XML syntaxes that have hierarchical elements. The main use of this is `raptor_namespaces_end_for_depth()` to disable ('end') all namespaces at a given depth. Otherwise set this to 0.

`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_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_namespace_write ()

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

Write a formatted namespace to an iostream

`ns` : | namespace to write
`iostr` : | raptor iosteram
Returns : | non-0 on failure

### raptor_namespace_stack

    raptor_namespace_stack* raptor_namespace_stack;

Raptor XML Namespace Stack class

### raptor_namespace_stack_start_namespace ()

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

Copy an existing namespace to a namespace stack with a new depth and start it.

The `depth` is a way to use the stack of namespaces for providing scoped namespaces where inner scope namespaces override outer scope namespaces. This is primarily for RDF/XML and XML syntaxes that have hierarchical elements. The main use of this is `raptor_namespaces_end_for_depth()` to disable ('end') all namespaces at a given depth. If depths are not being needed it is unlikely this call is ever needed to copy an existing namespace at a new depth.

`nstack` : | namespace stack
`ns` : | namespace
`new_depth` : | new depth
Returns : | non-0 on failure

### raptor_namespace_format_as_xml ()

    unsigned char *     raptor_namespace_format_as_xml      (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_xml_namespace_string_parse()`

`ns` : | namespace object
`length_p` : | pointer to length (or NULL)
Returns : | namespace formatted as newly allocated string or NULL on failure

### raptor_xml_namespace_string_parse ()

    int                 raptor_xml_namespace_string_parse   (const unsigned char *string,
                                                             unsigned char **prefix,
                                                             unsigned char **uri_string);

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

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`. Either but not both may be NULL.

See also `raptor_namespace_format_as_xml()`

`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.