view release on metacpan or  search on metacpan

lib/Acme/MetaSyntactic.pm  view on Meta::CPAN

sub themes { wantarray ? ( sort keys %META ) : scalar keys %META }
sub has_theme { $_[1] ? exists $META{$_[1]} : 0 }

1;

__END__

=encoding iso-8859-1

=head1 NAME

Acme::MetaSyntactic - Themed metasyntactic variables names

=head1 SYNOPSIS

    use Acme::MetaSyntactic; # loads the default theme
    print metaname();

    # this sets the default theme and loads Acme::MetaSyntactic::shadok
    my $meta = Acme::MetaSyntactic->new( 'shadok' );

    print $meta->name();          # return a single name
    my @names = $meta->name( 4 ); # return 4 distinct names (if possible)

    # you can temporarily switch theme
    # (though it shifts your metasyntactical paradigm in other directions)
    my $foo = $meta->name( 'foo' );       # return 1 name from theme foo
    my @foo = $meta->name( toto => 2 );   # return 2 names from theme toto

    # but why would you need an instance variable?
    use Acme::MetaSyntactic qw( batman robin );

    # the first loaded theme is the default (here batman)
    print metaname;
    my @names = metaname( 4 );

    print join ',', metabatman(3), metarobin;

    # the convenience functions are only exported
    # - via the Acme::MetaSyntactic import list
    # - when an individual theme is used
    print join $/, metabatman( 5 );

    use Acme::MetaSyntactic::donmartin;
    print join $/, metadonmartin( 7 );

    # but a one-liner is even better
    perl -MAcme::MetaSyntactic=batman -le 'print metaname'

    # the meta(1) command-line tool can be helpful too
    meta batman

=head1 DESCRIPTION

When writing code examples, it's always easy at the beginning:

    my $foo = "bar";
    $foo .= "baz";   # barbaz

But one gets quickly stuck with the same old boring examples.
Does it have to be this way? I say "No".

Here is C<Acme::MetaSyntactic>, designed to fulfill your metasyntactic needs.
Never again will you scratch your head in search of a good variable name!

=head1 METHODS (& FUNCTIONS)

C<Acme::MetaSyntactic> has an object-oriented interface, but can also
export a few functions (see L<EXPORTS>).

=head2 Methods

If you choose to use the OO interface, the following methods are
available:

=over 4

=item new( $theme )

Create a new instance of C<Acme::MetaSyntactic> with the theme C<$theme>.
If C<$theme> is omitted, the default theme is C<foo>.

=item name( [ $theme, ] $count )

Return C<$count> items from theme C<$theme>. If no theme is given,
the theme is the one passed to the constructor.

If C<$count> is omitted, it defaults to C<1>.

If C<$count> is C<0>, the whole list is returned (this may vary depending
on the "behaviour" of the theme) in list context, and the size of the
list in scalar context.

=back

There are also some class methods:

=over 4

=item themes( )

Return the sorted list of all available themes.

=item has_theme( $theme )

Return true if the theme C<$theme> exists.

=item add_theme( theme => [ @items ], ... )

This class method adds a new theme to the list. It also creates and
exports all the convenience functions (C<metaI<theme>()>) needed.

Note that this method can only create themes that implement the
C<Acme::MetaSyntactic::List> behaviour.

=item load_data( $data )

This method is used by the "behaviour" classes (such as
C<Acme::MetaSyntactic::List>) to read the content of the C<DATA>
filehandle and fetch the theme data.