String::PerlIdentifier(3)

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.