☺唐鳳☻
and 1 contributors

NAME

Relation - Relations for Perl 6

VERSION

This document describes Relation version 0.0.1.

SYNOPSIS

    use Relation;

This documentation is pending.

DESCRIPTION

This class implements a Relation data type that corresponds to the "relation" of logic and mathematics and philosophy ("a predicate ranging over more than one argument"), which is also the basis of the relational data model proposed by Edgar. F. Codd, upon which anything in the world can be modelled.

A relation is essentially a set of mappings, or a set of logical tuples; a picture of one can look like a table, where each tuple is a row and each relation/tuple attribute is a column, but it is not the same as a table.

The intended interface and use of this class in Perl programs is similar to the intended use of a Set class; a Relation is like a Set that exists over N dimensions rather than one. The Relation operators are somewhat of a superset of the Set operators.

Like the Set data type, the Relation data type is immutable. The value of a Relation object is determined when it is constructed, and the object can not be changed afterwards.

If you want something similar but that is more mutable, you can accomplish that manually using a set of mappings, or a multi-dimensional object Hash, or various combinations of other data types.

While the implementation can be changed greatly (it isn't what's important; the interface/behaviour is), this Relation data type is proposed to be generally useful, and very basic, and worthy of inclusion in the Perl 6 core, at least as worthy as a Set data type is.

INTERFACE

The interface of Relation is entirely object-oriented; you use it by creating objects from its member classes, usually invoking new() on the appropriate class name, and then invoking methods on those objects. All of their class/object attributes are private, so you must use accessor methods. Relation does not declare any subroutines or export such.

The usual way that Relation indicates a failure is to throw an exception; most often this is due to invalid input. If an invoked routine simply returns, you can assume that it has succeeded.

The Relation Class

A Relation object is an unordered set of tuples, each of which is an unordered set of named attributes; all tuples in a Relation are of the same degree, and the attribute names of each tuple are all the same as those of all the other tuples.

For purposes of the Relation class' API, a tuple is represented by a Perl Mapping where each Mapping key is an attribute name and each Mapping value is the corresponding attribute value.

Every Relation attribute has a name that is distinct from the other attributes, though several attributes may store values of the same class; every Relation tuple must be distinct from the other tuples. All Relation attributes may be individually addressed only by their names, and all Relation tuples may be individually addressed only by their values; neither may be addressed by any ordinal value.

Note that it is valid for a Relation to have zero tuples. It is also valid for a Relation to have zero attributes, though such a Relation can have no more than a single tuple. A zero-attribute Relation with zero tuples or one tuple respectively have a special meaning in relational algebra which is analagous to what the identity numbers 0 and 1 mean to normal algebra.

A picture of a Relation can look like a table, where each of its tuples is a row, and each attribute is a column, but a Relation is not a table.

The Relation class is pure and deterministic, such that all of its class and object methods will each return the same result when invoked on the same object with the same arguments; they do not interact with the outside environment at all.

A Relation object has 2 main attributes (implementation details subject to change) plus 1 extra attribute:

$!heading - Relation Heading

Set of Str - This contains zero or more Relation attribute names that define the heading of this Relation. Each attribute name is a character string.

$!body - Relation Body

Set of Mapping(Str) of Any - This contains zero or more member tuples of the Relation; each Set member is a Mapping whose keys and values are attribute names and values. Each Mapping key of a Body tuple must match a Set member of Heading, and the value of every tuple in Body must be mutually distinct.

$!is_mutable - Relation Is Mutable

Bool - This attribute is True if the Relation is allowed to and/or has the ability to mutate, and it is false if not. Looking forward to the near future where "Relation" is a Role rather than a Class, and some implementations are immutable rather than mutable, this property and/or same-named accessor method can be used to see if a Relation-doing object can mutate. Depending on the implementing class, it can default to True or False, but once it has a value of False, it can not be further changed; this class defaults it to False.

This is the main Relation constructor method:

new (Set of Str :$heading?, Set of Mapping(Str) of Any :$body?)

This method creates and returns a new Relation object, whose Heading and Body attributes are set respectively from the optional named parameters $heading and $body. If $heading is undefined or an empty Set, the Relation has zero attributes. If $body is undefined or an empty Set, the Relation has zero tuples. If a Relation has zero attributes, then $body may be an Set with a single member that is an empty Mapping.

A Relation object has these methods:

export_as_hash () returns Hash

This method returns a deep copy of this Relation as a Hash ref of 2 elements, which correspond to the 2 named parameters of new.

is_mutable () returns Bool

This method returns this Relation's "is mutable" boolean attribute.

heading () returns Set of Str

This method returns this Relation's heading.

body () returns Set of Mapping(Str) of Any

This method returns this Relation's body.

size () returns Int

This method returns a count of this Relation's member tuples as an Int.

exists (Mapping(Str) of Any $tuple!) returns Bool

This method returns a Bool indicating whether the argument $tuple exists in / is a member of this Relation.

equal (Relation $other!) returns Bool

This method returns a Bool indicating whether the immutable identity of the argument $other equals the immutable identity of the invocant.

not_equal (Relation $other!) returns Bool

This method returns the complement of equal with the same argument.

rename ( Mapping(Str) of Str $mapping! ) returns Relation

This method is a generic relational operator that returns a new Relation which is the same as the invocant Relation but that some of its attributes are renamed. The argument $mapping says which attributes are being renamed, with its keys being the old names and its values the new names. This method will fail if any $mapping keys do not match invocant Relation attribute names, or any $mapping values duplicate each other, or duplicate attribute names that aren't being renamed. This method supports renaming attributes to each others' names.

project (Set of Str $attrs!) returns Relation

This method is a generic relational operator that returns a new Relation which has a subset of the original's attributes; that subset is the same as those attribute names in the argument $attrs. The new Relation has all of the tuples of the original (or rather, the corresponding projection of each tuple), but that any duplicates following the projection have been eliminated. Trivial cases are where $attrs is either empty or equal to the invocant Relation's header, in which case it returns the identity-one Relation or the invocant Relation respectively. This method will fail if any members of $attrs do not match attribute names of the invocant Relation. This method has an alias named select.

project_all_but (Set of Str $attrs!) returns Relation

This method is the same as project but that the returned Relation has the complement subset of the original's attributes to what project would return given the same $attrs. This method has an alias named select_all_but.

extend (Mapping(Str) of Code $attrs!) returns Relation

This method is a generic relational operator that returns a new Relation which has a superset of the original's attributes; the new Relation has as many additional attributes as there are pairs in the argument $attrs, where the keys of $attrs provide the names of the new attributes, and the values provide values applied to each tuple. The new Relation has all of the tuples of the original (or rather, the corresponding extension of each tuple). Each value of $attrs is an anonymous function that, when given each original tuple/Mapping as its sole read-only argument, returns a value that is optionally a calculation using original attribute values as inputs. As a trivial case, if $attrs is empty, the output relation is identical to the invocant. This method will fail if any keys of $attrs duplicate attribute names of the invocant Relation.

wrap ( Mapping(Str) of Set of Str $mapping! ) returns Relation

TODO. This method has not yet been implemented.

This method is a generic relational operator that returns a new Relation which is the same as the invocant Relation but that some of its attributes have been combined/wrapped into tuple/Mapping-valued attributes. The argument $mapping says which attributes are being combined/wrapped, with its keys being the new tuple-valued attribute names and each of its values the set of old attribute names that are being wrapped. This method will fail if any $mapping keys duplicate attribute names that aren't being wrapped, or any $mapping value set members do not match invocant Relation attribute names, or duplicate any other value set members. This method supports having the new attributes having the same names as old attributes that become wrapped, and it supports having new tuple-valued attributes which wrap zero old attributes (they are effectively just an extension of the relation).

unwrap ( Set of Str $attrs! ) returns Relation

TODO. This method has not yet been implemented.

This method is a generic relational operator that returns a new Relation which is the same as the invocant Relation but that some of its tuple/Mapping-valued attributes have been split/unwrapped into other attributes. The members of the argument $attrs are the names of the invocant's attributes to split/unwrap. This method will fail if any of the named attributes are not tuple-valued attributes, or if any attribute names in one unwrapped tuple-valued attribute are the same as those of another, or are the same as the unaffected invocant's attributes. This method supports having the new attributes having the same names as old attributes that were wrapped, and it supports having old tuple-valued attributes which have zero attributes (they just vanish).

map (Set of Str $heading!, Code $transformer!) returns Relation

This method is a short-hand or alternative for the functionality provided by the 5 generic relational operators [extend, project, rename, wrap, unwrap], applied in that order, and it works like Perl's standard map operator. It returns a new Relation whose attributes (provided in $heading) may or may not resemble those of the original. The anonymous function in the argument $transformer is invoked for each original tuple/Mapping in turn, which it gets as its sole read-only argument, and it must return a new tuple/Mapping whose attributes match those of $heading. The new Relation has all of the tuples of the original (or rather, the corresponding transformation of each tuple), but that any duplicates following the transformation have been eliminated. Trivial cases are where $transformer returns either an empty tuple/Mapping or a tuple that is identical to the original, in which case this method returns the identity-one Relation or the invocant relation, respectively.

restrict (Code $predicate!) returns Relation

This method is a generic relational operator that returns a new Relation which has a subset of the original's tuples, and it works like Perl's standard grep operator; that subset is those for which the the Bool-returning anonymous function in the argument $predicate returns True when given the tuple/Mapping as its sole read-only argument. The new Relation has all of the same attributes as the original. Trivial cases are where $predicate simply returns True or False regardless of its argument, in which case the new Relation has either all of the tuples of the original, or has zero tuples, respectively. This method has aliases named where and grep.

union (Relation $other!) returns Relation

This multi-method is a generic binary relational operator that takes a single Relation in its $other argument, where <$other> has the same heading as the invocant Relation, and returns a new Relation that has the same heading and whose body contains all of the tuples that are in either or both of the invocant Relation and $other; any duplicated tuples appear only once in the result. With any 2 relations, the result is the same regardless of which is the invocant and which is the argument. This method will fail if $other does not have an identical header to the invocant relation. This method has an alias named plus.

union (Relation *@others) returns Relation

This multi-method is the N-ary version of the aforementioned binary union() operator, and the order of its arguments is not significant to the result; the new Relation contains all the tuples of the source Relations, including one copy each of any duplicated tuples.

exclusion (Relation $other!) returns Relation

This multi-method is a generic binary relational operator that is like union except that the returned Relation contains only tuples that are in exactly one of the source Relations. This method has aliases named disjoint_union, d_union, and symmetric_difference.

exclusion (Relation *@others) returns Relation

This multi-method is the N-ary version of the aforementioned.

intersection (Relation $other!) returns Relation

This multi-method is a generic binary relational operator that is like union except that the returned Relation contains only tuples that are in all of the source Relations. This method has an alias named intersect.

intersection (Relation *@others) returns Relation

This multi-method is the N-ary version of the aforementioned.

difference (Relation $other!) returns Relation

This method is a generic relational operator that takes a single Relation in its $other argument, where <$other> has the same heading as the invocant Relation, and returns a new Relation that has the same heading and whose body contains all of the tuples that are in the invocant Relation but that aren't in $other. This method will fail if $other does not have an identical header to the invocant relation. This method has aliases named minus and except.

semidifference (Relation $other!) returns Relation

This method is a generic relational operator that returns the complement of semijoin with the same argument. This method has aliases named semiminus and not_matching.

semijoin (Relation $other!) returns Relation

This method is a generic relational operator that takes a single Relation in its $other argument, where the heading of <$other> is a subset of the heading of the invocant Relation, and returns a new Relation that has the same heading as the invocant and whose body contains all of the tuples that are in the invocant Relation and that match any tuples of $other along their common attributes. This method will fail if the heading of <$other> is not a subset of the heading of the invocant Relation. This method degenerates into an intersection if the two source headings are identical. This method has an alias named matching.

product (Relation $other!) returns Relation

This multi-method is a generic binary relational operator that is identical to join except that this method will fail if any of its source Relations have attributes in common; it will only accept inputs that would result in a cross-product when joined. This method has aliases named cartesian_product, cross_product, cross_join.

product (Relation *@others) returns Relation

This multi-method is the N-ary version of the aforementioned.

join (Relation $other!) returns Relation

This multi-method is a generic binary relational operator that takes another Relation as its $other argument and combines it with the invocant relation into a new Relation, such that all common attribute names and corresponding common tuple values are aligned and merged. The heading of the new relation is the union of the invocant and <$other> headings. The body of the new relation is the result of first pairwise-matching every tuple of the invocant relation with every tuple of the <$other> relation, then where each member of a tuple pair has attribute names in common, eliminating pairs where the values of those attributes differ and unioning the remaining said tuple pairs, then eliminating any result tuples that duplicate others. The sequence in which any two source relations are combined is inconsequential. A trivial case is where @others is an empty list, in which case the returned Relation is identical to the invocant. Another trivial case is where any any source relation has zero tuples, in which case the result does too. Another trivial case is if any source relation is the identity-one relation (zero attributes, one tuple), the result is as if it wasn't there at all. In any situation where a pair of source relations have identical headings, for these their joining degenerates to a intersection. In any situation where a pair of source relations have zero attributes in common, their joining degenerates to a product. In any situation where the heading of one source relation is a full subset of another, the result degenerates to a semijoin. This method has an alias named natural_join.

join (Relation *@others) returns Relation

This multi-method is the N-ary version of the aforementioned binary join() operator, and the order of its arguments is not significant to the result; the new Relation is the result of combining all of the source Relations, such that all common attribute names and corresponding common tuple values are aligned and merged. The heading of the new relation is the union of all the headings of the source relations. The body of the new relation is the result of first pairwise-matching every tuple of each source relation with every tuple of each other source relation, then where each member of a tuple pair has attribute names in common, eliminating pairs where the values of those attributes differ and unioning the remaining said tuple pairs, then eliminating any result tuples that duplicate others.

compose

TODO.

group

TODO.

ungroup

TODO.

summarize

TODO.

substitute

TODO.

divide

TODO.

transitive_closure

TODO. Aliases: tclose.

DIAGNOSTICS

This documentation is pending.

CONFIGURATION AND ENVIRONMENT

This documentation is pending.

DEPENDENCIES

This file requires any version of Perl 6.x.y that is at least 6.0.0.

INCOMPATIBILITIES

None reported.

SEE ALSO

Set.

BUGS AND LIMITATIONS

This documentation is pending.

AUTHOR

Darren R. Duncan (perl@DarrenDuncan.net)

LICENCE AND COPYRIGHT

This file is part of the Relation library.

Relation is Copyright (c) 2006, Darren R. Duncan.

Relation is free software; you can redistribute it and/or modify it under the same terms as Perl 6 itself.

ACKNOWLEDGEMENTS

None yet.