 NAME
 VERSION
 SYNOPSIS
 DESCRIPTION
 INTERFACE
 DIAGNOSTICS
 CONFIGURATION AND ENVIRONMENT
 DEPENDENCIES
 INCOMPATIBILITIES
 SEE ALSO
 BUGS AND LIMITATIONS
 AUTHOR
 LICENCE AND COPYRIGHT
 ACKNOWLEDGEMENTS
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 multidimensional 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 objectoriented; 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 zeroattribute 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 samenamed accessor method can be used to see if a Relationdoing 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 identityone 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 namedselect
. 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 whatproject
would return given the same$attrs
. This method has an alias namedselect_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 readonly 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/Mappingvalued attributes. The argument
$mapping
says which attributes are being combined/wrapped, with its keys being the new tuplevalued 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 tuplevalued 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/Mappingvalued 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 tuplevalued attributes, or if any attribute names in one unwrapped tuplevalued 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 tuplevalued attributes which have zero attributes (they just vanish). map (Set of Str $heading!, Code $transformer!) returns Relation

This method is a shorthand 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 standardmap
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 readonly 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 identityone 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 Boolreturning anonymous function in the argument$predicate
returns True when given the tuple/Mapping as its sole readonly 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 namedwhere
andgrep
. union (Relation $other!) returns Relation

This multimethod 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 namedplus
. union (Relation *@others) returns Relation

This multimethod is the Nary 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 multimethod 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 nameddisjoint_union
,d_union
, andsymmetric_difference
. exclusion (Relation *@others) returns Relation

This multimethod is the Nary version of the aforementioned.
intersection (Relation $other!) returns Relation

This multimethod 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 namedintersect
. intersection (Relation *@others) returns Relation

This multimethod is the Nary 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 namedminus
andexcept
. 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 namedsemiminus
andnot_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 anintersection
if the two source headings are identical. This method has an alias namedmatching
. product (Relation $other!) returns Relation

This multimethod 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 crossproduct when joined. This method has aliases namedcartesian_product
,cross_product
,cross_join
. product (Relation *@others) returns Relation

This multimethod is the Nary version of the aforementioned.
join (Relation $other!) returns Relation

This multimethod 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 pairwisematching 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 identityone 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 aintersection
. In any situation where a pair of source relations have zero attributes in common, their joining degenerates to aproduct
. In any situation where the heading of one source relation is a full subset of another, the result degenerates to asemijoin
. This method has an alias namednatural_join
. join (Relation *@others) returns Relation

This multimethod is the Nary 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 pairwisematching 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.