/ 
Inline-Spew-0.02
River stage zero No dependents
/ Inline::Spew

NAME

Inline::Spew - Inline module for Spew

SYNOPSIS

use Inline Spew => <<'SPEW_GRAMMAR';
START: "the" noun verb
noun: "dog" | "cat" | "rat"
verb: "eats" | "sleeps"
SPEW_GRAMMAR

my $sentence = spew();

ABSTRACT

Inline::Spew is an Inline module for the Spew language.  Spew is a
random-grammar walker for generating random text strings controlled
by a grammar.

DESCRIPTION

Inline::Spew is an Inline module for the Spew language. Spew is a random-grammar walker for generating random text strings controlled by a grammar.

Each Inline invocation defines a single subroutine, named spew by default. The subroutine takes a single optional parameter, declaring the "start symbol" within the spew grammar, defaulting to START. The grammar is randomly-walked, and the resulting string is returned.

The grammar is very similar to Parse::RecDescent's grammar specification. Each non-terminal provides one or more alternatives, which consist of sequences of non-terminals and/or terminals. An alternative is chosen at random, by default equally weighted. You can set weights for the various alternatives easily: see below. The chosen non-terminals are expanded recursively until the result is a sequence of the remaining terminals.

For example, the following invocation randomly returns a character from the Flintstones:

use Inline Spew => <<'END';
START: flintstone_character | rubble_character
flintstone_character:
  ("fred" | "barney" | "pebbles") " flintstone" | "dino"
rubble_character:
  ("barney" | "betty" | "bamm bamm") " rubble"
END
my $character = spew();
my $flint = spew("flintstone_character"); # only flintstone

The cost to compile a grammar is roughly a second on a reasonably speedy machine, so the grammar compilation is cached by the Inline mechanism. As long as the source text is not changed (regardless of the file in which it appears), the compilation can be re-used.

Parse::RecDescent is required for the compilation. YAML is required for the saving and restoring of the spew grammar data structure (and Inline itself).

INLINE CONFIG PARAMETERS

SUB

The name of the subroutine defined by the inline invocation. Default is spew in the current package. A name without colons is presumed to be in the current package. A name with colons provides an absolute path.

METHODS

validate

Part of the Inline interface.

build

Part of the Inline interface.

spew_show

Part of the Inline interface.

load

Part of the Inline interface.

register

Part of the Inline interface.

spew_compile

Part of the Inline interface.

SPEW GRAMMAR

See http://www.stonehenge.com/merlyn/LinuxMag/col04.html for a detailed explanation and examples. Here's the relevent extract:

  • Non-terminals of the random sentence grammar are C-symbols (same as Perl identifiers).

  • Terminals are Perl-style quoted strings, permitting single-quoted or double-quoted values, even with alternate delimiters, as in qq/foo\n/.

  • Generally, a rule looks like:

    non_terminal: somerule1 | somerule2 | somerule3

  • A rule may have a subrule (a parenthesized part). For these anonymous subrules, a non-terminal entry is generated for the subrule, but assigned a sequentially increasing integer instead of a real name. In all other respects, the non-terminal acts identical to a user-defined non-terminal. This means that:

    foo: a ( b c | d e ) f | g h

    is the same as

    foo: a 1 f | g h
1: b c | d e

    ... except that you can't really have a non-terminal named 1.

  • Weights are added by prefixing a choice with a positive floating-point number followed by an @, as in:

    foo: 5 @ fred | 2 @ barney | 1.5 @ dino | betty

    which is five times as likely to pick fred as betty (or a total of 5 out of 9.5 times). This is simpler than repeating a grammar choice multiple times, as I've seen in other similar programs, and makes available fine-grained ratio definitions.

EXPORT

None.

SEE ALSO

The Linux Magazine article at http://www.stonehenge.com/merlyn/LinuxMag/col04.html.

SECURITY WARNINGS

Double-quoted strings may contain arbitrary Perl code in subscripts, executed when the grammar is compiled. Quoted strings also include `` or qx//, causing shell commands to be executed when the grammar is compiled. Adding Safe would be a good thing, and is in the TODO list.

AUTHOR

Randal L. Schwartz (Stonehenge Consulting Services, Inc.), <merlyn@stonehenge.com>

COPYRIGHT AND LICENSE

Copyright 2002, 2003 by Randal L. Schwartz

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.