/ 
Text-Table-Read-RelationOn-Tiny-v1.1.1
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 v1.1.1

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.

It may happen that there are elements that are identical with respect to the relation and you do not want to write duplicate rows and columns in your table. To cover such a case, it is allowed that entries of set are array references again.

Example:

[[qw(a a1 a2 a3)], 'b', [qw(c c1)], 'd']

In this case, the elements you write in your table are a, b, c, and d (in case of a subarray always the first element is taken). Method get will add corresponding rows and columns for a1, a2, a3, and c1 to the incidence matrix. Method elems will return this (note the order of the elements):

[a b c d a1 a2 a3 c1]

and method n_elems will return 4. Method elem_ids will return:

{ a => 0, a1 => 0, a2 => 0, a3 => 0,
  b => 1,
  c => 2, c1 => 2,
  d => 3
}

mapping duplicates to the same index, while x_elem_ids will return:

{ a  => 0, a1 => 4, a2 => 5, a3 => 6,
  b  => 1,
  c  => 2, c1 => 7,
  d  => 3
}

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 a hash mapping elements to ids (indices in array returned by elems), or undef if you did neither call get for the current object nor specified argument set when calling the constructor. If you used constructor argument set to specify duplicates, then the duplicates are mapped to the same index (especially each index is smaller than the return value of n_elems). See description of get and new.

x_elem_ids

If constructor argument set was not specified, then this method returns undef. Otherwise, it returns a reference to a hash mapping each element to its index in the array returned by elems. In case of duplicates, such an index may be equal or greater than the return value of n_elems.

prespec

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

n_elems

Returns the number of elements in table: If constructor argument set was specified, then this is the number of elements in the corresponding set. Otherwise, n_elems returns undef before get has been called, after the first call of get, it returns the number of elements of the set taken from the table.

Note: If constructor argument set was specified and some entries in the corresponding array were array references again, then n_elems needs not to be equal to the number of entries in the array returned by elems. Typically, n_elems will be smaller in such a case.

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:

The Artistic License 2.0 (GPL Compatible)