mkTables 1.0 Manual

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted. The author makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. By use of this software the user agrees to indemnify and hold harmless the author from any claims or liability for loss arising out of such use.
 

 CONTENTS

mkTables 1.0 - Table processing commands for Tcl/Tk 8.

Introduction
Commands
Examples
Installation
Changes
Author

 INTRODUCTION

mkTables is a small collection of new Tcl commands that allow for operating on tables. The term table simply means regular Tcl lists where each of the elements is itself a proper sublist (identical to what the Tcl command "lsort -index" accepts). The term "row" is used for an element in such a two-dimensional list, the term "column" for all n-th elements of all rows.

Obviously, rows can be retrieved and manipulated using the standard list commands like lindex or lappend. The commands in this package, however, provide column oriented manipulations and are in most cases similar to the command names for regular lists: The equivalent to lindex is tindex and so on.

 COMMANDS

tlength Table

Retrieves the "length" of a table, actually the least and greatest width. Obviously the number of rows is retrieved with the standard command llength. tlength instead returns a two-element list where the first value is the number of elements in the "shortest" row and the second value is the number of elements in the "longest" row. If the table is of rectangular shape, i.e. all rows have the same number of elements, then the two returned values are identical.

tlist ?Column ...?

Concatenates a number of columns to a new table. Similar to the standard command llist, each element of the given Columns forms an element in the resulting table.

tconcat ?Table ...?

Concatenates a number of tables to a new table. Similar to the standard command concat, the elements of the given tables form the elements in the resulting table. That is, the columns of the resulting table are the columns of the passed tables.

tindex Table Index

Returns a list with all elements specified by Index from all rows of Table. Thus, the returned list is one column of the given table. Index can be specified like with the standard lindex command, i.e. as an integer or "end-"integer.

tselect Table Index ?Index ...?

Returns a table where the columns are taken from Table according to the specified Indexes. Thus, the returned table contains one or more columns of Table. The Indexes can be specified like with the standard lindex command, i.e. as an integer or "end-"integer. Note that "tindex $myTable 1" is different from "tselect $myTable 1". The latter is rather identical to "trange $myTable 1 1" (see below).

trange Table First Last

Returns a table containing the columns of the given Table in the range as specified by the indexes First and Last. The indexes can be specified like with the standard lindex command, i.e. as an integer or "end-"integer.

tdelete Table First ?Last?

Deletes all columns from Table in the range as specified by the indexes First and Last. If Last is not specified, only the column First is deleted. The indexes can be specified like with the standard lindex command, i.e. as an integer or "end-"integer. Table itself is not modified by this command.

tinsert ?-embed? Table Index Column

Returns a new table formed by inserting Column into Table at the column position specified by Index. If option –embed is specified, Column is treated as a table. That is, the elements of Column are embedded into Table.

treplace ?-embed? Table First Last Column

Returns a new table formed by replacing all columns in the range from First to Last by the column Column. If option –embed is specified, Column is treated as a table. That is, the elements of Column are embedded into Table.

tmirror Table

Returns a table formed by mirroring the given Table vertically. I.e., the last column becomes the first one.

tinvert Table

Returns a table formed by "tilting" the given Table. Columns are turned into rows and rows into columns.

tpadl Table ?Value?, tpadr Table ?Value?

Returns Table in a guaranteed rectangular shape with all rows having the same number of elements. tpadl fills rows with fewer elements than the longest row in Table from the left, hereby right-justifying Table. tpadr does the same thing from the right and therefore left -justifies Table. If Value is not specified, Table is filled up with empty strings, otherwise with Value.

 EXAMPLES

  % tlength {{a b c d} {e f g}}
  3 4
  % tlist {{a b} {c d}} {{1 2} {3 4}}
  {{a b} {1 2}} {{c d} {3 4}}
  % tconcat {{a b} {c d}} {{1 2} {3 4}}
  {a b 1 2} {c d 3 4}
  % tindex {{a b c d} {1 2 3 4}} 2
  c 3
  % tselect {{a b c d} {1 2 3 4}} 1 3
  {b d} {2 4}
  % trange {{a b c d} {1 2 3 4}} 1 3
  {b c d} {2 3 4}
  % tdelete {{a b c d} {1 2 3 4}} 1 3
  a 1
  % tinsert {{a b c d} {1 2 3 4}} 1 {{A B} {C D}}
  {a {A B} b c d} {1 {C D} 2 3 4}
  % tinsert -embed {{a b c d} {1 2 3 4}} 1 {{A B} {C D}}
  {a A B b c d} {1 C D 2 3 4}
  % treplace {{a b c d} {1 2 3 4}} 1 2 {{A B} {C D}}
  {a {A B} d} {1 {C D} 4}
  % treplace -embed {{a b c d} {1 2 3 4}} 1 2 {{A B} {C D}}
  {a A B d} {1 C D 4}
  % tmirror {{1 2} {3 4}}
  {2 1} {4 3}
  % tinvert {{1 2 3} {4 5 6}}
  {1 4} {2 5} {3 6}
  % tpadl {{a b c} d {e f g h i}} X
  {X X a b c} {X X X X d} {e f g h i}
  

 INSTALLATION

 General

mkTables is written in C and comes with a DLL for Windows. On Unix, the package needs to be compiled into a shared library first (see below). mkTables works with Tcl/Tk version 8.0 and higher. It has been stubs-enabled with version 8.2.

To install, place the directory "mkTables1.0" in one of the directories contained in the global Tcl variable "auto_path". For a standard Tcl/Tk installation, this is commonly "c:/program files/tcl/lib" (Windows) and "/usr/local/lib" (Unix).

Compiling

To compile the package, just provide the correct path to "tcl.h" and link against "tcl8x.lib" (Windows) or "libtcl8x.so" (Unix) respectively. If you use stubs, define USE_TCL_STUBS and link against "tclstub8x.lib" (Windows) or "libtclstub8x.a" (Unix) instead.

For Visual C++, the following command should work:

  cl /I c:/progra~1/tcl/include /D USE_TCL_STUBS /c mkTables10.c
  link c:/progra~1/tcl/lib/tclstub83.lib /dll mkTables10.obj

On Linux 2.2, this here works fine:

  gcc -shared -DUSE_TCL_STUBS -ltclstub8.3 -o mkTables10.so mkTables10.c

Test

Test the installation by opening a tclsh or wish and entering "package require mkTables". The string "1.0" should appear. If it fails, "cd" into the directory "mkTables1.0" and load it directly with "load ./mkTables10.dll" (Windows) or "load ./mkTables10.so" (Unix). If no error occured, it succeeded and something must be wrong with the location of "mkTables1.0".

 CHANGES

No changes - Initial version.

 AUTHOR

Michael Kraus
mailto:michael@kraus5.de
http://mkextensions.sourceforge.net