/ 
Weaving-Tablet-0.009.006
River stage zero No dependents
/ Weaving::Tablet

NAME

Weaving::Tablet - Perl extension for manipulating tablet weaving patterns

VERSION

This document describes Weaving::Tablet version 0.9.6

SYNOPSIS

use Weaving::Tablet;

my $old_pattern = Weaving::Tablet::new_from_file("my_pattern");
my $new_pattern = Weaving::Tablet::new_from_scratch(20, 40); # 20 cards, 40 rows

$pattern->load_pattern; # load pattern from $pattern->{file_name}
$pattern->save_pattern; # write pattern to $pattern->{file_name}
$pattern->color_pattern; # compute $pattern->{color}
$pattern->twist_pattern; # compute $pattern->{twist}
$pattern->print_twist; # print accumulated twist for pattern
$pattern->print_twist(10); # print accumulated twist at row 10
$pattern->print_twist(10,20,25); # print accumulated twist at rows 10,20,25

$pattern->insert_pick; 
$pattern->insert_card; 
$pattern->delete_row;
$pattern->delete_card;
$pattern->duplicate_row;
$pattern->duplicate_card;

# member functions

# data retrieval
$pattern->file_name
$pattern->number_of_cards
$pattern->number_of_rows
$pattern->number_of_holes
$pattern->SZ, $pattern->SZ(card)
$pattern->threading, $pattern->threading(card), $pattern->threading(card,hole)
$pattern->start, $pattern->start(card)
$pattern->color_table, $pattern->color_table(color_index)
$pattern->turns, $pattern->card_turns(card), $pattern->row_turns(row), 
	$pattern->turns(card, row)
$pattern->color, $pattern->card_color(card), $pattern->row_color(row),
	$pattern->color(card,row) - gives color indices
$pattern->twist, $pattern->card_twist(card), $pattern->row_twist(row), $pattern->twist(card, row)
$pattern->dirty

# data modification
$pattern->SZ(card, value), $pattern->SZ(listref_of_SZ)
$pattern->threading(card, hole, color_index), $pattern->threading(card, listref_of_color_indices)
$pattern->start(card, hole), $pattern->start(listref_of_holes)
$pattern->color_table(color_index, color_value), $pattern->color_table(listref_of_color_values),
$pattern->color_table(undef, color_value) # add new color at end
$pattern->turns(card, row, turn), $pattern->card_turns(card, listref_of_turns),
$pattern->row_turns(row, listref_of_turns)
$pattern->dirty(value)

DESCRIPTION

The Weaving::Tablet module provides data structures and routines to manipulate tablet weaving patterns. It is limited to patterns using up to eight-holed tablets with all holes threaded and that do not involve flipping tablets, and use single turns only (no turning past more than one hole).

It supports an ASCII representation for persistent storage that is somewhat human readable.

It provides routines to print information about the pattern in an ASCII format.

Object Attributes

Some attributes are stored while others are computed or temporary. In the discussion of attributes which care about the number of holes, the discussion assumes four-holed cards. For different numbers of holes, the description extends naturally.

The persistent attributes:

number_of_rows

The number of rows in the pattern.

number_of_cards

The number of cards (width) in the pattern.

number_of_holes

The number of holes in each card. This defaults to four and may be as high as eight.

SZ

A list of (number_of_cards) elements, each of which is /[SZ]/. This indicates how the tablet is threaded, either S or Z.

threading

A list of (number_of_cards) lists of four elements, each being a "color" taken from the color_table.

Holes ABCD map to number 0123 for list indices. See the ASCII art below for how the holes are considered arranged (subject to rotation) regardless of S vs. Z threading.

<- fell
  _________
 /         \
 |  A   B  |
 |         |
 |  D   C  |
 \_________/
start

A list of (number_of_cards) elements which indicates which hole is in the A position (as shown above) for the starting positions. The values are 0123.

turns

A list of (number_of_cards) lists of (number_of_rows) elements whose values are /, \, or |, indicating the turning direction for each tablet for each row. / denotes a forward turn; \ denotes a backwards turn; | denotes no turn, i.e., an idling card.

color_table

A list of color specifications (whose specific format is undefined here). The threading attribute uses indices into this table as its values.

The non-persistent and computed attributes:

colors

A list parallel to turns whose values are the color of the thread visible at that point.

twist

A list parallel to turns whose values are the amount of twist (in quarter-turns) accumulated in the pattern up to that point.

file_name

The disk file name associated with this pattern, or undef if no file has been specified.

Save file format

Saved patterns are meant to be human readable. To this end, they are text files.

The first line gives the number of cards, rows, and holes. The next (number_of_rows) lines are @turns, with row 0 at the bottom of the list. The next line is @start, where the start positions are given as ABCD.

Next are the S/Z threading of each card, using S and Z as the symbols.

Next come (number_of_rows) lines giving the threadings. Each line is a list of four numbers which indicate the color table entry for each thread.

Next comes the color table. Each line is a list of three numbers giving the RGB value in the range 0 to 65535. The number of lines depends on the number of different colors being used in the total pattern.

For example:

20 cards 20 rows 4 holes
\///\\\/\\//\///\\\/
/\\\///\//\\/\\\///\
\/\\//\///\\\/\\//\/
\\/\/\///\\\\\/\/\//
\\\/\///\///\\\/\///
///\///\/\///\\\/\\\
//\///\//\\///\\\/\\
/\///\/\\\/\\//\\\/\
\///\\\/\\//\///\\\/
/\\\///\//\\/\\\///\
\/\\//\///\\\/\\//\/
\\/\/\///\\\\\/\/\//
\\\/\///\///\\\/\///
///\///\/\///\\\/\\\
//\///\//\\///\\\/\\
/\///\/\\\/\\//\\\/\
\///\\\/\\//\///\\\/
/\\\///\//\\/\\\///\
\/\\//\///\\\/\\//\/
\\/\/\///\\\\\/\/\//
ADABCDADABCDADABCDAD
SSSSSSSSSSSSSSSSSSSS
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
0,1,2,3
65535,0,0
0,65535,0
0,0,65535
65535,65535,0

Routines

new_from_file(file)

Load an existing pattern from the specified file. Returns undef if the file is not specified, is not readable, or cannot be loaded.

new_from_scratch(cards, rows)

Create a pattern with the specified number of cards and rows (both defaulting to 1). This assumes that the pattern uses four colors: black, red, green, blue. It sets the cards to all turn forward, threaded S, and arranged to make diagonals.

load_pattern

Attempts to load the pattern from $self->{file_name}. If the load fails for any reason it returns false, else true. It calls color_pattern and twist_pattern before returning.

save_pattern

Attempts to write the pattern to $self->{file_name}. If the save fails for any reason it returns false, else true.

color_pattern(cardlist)

Computes $self->{color} by walking each card to see what color is on top at each point in the pattern. If cardlist is specified, limit recoloring to specified cards.

twist_pattern(cardlist)

Computes the accumulated twist in quarter-turn units at each point in the pattern. If cardlist is specified, limit calculation to specified cards.

"Prints" the accumulated twist for the last row or each row specified in the rowlist.

In a scalar context, print_twist returns a string suitable for direct printing. The string contains one line for each row specified. Each line is a comma-separated list of values.

In a list context, print_twist returns a list of lists. Each inner list is a list of twist values for the selected row.

For example: $pattern->print_twist(10,11) will return a list of two lists in a list context

insert_pick(rowspec...)

Add picks to the pattern. Row numbers begin with 0.

$pattern->insert_pick() inserts a new row at the end, with all cards turning forward.

$pattern->insert_pick([]number]) inserts a new row after row (number). Specify -1 to insert new row at beginning. All cards will be turning forward.

$pattern->insert_pick([]number, turns]) inserts a new row with the turning specified. Turning is given as a string of /, \, and |. The turns is padded with / if too short; excess cards are ignored.

insert_pick may be called with multiple sets of rows and turnings.

insert_card(after, turns...)

Add a new tablet to the pattern. The variations are analagous to insert_pick. The tablet is presumed to be S threaded starting with hole A.

delete_row(rowlist)

Delete the specified rows from the pattern.

delete_card(cardlist)

Delete the specified card from the pattern.

duplicate_row(from, to)

Creates a new row after the specified row with the same turnings as the source row. Omitting the 'to' argument places the new row at the end.

duplicate_card(card, after)

Creates a new tablet after the specified tablet with the same turnings as the source tablet.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-weaving-tablet@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Michael Houghton <herveus@cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 1999-2012, Michael Houghton <herveus@cpan.org>. All rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.