 |
Australia Telescope Compact Array
|
 |
|
 |
|
ATwish - ATNF extension to Tcl/Tk
The following information is for programmers working with the Australia
Telescope National Facility extension to the WISH interpreter to the
Tcl/Tk language.
A summary of the ATwish commands and procedures can be found by
clicking here.
The following set of rules have been instigated for use by ATNF
programmers for the generation of user interfaces for telescope control
and utility software.
The ATwish program
The ATwish Tk extension
- ATwish provides a number of commands in addition to the standard
commands provided by the VMS version of the default Tk interpreter
WISH. These commands allow the programmer to create a
subprocess under the process running a Tk script and interact with
that subprocess interactively.
- ATwish also provides a timer function to allow programmers to
have time triggered events occur in their Tk scripts.
- The commands currently supported under ATwish in extension to the
normal Tcl and
Tk commands are
WARNING: These commands may be subject to change
as development is still occurring on ATwish. If you need any
clarification on ATwish commands, please see Derek.
- The following commands are planned but not yet implemented:
Other command suggestions are welcome.
The ATwish message protocol
- The design of ATwish allows the programmer to write
server programs that return information to the ATwish
script.
- All server programs should return whole lines which have the
" greater than" (>) symbol as the column-one (1) character.
- Any messages received by the parsing procedure in the Tk script should
check for these characters and any that do not conform should be
displayed in a messages box. This will ensure that programs pick up
messages from image crashes etc. and will make it easier for users to
recognize problems as well as programmers to debug them. It may also be
appropriate for such no-flagged messages to be accompanied by an
audible alarm.
- The next element after the > should be the keyword for the operation
to be performed.
- Spawned images should provide a " greater than" (>) symbol as
a prompt.
- The Tk scripts should wait for the > prompt as an indication that
the subprocess image is ready for input.
- Termination of the line with <cr> is not necessary
- Each record should be independent of other records.
- Where long processing is expected, the user interface should convert the
cursor to an appropriate style (e.g. clock/hourglass) to indicate the
non-responsiveness of the system.
ATwish server reserved words
- The command exit is a reserved word for termination of a
subprocess image (where ATNF written). Developers of programs should
ensure that the exit command will be recognised and supported
at any valid input prompt.
- The command init is reserved. Its purpose is cause a general
reset of the server program.
- The command ping is reserved. The ping command should
cause the server to return a line with > character. This can be used
to test whether the server is still responding to commands.
The ATwish code management standard
The ATwish source code standard
- The fact that the programmer is writing code for an interpreter
is no excuse to be sloppy. Careful organisation of .ATK files is
essential for efficiency and maintainability. Badly written code
is not servicable and will more readily be deleted and rewritten
than repaired or enhanced.
- ATwish scripts should be able to be passed through the
DOC automatic software documentation system. With this view, the
following header has been proposed:
#+
# Title [tbs]
# Preface [tbs]
#
# Author [tbs]
# Date [tbs]
#-
{
[tbs]
}
This header should be used as the first lines of every Tk script file
that acts as a main file (rather than just a set of procedures).
In addition, individual procedures within the script should be headed
with code like this:
#+
# Routine [tbs]
# Function [tbs]
#
# Author [tbs]
# Date [tbs]
#
# Call
#-
proc xxx_procname {arg1 arg2 arg3}
{
[tbs]
}
At this stage, I can see no easy way of incorporating the proc
xxx_procname {arg1 arg2 arg3} into the comment block. One
possibility is:
# Call
proc xxx_procname {arg1 arg2 arg3}
{
#-
[tbs]
}
but the included { is a little messy. Please feel free to
comment on this issue.
- Indentation of two (2) spaces is required for each level within the
code.
- Script procedures should be short and modular. If a procedure is long,
split it up into sub-functions.
- Avoid using Tcl/Tk commands as procedure and variable names. This
may lead to problems with standard script libraries that we later write.
- Script names should follow the DEC convention of a program identifier
(of ideally three (3) characters) followed by an underscore and then
the procedural name. Meaningful procedure names are strongly recomended.
- When creating widgets, maintain the hierarchical naming scheme. This
makes it easier to make associations when reviewing code.
- Thou shalt not use tabs!
- To assist in the checking of Tcl/Tk scripts, I have written a small
utility program that takes a source file as an argument and examines
it for potential problems. These include:
- Using reserved words as procedure names
- Tabs and control characters
- Non-standard file names
- Procedure definition style
This utility can be enhanced. If developers would like to see additional
features, then please let me know.
Original: dmckay (30-Nov-1994)
Modified: nmckay (9-Oct-1995)