# perldoc > String::Random

---
type: CommandReference
command: String::Random
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `String::Random->new` — create a new random string generator
- `$gen->randpattern("CCcc!ccn")` — generate string from pattern (e.g., `UDwp$tj5`)
- `$gen->randregex('\d\d\d')` — generate string matching a regex subset
- `random_string("...")` — procedural interface for pattern-based generation
- `random_regex('\d\d\d')` — procedural interface for regex-based generation

## Name

**String::Random** - Perl module to generate random strings based on a pattern

## Synopsis

perl
use String::Random;
my $string_gen = String::Random->new;
print $string_gen->randregex('\d\d\d');        # 3 random digits
print $string_gen->randpattern("...");          # 3 random printable characters

# Alternatively:
use String::Random qw(random_regex random_string);
print random_regex('\d\d\d');
print random_string("...");
## Description

Generates random strings from patterns or limited regular expressions.  
**Security note:** Defaults to Perl's predictable `rand()`. Use OO interface with `rand_gen` option for secure generation.

## Patterns

| Code | Meaning |
|------|---------|
| `c` | Lowercase Latin letter `[a-z]` |
| `C` | Uppercase Latin letter `[A-Z]` |
| `n` | Digit `[0-9]` |
| `!` | Punctuation (e.g., `~!@$%^&*()-_+={}[]|\:;"'.<>?/#,`) |
| `.` | Any of the above |
| `s` | Salt character `[A-Za-z0-9./]` |
| `b` | Any binary data |

Custom patterns can be added via `set_pattern()` or by modifying the object's hash directly.

## Methods

- `new` — create a new `String::Random` object  
  Options: `max` (max chars for `*` and variable-length regex), `rand_gen` (coderef `sub { my $max = shift; int rand $max }`)
- `randpattern LIST` — returns random string from concatenation of pattern strings (list context returns list)
- `randregex LIST` — returns random string matching a regex subset. Supported: `\w`, `\d`, `\W`, `\D`, `.`, `[]`, `{}`, `*`, `?`, `+`
- `get_pattern STRING` — returns pattern arrayref for a given name
- `set_pattern(NAME => ARRAYREF)` — defines or redefines a pattern
- `from_pattern` — deprecated, do not use

## Functions

- `random_string PATTERN, [LIST]` — single scalar pattern or pattern with up to 10 optional list references (used for `0`-`9` in pattern)
- `random_regex REGEX_IN_STRING` — generate string from regex pattern string

## Examples

perl
# Generate a password:
use String::Random;
my $pass = String::Random->new;
print "Your password is ", $pass->randpattern("CCcc!ccn"), "\n";
# Output: UDwp$tj5

# Using regex:
print $pass->randregex('[A-Z]{2}[a-z]{2}.[a-z]{2}\d'), "\n";

# Custom pattern:
$pass->set_pattern(A => [ 'A'..'Z', 'a'..'z' ]);
print $pass->randpattern("AAAA"), "\n";
## See Also

- [perl](https://perldoc.perl.org/perl)
- [MetaCPAN: String-Random](https://metacpan.org/release/String-Random)
- [CPAN Bug Tracker](https://rt.cpan.org/Public/Dist/Display.html?Name=String-Random)
- [Source Code](https://github.com/shlomif/string-random)