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

NAME

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

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_row; 
$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 Snartemo 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_row(after, turns...)

Add a new row to the pattern.

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

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

$pattern->insert_row(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_row 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_row. 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.

AUTHOR

Michael Houghton copyright 1999-2002, all rights reserved.

This software may be used under the same terms as Perl itself.

SEE ALSO