package Data::Rand::Obscure;

use warnings;
use strict;

=head1 NAME

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

=head1 VERSION

Version 0.021

=cut

our $VERSION = '0.021';

=head1 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);

=head1 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 L<Data::UUID> for that), but should be sufficient for most purposes.

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

=cut

use Digest;
use Carp::Clan;

my $SINGLETON; # Could be cute and keep this untouchable, but why bother.
sub singleton() {
    return $SINGLETON ||= __PACKAGE__->new;
}

=head1 METHODS

=head2 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 L<Digest> object of some kind (which will be used to take the digest of the seed value).

=cut

sub new {
    use Data::Rand::Obscure::Generator; # Long enough? :(
    my $class = shift;
    croak "You should extend Data::Rand::Obscure::Generator instead" unless $class eq __PACKAGE__;
    return Data::Rand::Obscure::Generator->new(@_);
}

=head1 EXPORTS 

=cut

use vars qw/@ISA @EXPORT_OK/; use Exporter(); @ISA = qw/Exporter/;
@EXPORT_OK = qw/create create_hex create_bin create_b64/;

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

=head2 $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.

=head2 $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.

=head2 $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).

=cut

sub create {
    return singleton->create_hex(@_);
}

for my $name (map { "create_$_" } qw/hex bin b64/) {
    no strict 'refs';
    *$name = sub {
        return singleton->$name(@_);
    };
}

=head1 FUNCTIONS

=head2 singleton

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

=head1 AUTHOR

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

=head1 BUGS

Please report any bugs or feature requests to C<bug-data-rand-obscure at rt.cpan.org>, or through
the web interface at L<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.




=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Data::Rand::Obscure


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Rand-Obscure>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Data-Rand-Obscure>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Data-Rand-Obscure>

=item * Search CPAN

L<http://search.cpan.org/dist/Data-Rand-Obscure>

=back


=head1 ACKNOWLEDGEMENTS

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

=head1 COPYRIGHT & LICENSE

Copyright 2007 Robert Krimen, all rights reserved.

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


=cut

1; # End of Data::Rand::Obscure

__END__