State:		Draft
Type:		Project
Tcl-Version:	8.7
Vote:		Pending
Post-History:	
Author:		Donal K. Fellows <donal.k.fellows@man.ac.uk>
Created:	29-Apr-2004
Keywords:	Tcl

Abstract

This TIP proposes a simple scheme to allow commands to provide basic syntax help for themselves. This information would allow for more advanced processing by programs doing interactive input of Tcl commands (by providing a mechanism for them to discover what possible completions of the current command fragment are available) and could be processed automatically by the interp alias and namespace ensemble mechanisms so that help could be automatically extended to commands defined through those mechanisms.

Rationale

Currently, Tcl commands are only partially consistent in how they provide information about their own syntax; the only way of getting any syntax help is by providing invalid input to the command, but not all commands have invalid input sequences (e.g. list) and nor is there any way of knowing what those invalid sequences are (where they do exist) unless you know the command beforehand.

Such help would be useful in a number of situations, such as command expansion in something like tkcon. It would also provide a mechanism for supplying the sort of detailed information which the likes of [incr Tcl]'s ensembles can generate, but which the Tcl ensembles of [112] do not do (for the reason that this would produce output significantly different in kind from existing core commands.)

Note that I do not want to provide extended help such as might be obtained from manual pages; this help system is designed to be mechanically queryable first.

Proposed Change

There are two main components

Data Model

Every command would supply help for itself by providing a callback to generate the information on demand; there will be a compatability callback installed by default that states that the command may take any number of unknown arguments.

The result of the callback will be a list of command call descriptions. Each description will be itself a list of terms that describe a particular way of calling the command, with one term per argument. Each term may in turn be one of:

Required literal - this might be something like a subcommand name.
Optional literal - a good example of this are the then and else words in a call to if.
Required varying (with name for display to the user) - a normal argument which may be whatever the caller wants it to be, subject to the higher level constraints implicit in the name.
Optional varying (with name for display to the user) - a normal optional argument.
All remaining arguments - this would be used in the default help outlined above, but would also be useful for modelling the args parameter to a procedure.

[ToDo: say how these are expressed in C code]

[ToDo: talk about how aliases and ensembles can do help construction]

[ToDo: talk about how such information can be partially derived in procedures]

Information Access

There will be a new subcommand of info to provide access to this information at the Tcl level: help. The first argument to info help will be the name of a command; if no further arguments are supplied, the result will be a multi-line string with one invokation per line; the invokations will be just the string parts with the literal/varying information omitted and the optional/required information converted into surrounding question marks.

Otherwise, the second argument to info help will be one of:

get: Two optional arguments; an index into the list of help "lines" (first) and an index within the line (second). If one index is supplied, returns the list of values (without lit/var or opt/req info) for the indexed line. If two indexes are supplied, returns the string form for the indexed word within the indexed line. If no indexes are supplied, or returns a list of every such value list when no index is supplied.

literal: Two required arguments; an index into the list of help "lines" and an index into the list of values for that line. Returns a boolean that is true when the indexed word within the indexed line is a literal.

required: Two required arguments; an index into the list of help "lines" and an index into the list of values for that line. Returns a boolean that is true when the indexed word within the indexed line is required.

[ToDo: could info help be used as a mechanism for procedures to set their own help up?]

Copyright