NAME

Data::Rand::Obscure - Generate (fairly) random strings easily.

VERSION

Version 0.021

SYNOPSIS

    use Data::Rand::Obscure qw/create create_b64/;

    # Some random hexadecimal string value.
    $value = create;

    ...

    # Random base64 value:
    $value = create_b64;

    # Random binary value:
    $value = create_bin;

    # Random hexadecimal value:
    $value = create_hex;

    ...

    # A random value containing only hexadecimal characters and 103 characters in length:
    $value = create_hex(length => 103);

    # Object-orientated

    my $generator = Data::Rand::Obscure->new(seeder => sub { ... # My special seeding algorithm # },
        digester => sub { return $my_favorite_digester; });

    $value = $generator->create;

    $value = $generator->create_hex(length => 32);

DESCRIPTION

Data::Rand::Obscure provides a method for generating random hexadecimal, binary, and base64 strings of varying length. To do this, it first generates a pseudo-random "seed" and hashes it using a SHA-1, SHA-256, or MD5 digesting algorithm.

Currently, the seed generator is:

    join("", <an increasing counter>, time, rand, $$, {})

You can use the output to make obscure "one-shot" identifiers for cookie data, "secret" values, etc.

Values are not GUARANTEED to be unique (see Data::UUID for that), but should be sufficient for most purposes.

This package was inspired by (and contains code taken from) the Catalyst::Plugin::Session package by Yuval Kogman

METHODS

Data::Rand::Obscure->new([ seeder => <seeder>, digester => <digester> ])

Returns a Data::Rand::Obscure::Generator with the following methods:

    create
    create_hex
    create_bin
    create_b64

You may optionally supply a seeder subroutine, which is called everytime a new value is to be generated. It should return some seed value that will be digested.

You may also optionally supply a digester subroutine, which is also called everytime a new value is to be generated. It should return a Digest object of some kind (which will be used to take the digest of the seed value).

EXPORTS

$value = create([ length => <length> ])

$value = create_hex([ length => <length> ])

Create a random hexadecimal value and return it. If <length> is specificied, then the string will be <length> characters long.

If <length> is specified and not a multiple of 2, then $value will technically not be a valid hexadecimal value.

$value = create_bin([ length => <length> ])

Create a random binary value and return it. If <length> is specificied, then the value will be <length> bytes long.

$value = create_b64([ length => <length> ])

Create a random base64 value and return it. If <length> is specificied, then the value will be <length> bytes long.

If <length> is specified, then $value is (technically) not guaranteed to be a "legal" b64 value (since padding may be off, etc).

FUNCTIONS

singleton

Returns the Data::Rand::Obscure::Generator used in the above exported functions You probably don't need to use this.

AUTHOR

Robert Krimen, "<rkrimen at cpan.org>"

BUGS

Please report any bugs or feature requests to "bug-data-rand-obscure at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Rand-Obscure>. 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 Data::Rand::Obscure

You can also look for information at:

RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Rand-Obscure>
AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Data-Rand-Obscure>
CPAN Ratings
<http://cpanratings.perl.org/d/Data-Rand-Obscure>
Search CPAN
<http://search.cpan.org/dist/Data-Rand-Obscure>

ACKNOWLEDGEMENTS

This package was inspired by (and contains code taken from) the Catalyst::Plugin::Session package by Yuval Kogman

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.