=head1 Name

lua-uri-urn - URN support for Lua URI library

=head1 Description

The class C<uri.urn> is used for URNs, that is, URIs with the C<urn> scheme.
It inherits from the L<uri|lua-uri(3)> class.

Any URN containing an authority part or query part is considered to be invalid,
as is one which does not have a valid NID.  URNs must be of the form
C<urn:nid:nss>, where the NSS part has a syntax specific to the NID.  The
scheme and NID part are both normalized to lowercase.  Some NIDs have
subclasses which enforce further syntax constraints, do NID-specific
normalization, or provide additional methods.

=head1 Methods

All the methods defined in L<lua-uri(3)> are supported.  The C<userinfo>,
C<host>, C<port>, and C<query> methods will always return nil, and will throw
an exception when passed anything other than nil.  The C<path> method will
throw an exception if given a new path which is nil or not valid for the C<urn>
scheme.

The following additional methods are supported:

=over

=item uri:nid(...)

Get or set the NID (Namespace Identifier) of the URN (the part of the path
before the first colon).  If a new value is supplied then the URI's path will
be changed to have the new NID but with the same NSS value.

An exception will be thrown if the new NID is invalid, or if the existing
NSS value is invalid in the context of the new NID.  Note that the value
'urn' is an invalid NID.

This can cause the class of the URI object to change, if a different class
is appropriate for the new NID.

=item uri:nss(...)

Get or set the NSS (Namespace Specific String) part of the URN (the part of the
path after the first colon).  If a new value is supplied then the URI's path
will be changed to use the new NSS, but the NID will be unchanged.

This will throw an exception if the new value is invalid for the current NID.

=back

=head1 Subclasses

The following subclasses are used for URNs with certain NIDs.  URNs with
other NIDs just use the generic C<uri.urn> class.

=over

=item L<uri.urn.isbn|lua-uri-urn-isbn(3)>

=item L<uri.urn.issn|lua-uri-urn-issn(3)>

=item L<uri.urn.oid|lua-uri-urn-oid(3)>

=back

=head1 References

This class is based on L<RFC 2141>.

=for comment
vi:ts=4 sw=4 expandtab
