/ 
Text-Table-Read-RelationOn-Tiny-0.01
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.01

SYNOPSIS

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

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

DESCRIPTION

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

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

noinc

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

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 not yet call get for the current object. See description of get.

elem_ids

Returns a reference to the hash element ids (indices in array returned by elems), or undef if you did not yet call get for the current object. See description of get.

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