NAME
URI::ni - URI scheme for Named Information Identifiers
SYNOPSIS
use URI;
$u = URI->new('ni:///sha-256');
$u->compute('some data');
my $algo = $u->algorithm;
my $b64 = $u->b64digest;
my $hex = $u->hexdigest;
my $bin = $u->digest;
DESCRIPTION
This module implements the ni:
URI scheme defined in RFC 6920.
compute $DATA [, $ALGO, \%QUERY]
Compute a new ni: URI from some data. Since the data objects we're typically interested in hashing tend to be bulky, this method will optionally take GLOB or SCALAR references, even blessed ones if you can be sure they'll behave, that is, globs treated like files and scalars dereferenced. If not, $DATA
can also be a CODE reference as well, with the Digest context as its first argument, enabling you to specify your own behaviour, like this:
my $obj = MyObj->new;
my $ni = URI->new('ni:///sha-256;');
$ni->compute(sub { shift->add($obj->as_string) });
# Alternatively:
use URI::ni;
my $ni = URI::ni->compute(sub { shift->add($obj->as_string) });
It is also possible to supply your own Digest instance and the URI will be generated from its current state, like this:
my $ctx = Digest->new('SHA-1');
$ctx->add($some_stuff);
# REMEMBER TO MATCH THE ALGORITHM IN THE CONSTRUCTOR!
# I CAN'T (RELIABLY) DO IT FOR YOU!
my $ni = URI::ni->compute($ctx, 'sha-1')
# now you can use $ctx for other stuff.
# The URI doesn't store $ctx so if you modify it, the URI won't
# change.
The algorithms supported are the same as the ones in Digest, which will be coerced to lower-case in the URI. If omitted, the default algorithm is SHA-256, per the draft spec.
Optionally, you can pass in a string or HASH reference which will be appended to the URI. The keys map as they do in URI::QueryParam, and so do the values, which can be either strings or ARRAY references containing strings, to represent multiple values.
from_digest $DIGEST [, $ALGO, \%QUERY, $KIND ]
Returns a ni:
URI from an already-computed digest. As with "compute", you need to supply $ALGO
only if you have either not supplied one in the constructor (e.g. URI->new('ni:')
), or you are using this as a class method.
If $DIGEST
isn't a Digest object, this method will try to detect the representation of the digest that is passed in with $DIGEST
. By convention, it is biased toward the hexadecimal representation, since that is how we typically find message digests in the wild. It is possible, though not likely, that Base64 or binary representations only contain bits that correspond to [0-9A-Fa-f]
, so if you're feeling paranoid, you can supply an additional $KIND parameter with the radix of each character (e.g. 16
, 64
or 256
), or the strings hex
, b64
or bin
. Base64 digests can be supplied in either conventional or base64url forms.
(NB: The difference between standard Base64 and base64url is simply tr!+/!-_!
.)
algorithm
Retrieves the hash algorithm. This method is read-only, since it makes no sense to change the algorithm of an already-computed hash.
b64digest [$RAW]
Returns the digest encoded in Base64. An optional $RAW
argument will return the digest without first translating from base64url (section 5 in RFC 4648).
Like everything else in this module that pertains to the hash itself, this accessor is read-only.
hexdigest
Returns the hexadecimal cryptographic digest we're all familiar with.
digest
Retrieves a binary digest, in keeping with the nomenclature in Digest.
locators
This is a convenience method to instantiate any locators defined in section 2.1.4 as URI objects. If you want to set these values, use URI::QueryParam with the http
or https
keys. Returns all locators in list context, and the first one in scalar context (which of course may be undef).
SEE ALSO
AUTHOR
Dorian Taylor, <dorian at cpan.org>
BUGS
Please report any bugs or feature requests to bug-uri-ni at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI-ni. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc URI::ni
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
LICENSE AND COPYRIGHT
Copyright 2012 Dorian Taylor.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.