Methods

new( $theme )

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

name( [ $theme, ] $count )

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

If $count is omitted, it defaults to 1.

If $count is 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.

There are also some class methods:

themes( )

Return the sorted list of all available themes.

has_theme( $theme )

Return true if the theme $theme exists.

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

This class method adds a new theme to the list. It also creates and exports all the convenience functions ("metatheme()") needed.

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

load_data( $data )

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

The format is very simple. If the "DATA" filehandle contains the following data:

    # names
    bam zowie plonk
    powie kapow # comment
    # multi level
      abc    def
    # empty
    # multi lingual
    fr de
    

"load_data()" will return the following data structure (the string is trimmed, newlines and duplicate whitespace characters are squashed, and end-of-line comments are removed):

    {
        names => "bam zowie plonk powie kapow",
        multi => {
            level   => "abc def",
            lingual => "fr de",
        },
        empty => ""
    }
    

For example, "Acme::MetaSyntactic::List" uses the single parameter "names" to fetch the lists of names for creating its subclasses.

The "init()" method in all "behaviour" classes will also accept an optional $data hashref and if it provided, will use it instead of reading the "__DATA__" section of the module. The actual structure of the hashref depends on the "Acme::MetaSyntactic::" class.

Convenience methods also exists for all the themes. The methods are named after the theme. They are exported only when the theme is actually used or when it appear in the "Acme::MetaSyntactic" import list. The first imported theme is the default, used by the "metaname()" function.

Use cases

"use Acme::MetaSyntactic;"

This exports the "metaname()" function only.

"use Acme::MetaSyntactic 'theme';"

This exports the "metaname()" function and the "metatheme()" function. "metaname()" default to the theme theme.

"use Acme::MetaSyntactic qw(theme1 theme2);"

This exports the "metaname()", "metatheme1()", "metatheme2()" functions. "metaname()" default to the first theme of the list (theme1).

"use Acme::MetaSyntactic ':all';"

This exports the "metaname()" function and the meta* functions for all themes. "metaname()" default to the standard default theme ("foo").

"use Acme::MetaSyntactic::theme;"

This exports the "metatheme()" function only. The "metaname()" function is not exported.

Theme behaviours

The behaviours are all the "Acme::MetaSyntactic::type" classes, with type starting with an uppercase letter.

Here are the available behaviours:

"Acme::MetaSyntactic::List"

The theme is a simple collection of names. An object instance will return names at random from the list, and not repeat any until the list is exhausted.

"Acme::MetaSyntactic::Locale"

The theme is made of several collections of names, each associated with a "language". The language is either passed as a constructor parameter, extracted from the environment or a default is selected.

"Acme::MetaSyntactic::MultiList"

The theme is made of several collections of names, each associated with a "category". Categories can include sub-categories, etc, ad infinitum (or when disk space or memory is exhausted, whichever happens first). The category is either passed as a constructor parameter or the default value is selected.

"Acme::MetaSyntactic::Alias"

The theme is simply an alias of another theme. All items are identical, as the original behaviour. The only difference is the theme name.

Over time, new theme "behaviours" will be added.