/ 
String-PerlIdentifier-0.06
River stage zero No dependents
++
 / String::PerlIdentifier
Author image James E Keenan
and 1 contributors

NAME

String::PerlIdentifier - Generate a random name for a Perl variable

VERSION

This document refers to version 0.06, released November 14 2016.

SYNOPSIS

    use String::PerlIdentifier;

    $varname = make_varname();      # defaults to 10 characters

or

    $varname = make_varname(12);    # min: 3    max: 20

or

    $varname = make_varname( {      # set your own attributes
        min     => $minimum,
        max     => $maximum,
        default => $default,
    } );

or

    $varname = make_varname( {      # no underscores in strings;
        underscores => 0,           # alphanumerics only
    } );

DESCRIPTION

This module automatically exports a single subroutine, make_varname(), which returns a string composed of random characters that qualifies as the name for a Perl variable. The characters are limited to upper- and lower-case letters in the English alphabet, the numerals from 0 through 9 and the underscore character. The first character may not be a numeral.

By default, make_varname() returns a string of 10 characters, but if a numerical argument between 3 and 20 is passed to it, a string of that length will be returned. Arguments smaller than 3 are rounded up to 3; arguments greater than 20 are rounded down to 20.

make_varname() can also take as an argument a reference to a hash containing one or more of the following keys:

    min
    max
    default
    underscores

So if you wanted your string to contain a minimum of 15 characters and a maximum of 30, you would call:

    $varname = make_varname( { min => 15, max => 30 } );

If you try to set min greater than max, you will get an error message and croak. But if you set default less than min or greater than max, the default value will be raised to the minimum or lowered to the maximum as is appropriate.

No underscores option

The only meaningful value for key underscores is 0. String::PerlIdentifier, like Perl itself, assumes that underscores are valid parts of identifiers, so underscores are ''on'' by default. So the only time you need to worry about the underscores element in the hash passed by reference to make_varname() is when you want to prevent underscores from being part of the string being generated -- in which case you set:

    underscores => 0

Non-Perl-identifier usages

Although the strings returned by make_varname() qualify as Perl identifiers, they also are a subset of the set of valid directory and file names on operating systems such as Unix and Windows. This is how, for instance, this module's author uses make_varname().

Note: String::PerlIdentifier originally appeared on CPAN as String::MkVarName. When I went to register it on modules@perl.org, brian d foy persuaded me to change the name.

TO DO

Ideally, you should be able to pass the function a list of strings forbidden to be returned by make_varname, e.g., a list of all Perl variables currently in scope. String::PerlIdentifier doesn't do that yet.

SEE ALSO

String::MkPasswd

This CPAN module by Chris Grau was the inspiration for String::PerlIdentifier. String::PerlIdentifier evolved as a simplification of String::MkPasswd for use in the test suite for my other CPAN module File::Save::Home.

String::Random

This CPAN module by Steven Pritchard is a more general solution to the problem of generating strings composed of random characters. To generate a 10-character string that would qualify as a Perl identifier using String::Random, you would proceed as follows:

    use String::Random;
    $rr = String::Random->new();
    $rr->{'E'} = [ 'A'..'Z', 'a'..'z', '_' ];
    $rr->{'F'} = [ 'A'..'Z', 'a'..'z', '_', 0..9 ];

then

    $rr->randpattern("EFFFFFFFFF");

String::Random's greater generality comes at the cost of more typing.

File::Save::Home

CPAN module by the same author as String::PerlIdentifier which uses make_varname() in its test suite as of its version 0.05. File::Save::Home is used internally within recent versions of ExtUtils::ModuleMaker and its test suite.

AUTHOR

        James E Keenan
        CPAN ID: JKEENAN
        jkeenan@cpan.org
        http://search.cpan.org/~jkeenan

SUPPORT

Send email to jkeenan [at] cpan [dot] org. Please include any of the following in the subject line:

    String::PerlIdentifier
    String-PerlIdentifier
    make_varname

in the subject line. Please report any bugs or feature requests to bug-String-PerlIdentifier@rt.cpan.org, or through the web interface at http://rt.cpan.org.

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.