The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
URI-ni-0.05
River stage one • 2 direct dependents • 2 total dependents
++
/ URI::ni

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

http://tools.ietf.org/html/rfc6920
URI
Digest

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:

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.