TIP #193: SIMPLE SYNTAX HELP SYSTEM ===================================== Version: $Revision: 1.3 $ Author: Donal K. Fellows State: Draft Type: Project Tcl-Version: 8.7 Vote: Pending Created: Thursday, 29 April 2004 URL: https://tip.tcl-lang.org193.html Post-History: ------------------------------------------------------------------------- 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 [TIP #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 =========== This document has been placed in the public domain. ------------------------------------------------------------------------- TIP AutoGenerator - written by Donal K. Fellows