[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

# cmdr::table(n) 0.1 doc "Cmdr, a framework for command line parsing and dispatch"

## Name

cmdr::table - Cmdr - Simple Table creation

## Table Of Contents

## Synopsis

- package require cmdr::util

- ::cmdr::table general var headers script
- ::cmdr::table dict var script
- ::cmdr::table borders ?enable?
- ::cmdr::table show ?cmd...?
- t borders ?enable?
- t headers ?enable?
- t style ?style?
- t add word...
- t + word...
- t += word...
- t << word...
- t <= word...
- t show* ?cmd?
- t show ?cmd?

## Description

Welcome to the Cmdr project, written by Andreas Kupries.

For availability please read Cmdr - How To Get The Sources.

This package provides convenience commands for the easy creation of simple tables.

## API

::cmdr::table general var headers script

  This command creates a new table with the words found in the list of headers as the top row. The script is run in the calling context to configure and populate the table. The table's object command is stored in the named var for access by the script. The result of the command is the table's object command.

  varname var

    The name of the variable in the calling scope the new table's object command will be stored into.

  list headers

    The list of words to user as column headers.

  string script

    The tcl script to be run to configure and populate the table.

::cmdr::table dict var script

  This command creates a new table intended for the display of a Tcl dictionary. It will have two columns titled Key and Value. The script is run in the calling context to configure and populate the table. The table's object command is stored in the named var for access by the script. The result of the command is the table's object command.

  varname var

    The name of the variable in the calling scope the new table's object command will be stored into.

  string script

    The tcl script to be run to configure and populate the table.

::cmdr::table borders ?enable?

  This command configures the global border setting, which indicates the (non)use of borders by the tables of this package. Note that changes to this setting influence only the tables created after the change. Existing tables are not modified.

  The result of the command is the new state of the setting.

  If the command is called without an argument it simply returns the current state of the setting, without making changes.

  The default value for the setting is yes. Individual tables can override the global settings via their borders method, see Table API.

  boolean enable

    The new value of the setting. Optional.

::cmdr::table show ?cmd...?

  This command configures the global show setting, which is the command prefix to use to print a table, if the table is not given a specific command to use. Note that changes to this setting influence only the tables created after the change. Existing tables are not modified.

  The result of the command is the new state of the setting

  If the command is called without any arguments it simply returns the current state of the setting, without making changes.

  The default value for the setting is puts.

  word cmd

    The command prefix to use for printing a table, as varargs. The prefix will be invoked with a single argument, the string representation of the table.

## Table API

This section lists the methods available for configuration and population of the tables created by this package.

t borders ?enable?

  This is the table-level borders setting. On creation a table inherits the global setting (See ::cmdr::table borders). If that is not to suit then this method can be used to override it.

  The result of the method is the new state of the setting. When called without argument no change is made and the result is the current state of the setting.

t headers ?enable?

  This method controls the visibility of the header row. By default general tables have the header row visisble, while for dict tables the header is suppressed. This method allows the user to override these defaults.

  The result of the method is the new state of the setting. When called without argument no change is made and the result is the current state of the setting.

t style ?style?

  This method allows the user to force the use of a completely custom style. Please see the documentation for the Tcllib package report on how to define table styles.

  The package defines four styles of its own, all using the common prefix cmdr/table/ in their names. When no custom style is set the table chooses between these based on its borders and headers settings.

  The result of the method is the new state of the setting. When called without argument then no change is made and the result is the current state of the setting.

  To revert from a custom style to the automatic choice invoke this method with the empty string as the name of the style.

t add word...
t + word...
t += word...
t << word...
t <= word...

  This method adds a new row to the table, containing the given words. If less words than headers are specified the row is padded with empty columns. If too many words are specified the superfluous words are ignored.

  The result of the method is the empty string.

t show* ?cmd?

  This method formats the table into a string and then invokes the command prefix cmd to print that string. The command prefix is run at the global namespace and level. If the cmd is not specified the global show setting is used instead.

  The result of the method is the empty string.

t show ?cmd?

  This is a variant of method show* above which not only prints the table as above, but also destroys it.

## Bugs, Ideas, Feedback

Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Cmdr Tickets.

Please also report any ideas you may have for enhancements of either package(s) and/or documentation.

## Keywords

arguments, command hierarchy, command line completion, command line handling, command tree, editing command line, help for command line, hierarchy of commands, interactive command shell, optional arguments, options, parameters, processing command line, tree of commands

## Copyright

Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries