/ 
Text-Table-Read-RelationOn-Tiny-0.02
River stage zero No dependents
/ Text::Table::Read::RelationOn::Tiny

NAME

Text::Table::Read::RelationOn::Tiny - Read binary "relation on (over) a set" from a text table.

VERSION

Version 0.02

SYNOPSIS

use Text::Table::Read::RelationOn::Tiny;

my $obj = Text::Table::Read::RelationOn::Tiny
my ($matrix, $elems, $ids) = $obj->get('my-table.txt');

DESCRIPTION

Minimum version of perl required to use this module: v5.10.1.

This module implements a class that reads a binary relation on a set (homogeneous relation, see https://en.wikipedia.org/wiki/Binary_relation#Homogeneous_relation) from a text table.

The table format must look like this:

| x\y     | this | that | foo bar |
|---------+------+------+---------+
| this    | X    |      | X       |
|---------+------+------+---------+
| that    |      |      | X       |
|---------+------+------+---------+
| foo bar |      | X    |         |
|---------+------+------+---------+

  • Tables are read by method get, see below.

  • Only two different table entries are possible, these are X and the empty string (this is default and can be changed, see description of new).

  • The entry in the table's upper left corner is simply ignored and may be empty, but you cannot ommit the upper left | character.

  • The hotizontal rules are optional.

  • There is not something like a format check for the horizontal rules. Any line starting with |- is simply ignored, regardless of the other subsequent characters, if any.

  • The entries (names) in the header line are the set's element names. One of these names may be the empty string.

  • The names of the columns (header line) and the rows (first entry of each row) need to be the same and they must be unique, but they don't have to appear in the same order.

  • Spaces at the beginning of a line are ignored.

METHODS

new

The constructor take the following optional named scalar arguments:

inc

A string. Table entry that flags that the corresponding elements are related. Default is "X".

noinc

A string. Table entry that flags that the corresponding elements are not related. Default is the empty set.

set

If specified, then this must be an array of unique strings specifying the elements of the set for your relation. When the constructor was called with this argument, then method elems will return a reference to a copy of it, and elem_ids will return a hash mapping each element to its array index (otherwise both methods would return undef before the first call to get).

Method get will check if the elements in the input table are the same as those specified in the array. Furthermore, the indices in matrix will always refere to the indices in the set array, and elems and elem_ids will always return the same, regardless of the order of rows and columns in the input table.

If you specify both arguments, then their vaules must be different.

get

The method reads and parses a table. It takes exactly one argument which may be either a file name, an array reference or a string containing newline characters.

Argument is an array reference

The method treats the array entries as the rows of the table.

Argument is a string containing newlines

The method treats the argument as a string representation of the table and parses it.

Argument is a string not containing newlines

The method treats the argument as a file name and tries to read the table from that file.

Note that the method will stop parsing if it recognizes a line containing not any non-white character and will ignore any subsequent lines.

Parsing

When parsing a table, the method first creates an array of set element names from the table's header line (you can obtain this array from the returned list or from method elems).

It then creates a hash whose keys are the element names and each value is the index in the element array just mentioned (you can obtain this hash from the returned list or from method elem_ids).

Finally, it creates a hash of hashes representing the relation (incidence matrix): each key is an integer which is an index in the element array created before. Each corresponding value is again a hash where the keys are the array indices of the elements being in relation; the values do not matter and are always undef. This hash will never contain empty subhashes. (you can obtain this hash from the returned list or from method matrix).

Example

This table:

| x\y   | norel |      | foo | bar |
|-------+-------+------+-----+-----|
| norel |       |      |     |     |
|-------+-------+------+-----+-----|
|       |       | X    | X   |     |
|-------+-------+------+-----+-----|
| foo   |       |      |     | X   |
|-------+-------+------+-----+-----|
| bar   |       |      | X   |     |
|-------+-------+------+-----+-----|

will result in this array:

('norel', '', 'foo', 'bar')

this hash:

('norel' => 0, '' => 1, 'foo' => 2, 'bar' => 3)

and in this hash representing the incidence matrix:

1 => {
         1 => undef,
         2 => undef
       },
3 => {
         2 => undef
       },
2 => {
         3 => undef
       }

Note that element norel (id 0), which is not in any relation, does not appear in this hash (it would be 0 => {} but as said, empty subhashes are not contained).

Return value:

In scalar context, the method returns simply the object.

In list context, the method returns a list containing three references corresponding to the accessor methods matrix, elems and elem_ids: the hash representing the incidence matrix, the element array and the element index (id) hash. Thus, wirting:

my ($matrix, $elems, $elem_ids) = $obj->get($my_input);

is the same as writing

$obj->get($my_input);
my $matrix   = $obj->matrix;
my $elems    = $obj->elems;
my $elem_ids = $obj->elem_ids;

However, the first variant is shorter and needs only one method call.

inc

Returns the current value of inc. See description of new.

noinc

Returns the current value of noinc. See description of new.

matrix

Returns the incidence matrix (reference to a hash of hashes) produced by the most recent call of get, or undef if you did not yet call get for the current object. See description of get.

elems

Returns a reference to the array of elements (names from the table's header line), or undef if you did neither call get for the current object nor specified option set when calling the constructor. See description of get and new.

elem_ids

Returns a reference to the hash element ids (indices in array returned by elems), or undef if you did neither call get for the current object nor specified option set when calling the constructor. See description of get and new.

prespec

Returns 1 (true) if you specified argument set when calling the constructor, otherwise it returns an empty string (false).

AUTHOR

Abdul al Hazred, <451 at gmx.eu>

BUGS

Please report any bugs or feature requests to bug-text-table-read-relationon-tiny at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-Table-Read-RelationOn-Tiny. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Text::Table::Read::RelationOn::Tiny

You can also look for information at:

LICENSE AND COPYRIGHT

This software is Copyright (c) 2021 by Abdul al Hazred.

This is free software, licensed under:

GNU GENERAL PUBLIC LICENSE Version 2