NAME

Data::Fake::Core - General purpose generators

VERSION

version 0.005

SYNOPSIS

    use Data::Fake::Core;

    $generator = fake_hash(
        {
            ssn             => fake_digits("###-##-###"),
            phrase          => fake_template(
                                "%s world", fake_pick(qw/hello goodbye/)
                               ),
            die_rolls       => fake_array( 3, fake_int(1, 6) ),
            temperature     => fake_float(-20.0, 120.0),
        }
    );

DESCRIPTION

This module provides a general-purpose set of fake data functions to generate structured data, numeric data, structured strings, and weighted alternatives.

All functions are exported by default.

FUNCTIONS

fake_hash

    $generator = fake_hash(
        {
            name => fake_name,
            pet => fake_pick(qw/dog cat frog/),
        }
    );

    $generator = fake_hash( @hash_or_hash_generators );

The fake_hash function returns a code reference that, when run, generates a hash reference.

The simplest way to use it is to provide a hash reference with some values replaced with fake_* generator functions. When the generator runs, the hash will be walked recursively and any code reference found will be replaced with its output.

If more than one argument is provided, when the generator runs, they will be merged according to the following rules:

• code references will be replaced with their outputs

• after replacement, if any arguments aren't hash references, an exception will be thrown

• hash references will be shallow-merged

This merging allows for generating sections of hashes differently or generating hashes that have missing keys (e.g. using "fake_binomial"):

    # 25% of the time, generate a hash with a 'spouse' key
    $factory = fake_hash(
        { ... },
        fake_binomial( 0.25, { spouse => fake_name() }, {} ),
    );

fake_array

    $generator = fake_array( 5, fake_digits("###-###-####") );

The fake_array takes a positive integer size and source argument and returns a generator that returns an array reference with each element built from the source.

If the size is a code reference, it will be run and can set a different size for every array generated:

    # arrays from size 1 to size 6
    $generator = fake_array( fake_int(1,6), fake_digits("###-###-###") );

If the source is a code reference, it will be run; if the source is a hash or array reference, it will be recursively evaluated like fake_hash.

fake_pick

    $generator = fake_pick( qw/one two three/ );
    $generator = fake_pick( @generators );

Given literal values or code references, returns a generator that randomly selects one of them with equal probability. If the choice is a code reference, it will be run; if the choice is a hash or array reference, it will be recursively evaluated like fake_hash or fake_array would do.

fake_binomial

    $generator = fake_binomial(
        0.90,
        { name => fake_name() }, # 90% likely
        {},                      # 10% likely
    );

    $generator = fake_binomial( $prob, $lte_outcome, $gt_outcome );

The fake_binomial function takes a probability and two outcomes. The probability (between 0 and 1.0) indicates the likelihood that the return value will the first outcome. The rest of the time, the return value will be the second outcome. If the outcome is a code reference, it will be run; if the outcome is a hash or array reference, it will be recursively evaluated like fake_hash or fake_array would do.

fake_weighted

    $generator = fake_weighted(
        [ 'a_choice',          1 ],
        [ 'ten_times_likely', 10 ],
        [ $another_generator,  1 ],
    );

Given a list of array references, each containing a value and a non-negative weight, returns a generator that randomly selects a value according to the relative weights.

If the value is a code reference, it will be run; if it is a hash or array reference, it will be recursively evaluated like fake_hash or fake_array would do.

fake_int

    $generator = fake_int(1, 6);

Given a minimum and a maximum value as inputs, returns a generator that will produce a random integer in that range.

fake_float

    $generator = fake_float(1.0, 6.0);

Given a minimum and a maximum value as inputs, returns a generator that will produce a random floating point value in that range.

fake_digits

    $generator = fake_digits('###-####'); # "555-1234"
    $generator = fake_digits('\###');     # "#12"

Given a text pattern, returns a generator that replaces all occurrences of the sharp character (#) with a randomly selected digit. To have a literal sharp character, escape it with a backslash (do it in a single-quoted string to avoid having to double your backslash to get a backslash in the string.).

Use this for phone numbers, currencies, or whatever else needs random digits:

    fake_digits('###-##-####');     # US Social Security Number
    fake_digits('(###) ###-####');  # (800) 555-1212

fake_template

    $generator = fake_template("Hello, %s", fake_name());

Given a sprintf-style text pattern and a list of generators, returns a generator that, when run, executes the generators and returns the string populated with the output.

Use this for creating custom generators from other generators.

fake_join

    $generator = fake_join(" ", fake_first_name(), fake_surname() );

Given a character to join on a list of literals or generators, returns a generator that, when run, executes any generators and returns them concatenated together, separated by the separator character.

The separator itself may also be a generator if you want that degree of randomness as well.

    $generator = fake_join( fake_pick( q{}, q{ }, q{,} ), @args );

fake_flatten

    $flatten_generator = fake_flatten( fake_array( 3, fake_first_name() ) );
    @array_of_names = $flatten_generator->();

Given a generator that returns an array ref (such as fake_array) or a hash ref (fake_hash), fake_flatten returns a generator that, when run, executes the generators and returns their result in a dereferenced state.

This is particularly useful when the return value is used directly as input to another function, for example within a fake_join.

    $generator = fake_join( " ", $flatten_generator );

AUTHOR

David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by David Golden.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

cpanm Data::Fake

perl -MCPAN -e shell
install Data::Fake