.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "RDF::NS 3pm"
.TH RDF::NS 3pm 2024-01-21 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
RDF::NS \- Just use popular RDF namespace prefixes from prefix.cc
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use RDF::NS \*(Aq20230619\*(Aq;              # check at compile time
\&  my $ns = RDF::NS\->new(\*(Aq20230619\*(Aq);   # check at runtime
\&
\&  $ns\->foaf;               # http://xmlns.com/foaf/0.1/
\&  $ns\->foaf_Person;        # http://xmlns.com/foaf/0.1/Person
\&  $ns\->foaf(\*(AqPerson\*(Aq);     # http://xmlns.com/foaf/0.1/Person
\&  $ns\->uri(\*(Aqfoaf:Person\*(Aq); # http://xmlns.com/foaf/0.1/Person
\&
\&  use RDF::NS;             # get rid if typing \*(Aq$\*(Aq by defining a constant
\&  use constant NS => RDF::NS\->new(\*(Aq20111208\*(Aq);
\&  NS\->foaf_Person;         # http://xmlns.com/foaf/0.1/Person
\&
\&  $ns\->SPAQRL(\*(Aqfoaf\*(Aq);     # PREFIX foaf: <http://xmlns.com/foaf/0.1/>
\&  $ns\->TTL(\*(Aqfoaf\*(Aq);        # @prefix foaf: <http://xmlns.com/foaf/0.1/> .
\&  $ns\->XMLNS(\*(Aqfoaf\*(Aq);      # xmlns:foaf="http://xmlns.com/foaf/0.1/"
\&
\&  # load your own mapping from a file
\&  $ns = RDF::NS\->new("mapping.txt");
\&
\&  # select particular mappings
\&  %map = $ns\->SELECT(\*(Aqrdf,dc,foaf\*(Aq);
\&  $uri = $ns\->SELECT(\*(Aqfoo|bar|doz\*(Aq); # returns first existing namespace
\&
\&  # instances of RDF::NS are just blessed hash references
\&  $ns\->{\*(Aqfoaf\*(Aq};           # http://xmlns.com/foaf/0.1/
\&  bless { foaf => \*(Aqhttp://xmlns.com/foaf/0.1/\*(Aq }, \*(AqRDF::NS\*(Aq;
\&  print (scalar keys %$ns) . "prefixes\en";
\&  $ns\->COUNT;              # also returns the number of prefixes
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Hardcoding URI namespaces and prefixes for RDF applications is neither fun nor
maintainable.  In the end we all use more or less the same prefix definitions,
as collected at <http://prefix.cc>. This module includes all these prefixes as
defined at specific snapshots in time. These snapshots correspond to version
numbers of this module. By selecting particular versions, you make sure that
changes at prefix.cc won't affect your programs.
.PP
The command line client rdfns is installed automatically with this module:
.PP
.Vb 3
\&  $ rdfns rdf,foaf.ttl
\&  @prefix foaf: <http://xmlns.com/foaf/0.1/> .
\&  @prefix rdf: <http://www.w3.org/1999/02/22\-rdf\-syntax\-ns#> .
.Ve
.PP
This module does not require RDF::Trine, which is recommended nevertheless.
(at least version 0.140).  If you prefer RDF::NS to return instances of 
RDF::Trine::Node::Resource instead of plain strings, use RDF::NS::Trine.
RDF::NS::URIS is a similar module that returns instances of URI.
.PP
The code repository of this module contains an
update script <https://github.com/nichtich/RDF-NS/blob/master/update.pl>
to download the current prefix-namespace mappings from <http://prefix.cc>.
.SH "GENERAL METHODS"
.IX Header "GENERAL METHODS"
In most cases you only need the following lowercase methods.
.ie n .SS "new ( [ $file_or_date ] [ %options ] )"
.el .SS "new ( [ \f(CW$file_or_date\fP ] [ \f(CW%options\fP ] )"
.IX Subsection "new ( [ $file_or_date ] [ %options ] )"
Create a new namespace mapping from a selected file, date, or hash reference.
The special string \f(CW"any"\fR or the value \f(CW1\fR can be used to get the newest
mapping, but you should better select a specific version, as mappings can
change, violating backwards compatibility.  Supported options include \f(CW\*(C`warn\*(C'\fR
to enable warnings and \f(CW\*(C`at\*(C'\fR to specify a date.
.SS """\fIprefix\fP"""
.IX Subsection """prefix"""
Returns the namespace for \fIprefix\fR if namespace prefix is defined. For
instance \f(CW\*(C`$ns\->foaf\*(C'\fR returns \f(CW\*(C`http://xmlns.com/foaf/0.1/\*(C'\fR.
.SS """\fIprefix_name\fP"""
.IX Subsection """prefix_name"""
Returns the namespace plus local name, if namespace prefix is defined. For
instance \f(CW\*(C`$ns\->foaf_Person\*(C'\fR returns \f(CW\*(C`http://xmlns.com/foaf/0.1/Person\*(C'\fR.
.ie n .SS "uri ( $short | ""<$URI>"" )"
.el .SS "uri ( \f(CW$short\fP | ""<$URI>"" )"
.IX Subsection "uri ( $short | ""<$URI>"" )"
Expand a prefixed URI, such as \f(CW\*(C`foaf:Person\*(C'\fR or \f(CW\*(C`foaf_Person\*(C'\fR. Alternatively 
you can expand prefixed URIs with method calls, such as \f(CW\*(C`$ns\->foaf_Person\*(C'\fR.
If you pass an URI wrapped in \f(CW\*(C`<\*(C'\fR and \f(CW\*(C`>\*(C'\fR, it will not be expanded
but returned as given.
.SH "SERIALIZATION METHODS"
.IX Header "SERIALIZATION METHODS"
.SS "TTL ( prefix[es] )"
.IX Subsection "TTL ( prefix[es] )"
Returns a Turtle/Notation3 \f(CW@prefix\fR definition or a list of such definitions
in list context. Prefixes can be passed as single arguments or separated by
commas, vertical bars, and spaces.
.SS "SPARQL ( prefix[es] )"
.IX Subsection "SPARQL ( prefix[es] )"
Returns a SPARQL PREFIX definition or a list of such definitions in list
context. Prefixes can be passed as single arguments or separated by commas,
vertical bars, and spaces.
.SS "XMLNS ( prefix[es] )"
.IX Subsection "XMLNS ( prefix[es] )"
Returns an XML namespace declaration or a list of such declarations in list
context. Prefixes can be passed as single arguments or separated by commas,
vertical bars, and spaces.
.SS "TXT ( prefix[es] )"
.IX Subsection "TXT ( prefix[es] )"
Returns a list of tabular-separated prefix-namespace-mappings.
.SS "BEACON ( prefix[es] )"
.IX Subsection "BEACON ( prefix[es] )"
Returns a list of BEACON format prefix definitions (not including prefixes).
.SH "LOOKUP METHODS"
.IX Header "LOOKUP METHODS"
.ie n .SS "PREFIX ( $uri )"
.el .SS "PREFIX ( \f(CW$uri\fP )"
.IX Subsection "PREFIX ( $uri )"
Get a prefix of a namespace URI, if it is defined. This method does a reverse
lookup which is less performant than the other direction. If multiple prefixes
are defined, the first in sorted order is returned. If you need to call this
method frequently and with deterministic response, better create a reverse hash
(method REVERSE).
.ie n .SS "PREFIXES ( $uri )"
.el .SS "PREFIXES ( \f(CW$uri\fP )"
.IX Subsection "PREFIXES ( $uri )"
Get all known prefixes of a namespace URI in sorted order.
.SS REVERSE
.IX Subsection "REVERSE"
Calling \f(CW\*(C`$ns\->REVERSE\*(C'\fR is equal to \f(CW\*(C`RDF::SN\->new($ns)\*(C'\fR. See
RDF::SN for details.
.SS "SELECT ( prefix[es] )"
.IX Subsection "SELECT ( prefix[es] )"
In list context, returns a sorted list of prefix-namespace pairs, which
can be used to assign to a hash. In scalar context, returns the namespace
of the first prefix that was found. Prefixes can be passed as single arguments
or separated by commas, vertical bars, and spaces.
.SH "INTERNAL METHODS"
.IX Header "INTERNAL METHODS"
.ie n .SS "SET ( $prefix => $namespaces [, $warn ] )"
.el .SS "SET ( \f(CW$prefix\fP => \f(CW$namespaces\fP [, \f(CW$warn\fP ] )"
.IX Subsection "SET ( $prefix => $namespaces [, $warn ] )"
Set or add a namespace mapping. Errors are ignored unless enabled as warnings
with the third argument. Returns true if the mapping was successfully added.
.ie n .SS "MAP ( $code [, prefix[es] ] )"
.el .SS "MAP ( \f(CW$code\fP [, prefix[es] ] )"
.IX Subsection "MAP ( $code [, prefix[es] ] )"
Internally used to map particular or all prefixes. Prefixes can be selected as
single arguments or separated by commas, vertical bars, and spaces. In scalar
context, \f(CW$_\fR is set to the first existing prefix (if found) and \f(CW$code\fR is
called. In list context, found prefixes are sorted at mapped with \f(CW$code\fR.
.ie n .SS "GET ( $uri )"
.el .SS "GET ( \f(CW$uri\fP )"
.IX Subsection "GET ( $uri )"
This method is used internally to create URIs as return value of the URI
method and all lowercase shortcut methods, such as \f(CW\*(C`foaf_Person\*(C'\fR. By default
it just returns \f(CW$uri\fR unmodified.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
There are several other CPAN modules to deal with IRI namespaces, for instance
RDF::Trine::Namespace, RDF::Trine::NamespaceMap, URI::NamespaceMap,
RDF::Prefixes, RDF::Simple::NS, RDF::RDFa::Parser::Profile::PrefixCC,
Class::RDF::NS, XML::Namespace, XML::CommonNS etc.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2013\- by Jakob Voß.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.