relformat - Text formatting for relations
This manpage describes a set of commands that are used for generating text output of relation and tuple values. These commands are part of the Tcl Relational Algebra Library (ral) package.
The commands described here depend upon access to the struct::matrix, report and csv packages of the Tcl standard library. If your installation does not include tcllib then these commands will not be available to you.
The relformat command returns a string that contains a human readable form of the relation given by relationValue. Relformat is intended to be to relations what the parray command is to arrays, i.e. a easy means of obtaining human readable output. Rather than writing the output directly to a channel, relformat returns it as a string. The returned string does not have a trailing newline character and so is suitable for handing directly to puts. If the optional title argument is present, then it is used as a caption at the bottom of the relation printout. If the options sortAttrs argument is given then the relation is sorted by the list of attributes in sortAttrs before being displayed. If the noheading argument is set to 1, then two rows of attribute name and attribute type that by default are placed as a heading of the output are omitted.
% puts [relformat $::DOG Dog]
+-------+---------+
|DogName|Breed |
|string |string |
+-------+---------+
|Fido |Poodle |
|Sam |Collie |
|Spot |Terrier |
|Rover |Retriever|
|Fred |Spaniel |
|Jumper |Mutt |
+-------+---------+
Dog
---
% puts [relformat $::OWNERSHIP Ownership {DogName Acquired}]
+---------+-------+--------+
|OwnerName|DogName|Acquired|
|string |string |string |
+---------+-------+--------+
|Sue |Fido |2001 |
|George |Fido |2001 |
|Jim |Fred |2003 |
|Mike |Rover |2002 |
|Sue |Sam |2000 |
|George |Sam |2000 |
|Alice |Spot |2001 |
+---------+-------+--------+
Ownership
---------
% puts [relformat $::OWNER Owner "" 1]
+------+--+-------------+
|Sue |24|Cupertino |
|George|35|Sunnyvale |
|Alice |30|San Jose |
|Mike |50|San Jose |
|Jim |42|San Francisco|
+------+--+-------------+
Owner
-----
% puts [relformat [relation group $::OWNERSHIP Owners OwnerName] "" DogName]
+-------+--------+-----------+
|DogName|Acquired|Owners |
|string |string |Relation |
+-------+--------+-----------+
|Fido |2001 |+---------+|
| | ||OwnerName||
| | ||string ||
| | |+---------+|
| | ||Sue ||
| | ||George ||
| | |+---------+|
|Fred |2003 |+---------+|
| | ||OwnerName||
| | ||string ||
| | |+---------+|
| | ||Jim ||
| | |+---------+|
|Rover |2002 |+---------+|
| | ||OwnerName||
| | ||string ||
| | |+---------+|
| | ||Mike ||
| | |+---------+|
|Sam |2000 |+---------+|
| | ||OwnerName||
| | ||string ||
| | |+---------+|
| | ||Sue ||
| | ||George ||
| | |+---------+|
|Spot |2001 |+---------+|
| | ||OwnerName||
| | ||string ||
| | |+---------+|
| | ||Alice ||
| | |+---------+|
+-------+--------+-----------+
The tuple2matrix command returns a matrix containing the values in tupleValue. The matrix is created using the struct::matrix package from the standard Tcl library. By default, the first two rows of the matrix contain the attribute names and types. Setting the noheading argument to 1, removes those rows from the returned matrix. It is the responsibility of the caller to destroy the matrix when it is no longer needed.
The relation2matrix command returns a matrix containing the values in relationValue. The matrix is created using the struct::matrix package from the standard Tcl library. If present, the sortAttr argument is a list of attributes that are used to sort the values before placing in the matrix. By default, the first two rows of the matrix contain the attribute names and types. Setting the noheading argument to 1, removes those rows from the returned matrix. It is the responsibility of the caller to destroy the matrix when it is no longer needed.
The csv command formats the relation value given by relationValue into comma separated value formatted string. If sortAttrs is given, then the tuples of the relation value will appear in the order implied by the list of attributes contained in sortAttrs. If noheading is given as 1, then no heading will be placed in the returned CSV string. By default, heading information is placed in the output. This command uses the csv package from tcllib.
The csvToFile command writes the value of relationValue to the file named fileName in comma separated values format. If sortAttrs is given, then the tuples of the relation value will appear in the order implied by the list of attributes contained in sortAttrs. If noheading is given as 1, then no heading will be placed in the returned CSV string. By default, heading information is placed in the output. This command uses the csv package from tcllib.
The tupleAsTable command is a report style for use with the report package in tcllib. This is the default report style used by the commands in TclRAL for formatting tuples.
The relationAsTable command is a report style for use with the report package in tcllib. This is the default report style used by the commands in TclRAL for formatting relations.
Copyright © 2004 - 2010 by G. Andrew Mangogna