NAME

Lingua::Awkwords::Subpattern - implements named subpatterns

SYNOPSIS

  use feature qw(say);
  use Lingua::Awkwords;
  use Lingua::Awkwords::Subpattern;

  # pick-one-of-these patterns (equal weights)
  Lingua::Awkwords::Subpattern->set_patterns(
      C => [qw/p t k s m n/],
      N => [qw/m n/],
      V => [qw/a i u/],
  );

  my $triphthong = Lingua::Awkwords->new( pattern => q{ VVV } );
  say $triphthong->render;

  # patterns can also point to parse trees
  Lingua::Awkwords::Subpattern->update_pattern(
      T => $triphthong
  );

  my $tritriphthong = Lingua::Awkwords->new( pattern => q{ TTT } );
  say $tritriphthong->render;

DESCRIPTION

Subpatterns are named (with the ASCII letters A-Z) elements of an awkwords pattern that expand out to some list of equally weighted choices, or existing parse tree objects. That is, V in a pattern can be a shorthand notation for

  [a/e/i/o/u]

See the source code for what patterns are defined by default, or use set_patterns or update_pattern to change the values.

ATTRIBUTES

pattern

The pattern this object represents. Mandatory. Typically should be an ASCII letter in the A-Z range and typically should be set via the new method.

target

Array reference or object the pattern points to. Prior to 0.03 this did not exist, and the target would be looked up from the patterns each time.

METHODS

get_patterns

Returns the presently set (global) patterns and their corresponding values as a list of keys and values.

is_pattern pattern

Returns a boolean indicating whether pattern is an existing pattern or not.

new

Constructor. A pattern should ideally be supplied. Will throw an error if the pattern does not exist in the global patterns list.

  Lingua::Awkwords::Subpattern->new( pattern => 'V' )

render

Returns a random item from the list of choices, or calls render if the target is a reference of the not-ARRAY kind.

set_patterns list-of-patterns-and-choices

Resets all the choices. These changes are global to a process. For example for the Toki Pona language one might set C for consonants and V for vowels via

  Lingua::Awkwords::Subpattern->set_patterns(
      C => [qw/j k l m n p s t w/],
      V => [qw/a e i o u/],
  );

Choices can either be simple string values or an object ideally with a render method. "COMPLICATIONS" in Lingua::Awkwords has an example of the later form.

update_pattern pattern choices

Updates the choices for the given pattern. This happens globally in a process.

Note that array references are treated differently than lists of values;

  my $nnmm = [qw/n m/];
  Lingua::Awkwords::Subpattern->update_pattern( N => $nnmm );

allows the array reference $nnmm to be changed by the caller (thus affecting future pattern of future objects created in this class), while

  Lingua::Awkwords::Subpattern->update_pattern( N => @$nnmm );

does not allow the caller to then change anything as instead a copy of the list of choices has been made.

walk callback

Calls the callback function with itself as the argument, then if the target is an object calls walk on that object.

BUGS

Reporting Bugs

Please report any bugs or feature requests to bug-lingua-awkwords at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Lingua-Awkwords.

Patches might best be applied towards:

https://github.com/thrig/Lingua-Awkwords

Known Issues

There can only be 26 named subpatterns and these are global to the process. It may be beneficial to (optionally?) make them instance specific somehow, though a workaround for that is to incrementally build up a complicated parse tree from one or more other parse trees.

SEE ALSO

Lingua::Awkwords, Lingua::Awkwords::Parser

AUTHOR

thrig - Jeremy Mates (cpan:JMATES) <jmates at cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2017 by Jeremy Mates

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause