/ 
Game-TextPatterns-0.42
River stage zero No dependents
/ Game::TextPatterns

NAME

Game::TextPatterns - generate patterns of text

SYNOPSIS

use Game::TextPatterns;

my $v = Game::TextPatterns->new( pattern => ".#\n#." );

$v->multiply(7,3)->border->border(1, '.')->border;

print $v->string;

Ta-da! You should now have an Angband checker type vault. (Doors not included. Items and monsters may cost extra.)

####################
#..................#
#.################.#
#.#.#.#.#.#.#.#.##.#
#.##.#.#.#.#.#.#.#.#
#.#.#.#.#.#.#.#.##.#
#.##.#.#.#.#.#.#.#.#
#.#.#.#.#.#.#.#.##.#
#.##.#.#.#.#.#.#.#.#                       @
#.################.#
#..................#
####################

Items might be added by applying an appropriate mask:

my $i = Game::TextPatterns->new( pattern => "." );
$i->multiply( 19, 11 );
$i->white_noise( '?', .1 );
$v->mask( '.', $i );
print $v->string;

Which could result in

####################
#.?..............?.#
#.################.#
#.#.#.#.#.#.#.#.##.#
#?##.#.#.#.#.#.#.#.#
#.#.#.#.#.#.#?#.##?#
#.##.#?#.#.#.#.#.#.#
#.#.#?#.#.#.#.#.##.#                  #######
#.##.#.#.#.#.#.#.#.#                  .@...<#
#.################.#                  #######
#.?....?.?.........#
####################

And this pattern adjusted with four_up, twice

my $pat = Game::TextPatterns->new( pattern => <<"EOF" );
..##.
...##
#....
##..#
.#.##
EOF
print $pat->four_up->four_up->string;

creates

.#.##..##..#.##..##.
##..#...####..#...##
#....#....#....#....
...####..#...####..#
..##..#.##..##..#.##
##.#..##..##.#..##..
#..####...#..####...
....#....#....#....#
##...#..####...#..##
.##..##.#..##..##.#.
.#.##..##..#.##..##.
##..#...####..#...##
#....#....#....#....
...####..#...####..#
..##..#.##..##..#.##
##.#..##..##.#..##..
#..####...#..####...
....#....#....#....#
##...#..####...#..##
.##..##.#..##..##.#.

DESCRIPTION

Game::TextPatterns contains methods that generate and alter text patterns. Potential uses include the creation of ASCII art or the construction of vaults for roguelike games.

Terminology

Columns (x, width) and Rows (y, height) are used in various places.

  columns ...
r 
o  ###%#######+######
w  #...the.pattern..#
s  #######+##########
.  #........#.......#
.  #.......@'...<...#
.  ##################

The pattern text can be most any string value.

CONSTRUCTORS

These return new objects. Some require an existing object that probably should not be the same as the object being operated on. If something goes wrong they will throw an exception.

clone

Returns a new object from an existing one with the current state of the pattern attribute.

new pattern => ...

Constructor. A pattern attribute must be specified.

rebuild

MooX::Rebuild feature that returns a new object with the original pattern attribute.

ATTRIBUTES

Only one at the moment.

pattern

Required. Must be a string (which will be split on $/ into an array reference) or an array reference of strings or an object that has a pattern method that ideally returns one of the previous types.

File::Slurper may help read pattern data directly from a file.

pattern can be called as a method to return the current pattern as an array reference. It may be a bad idea to modify the contents of that reference directly.

METHODS

Call these on something returned by a constructor. Those that modify the pattern in-place can be chained with other methods. If something goes wrong these will throw an exception.

append_cols fill pattern

Appends the given pattern to the right of the existing object. If the patterns are of unequal size the fill character (or array reference) will be used to fill in the gaps. If fill is an array reference the first character of that reference will be used to fill gaps should the object be smaller, or otherwise the second character of the array will be used as fill if the object is larger than the given pattern.

append_rows fill pattern

Appends the given pattern below the existing object. Same rules for fill as for append_cols.

as_array

Returns the pattern of the object as a reference to a 2D array. Presumably useful for some other interface that expects a 2D grid. See also from_array.

border width character

Creates a border of the given width (1 by default) and character (# by default) around the pattern.

cols

Returns the width (x, or number of columns) in the pattern. This is based on the length of the first line of the pattern.

crop point1 point2

Crops the pattern to the given column and row pairs, which are counted from zero for the first row or column, or backwards from the end for negative numbers. Will throw an error if the crop values lie outside the size of the pattern.

See also trim.

dimensions

Returns the cols and rows of the current pattern.

draw_in point1 [ point2 ] pattern

Draws the pattern within the given bounds, though will not extend the dimensions of the object if the pattern exceeds that (hence the lower right bound being optional). Should the pattern be smaller than the given bounds nothing will be changed at those subsequent points (this differs from other methods that accept a fill argument).

See also the more complicated overlay.

flip_both

Flips the pattern by columns and by rows.

flip_cols

Flips the columns (vertical mirror) in the pattern.

flip_four

Treats the object as a pattern in quadrant I of the unit circle and returns a new object with that pattern flipped as appropriate into the other three quadrants. See also four_up.

Note that this does not modify the object in-place.

flip_rows

Flips the rows (horizontal mirror).

four_up [ fill ] [ crop? ]

Treats the object as a pattern in quadrant I of the unit circle and returns a new object with that pattern rotated into the other three quadrants by an appropriate number of degrees. See also flip_four.

fill will be used if the input is not a square during various calls to append_cols and append_rows, unless crop is a true value, in which case the object used will be cropped to be a square before the rotations.

Note that this does not modify the object in-place.

from_array array

Replaces the pattern of the object with the contents of the given 2D array. See also as_array.

mask char pattern

mask replaces instances of the char in the object with the corresponding character(s) of the given pattern.

multiply cols [ rows ]

Multiplies the existing data in the columns or rows, unless cols or rows is 1. With no rows set multiplies both the columns and rows by the given value.

overlay point pattern mask

Draws the pattern into the object at the given point though preserving anything from the original object that match the mask character in the pattern.

See also the simpler draw_in.

rows

Returns the height (y, or number of rows) in the pattern.

rotate amount

Rotates the pattern by 0, 90, 180, or 270 degrees specified by the integers 0, 1, 2, and 3 (or modulus of those).

string sep

Returns the pattern as a string with rows joined by the sep value ($/ by default which typically is but may not be a newline).

trim amount

Convenience method for crop( [amount,amount], [-amount,-amount] ).

white_noise char percent

Fills the object with the given percentage of the char randomly.

# 50% fill with 'x'
$v->white_noise( 'x', .5 );

BUGS

Reporting Bugs

Please report any bugs or feature requests to bug-game-textpatterns at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Game-TextPatterns.

Patches might best be applied towards:

https://github.com/thrig/Game-TextPatterns

Known Issues

Probably should have used a 2D array instead of an array of strings, internally.

Probably needs more tests for various edge conditions.

flip_four and four_up probably need better names.

Some of the calling arguments to various methods likely need improvements which will probably break backwards compatibility.

SEE ALSO

https://github.com/thrig/ministry-of-silly-vaults/

Consult the t/ directory under this module's distribution for example code.

Another option might be to use a standard image library and then devise a conversion such that particular colors become particular ASCII symbols (or combinations of symbols, with Unicode or control sequences to set colors or such).

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2018 by Jeremy Mates

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