=begin pod

=head1 NAME

Random::Names - Create random names to be used as identifiers

=head1 SYNOPSIS

=begin code :lang<raku>
use Random::Names;

# procedural interface
say docker-name;      # e.g. epic-engelbart
say class-name;       # e.g. Mendeleev
say identifier-name;  # e.g. dhawan

my @dn = docker-name(10);      # get array with 10 unique docker-names
my @cn = class-name(10);       # get array with 10 unique class-names
my @in = identifier-name(10);  # get array with 10 unique identifiers

# object interface
my $rn = Random::Names.new;  # set up unique pool of names
say $rn.docker-name;
say $rn.class-name;
say $rn.identifier-name;
=end code

=head1 DESCRIPTION

Sometimes you need some placeholder names for things that do not have
a name yet.  This module provides a way to create names for things that
are both fun and interesting.  The names from which it selects, are the
surnames of individuals that are famous in the history of scientific
exploration and engineering.

It offers 3 types of random names:

=item docker-name

Similar to how Docker names unnamed containers.

=item class-name

Title-cased names used for classes in Raku.

=item identifier-name

Just a random name that can be used as an identifier.

This module also installs a C<rn> script that allows you to generate one or
more names, accepting a named argument C<--docker> for docker names,
C<--class> for class names, or just identifiers if not specified.  Also
optionally takes a named argument C<--verbose> to also show the C<WHY> and
C<LINK> information.

=head1 ADDITIONAL INFORMATION

Each string that is being returned by this module, also has a C<.WHY>
method attached to it that will give additional information about the
person to which the name is attached.  E.g.;

=begin code :lang<raku>
my $name = identifier-name;
say $name;  # einstein
my $why = $name.WHY;
say $why;  # Albert Einstein invented the general theory of relativity.
=end code

And that string has a C<.LINK> method that produces a link to a page that
will show you more information about that person:

=begin code :lang<raku>
say $why.LINK;  # https://en.wikipedia.org/wiki/Albert_Einstein
=end code

=head1 FUNCTIONS

=head2 docker-name

Return a random string similar to how Docker names unnamed containers,
such as: C<interesting-mendeleev>, C<epic-engelbart>, C<lucid-dhawan>,
C<recursing-cori>, C<ecstatic-liskov> and C<busy-ardinghelli>.  These
are made from a random selection of an adjective and a surname.

Optionally takes the number of docker-names to be returned.

=begin code :lang<raku>
say docker-name;          # e.g. epic-engelbart
.say for docker-name(5);  # 5 different docker names
=end code

=head2 class-name

Return a random string that can be used as a name of a class, such
as I<Mendeleev>.

Optionally takes the number of class names to be returned.

=begin code :lang<raku>
say class-name;          # e.g. Engelbart
.say for class-name(5);  # 5 different class names
=end code

=head2 identifier-name

Return a random string that can be used as an identifier, such
as I<dhawan>.

Optionally takes the number of identifiers to be returned.

=begin code :lang<raku>
say identifier-name;          # e.g. cori
.say for identifier-name(5);  # 5 different identifiers
=end code

=head1 METHODS

The method interface has two different modes of operation.  When called
as a class method, the semantics are exactly the same as the functional
interface.

When called on a C<Random::Names> instance, it will only produce each
adjective and each surname B<only once>.  This means that any mix of
calls to C<docker-name>, C<class-name> or C<identifier-name>, the
returned strings will always be unique.

=head2 new

=begin code :lang<raku>
my $rn = Random::Names.new:
  adjectives => <pretty awful>,     # default: standard set of adjectives
  surnames   => <mattijsen kasik>,  # default: standard set of surnames
;
=end code

=head2 docker-name

Return a random string similar to how Docker names unnamed containers.
These are made from a random selection of an adjective and a surname.

Optionally takes the number of docker-names to be returned.

=begin code :lang<raku>
my $rn = Random::Names.new;
say $rn.docker-name;          # e.g. epic-engelbart
.say for $rn.docker-name(5);  # 5 different docker names
=end code

=head2 class-name

Return a random string that can be used as a name of a class, such
as I<Mendeleev>.

Optionally takes the number of class names to be returned.

=begin code :lang<raku>
my $rn = Random::Names.new;
say $rn.class-name;          # e.g. Engelbart
.say for $rn.class-name(5);  # 5 different class names
=end code

=head2 identifier-name

Return a random string that can be used as an identifier, such
as I<dhawan>.

Optionally takes the number of identifiers to be returned.

=begin code :lang<raku>
my $rn = Random::Names.new;
say $rn.identifier-name;          # e.g. cori
.say for $rn.identifier-name(5);  # 5 different identifiers
=end code

=head2 adjectives

=begin code :lang<raku>
.say for Random::Names.new.adjectives;
=end code

Return an array of possible adjectives, alphabetically sorted.

=head2 surnames

=begin code :lang<raku>
.say for Random::Names.new.surnames;
=end code

Return an array of possible surnames, alphabetically sorted.

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>, inspired by the Perl module
C<Data::Docker::Names> by Mikko Johannes Koivunalho <mikko.koivunalho@iki.fi>.

Source can be located at: https://codeberg.org/lizmat/Random-Names .
Comments and Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a
L<small sponsorship|https://github.com/sponsors/lizmat/>  would mean a great
deal to me!

=head1 COPYRIGHT AND LICENSE

Copyright 2020, 2021, 2022, 2025, 2026 Elizabeth Mattijsen

This library is free software; you can redistribute it and/or modify it under
the Artistic License 2.0.

=end pod

# vim: expandtab shiftwidth=4
