Self Doc Scripts
Volume Number: 6
Issue Number: 6
Column Tag: HyperChat™
Almost Self Documenting Scripts 
By Tom Trinko, Ph.D., Colleen Trino, Fremont, CA
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Almost Self Documenting HyperTalk™ Scripts
[Tom Trinko, Ph.D., is working on advanced computing systems designs at LMSC.
He has worked on machines ranging from PDP-11s to CDC 6600s. Colleen Trinko is
currently a full-time mother and a part-time instructional designer at Apple.]
One problem we all have with code is remembering what it does and how it does it.
If most of the code we generated were one shot throw-away stuff this wouldn’t be a
concern. As the sheer amount of code we have to write increases, however, it becomes
more and more difficult to start from scratch. A number of different ways of dealing
with the problem have been developed for Mac programmers, such as Prototyper™ or
Program Extender™ . The simplest technique is still recycling your own code. After
all, you at least know you’ll eventually be able to figure it out!
HyperTalk™ is well structured to support code reuseabilty because of its pseudo
object oriented construction. Once you’ve written a handler (on mouseup...end
mouseup) to perform a certain function, say make visible all of the hidden objects in a
card, there’s no reason you can’t use that same handler in all of your other stacks--or
projects if you’re using SuperCard™. The difficulty we encounter is trying to
remember which handlers are where and when you find a handler, remembering what
it does.
One possible solution to this problem that we’ve developed is to place a
description of what each handler does at the beginning of the handler. You could place
it at the end of the handler to save a little processing time when the handler is executed
but HyperCard really doesn’t take much time to skip over comments. An example
handler is shown in Listing 1.
Listing 1:
function linechoosen loc
--input x,y location of the mouse click(use the clickloc)
--output line number clicked on in a scrolling field
-- This is a generally useful function which takes the clickloc as
-- input and finds out which line in a scrolling field was clicked
on
put second item of loc into pos
put pos - the top of the target into pos
put pos + the scroll of the target into pos
get the textsize of the target
put it+trunc(it/3) into size
put trunc(pos/size)+1 into linehit
return linehit
end linechoosen
Now this is nice but it still doesn’t help you find where in your 5 Megabyte stack
the handler you want resides. That’s where the scripts in Listing 2 come in handy.
These scripts, when placed in a button, will do the following: (1) search through a
stack and find all of the functions (function name...end name) and all of the handlers
that reside in the stack, and (2) place the location, name and all comments that lie
between the first line of the handler/function and the first executable line in the
handler/function into two variables “functionlist” and “ handlerlist”. These two
variables are structured as shown in Figure 1. You can place the two variables in two
scrolling fields for easy access.
Figure 1
STACK:linechoosen <-- address and name of function line 1 of
functionlist
--input x,y location of the mouse click(use the clickloc)
2
-- This is a generally useful function which takes the clickloc
3
-- input and finds out which line in a scrolling field was clicked
4
BKGND handler lists:findloc
5
If you have a really big stack it might still take awhile to wade through all of the
information returned so we’ve included two scripts, shown in Listings 3a and 3b,
which let you search for keywords in the two fields and automatically scroll the fields
to the line where the match was found. Once you’ve found the item of interest you can
go directly to the script containing the handler if you put the scripts from listing 6
into the scrolling fields and the scripts from listing 5 into the background or card the
scrolling field is in. Just click on the line containing the name of the handler or
function you’re interested in and you will be taken to the edit window for that script.
Listing 4 contains some miscellaneous scripts that are required in the stack
script. Note that the closestack, checkfreespace, and deletefield handlers are not
required but they make life a little nicer. The redolist and popmenu handlers are used
by the scripts which search through the stack and make the function and handler lists.
The linechoosen function is used by the scripts in listing 6 but it can be used in any
scrolling field to see what physical line the user has clicked on.
If you decide to use the scripts in listing 5 and 6, you must make sure that the
address line for a function or handler does not occupy more than one physical line in
the field you display it in. The distinction between physical and logical lines in a field
is fairly simple. As an example suppose that line n of a variable is 80 characters
long. If we put that variable into a field which is 60 characters wide then the logical
line n of the variable will be shown on physical lines n and n+1. If however you use
the fragment
put line n of field x into temp
Temp will contain the full 80 characters. The reason this is important is that
the scripts in listing 4 determine which physical line the mouse has been clicked in
and then get that logical line to parse to find the identity of the object containing the
script. So if logical line 8 occupies two physical lines then when the user clicks on
physical line 24 he will get the wrong answer because logical line 23, not 24, actually
contains what is displayed in line 24. This problem is avoided by clipping the length of
the logical lines to be less than the physical field width. In the listings the field is
assumed to be 75 characters wide. When you set up your card, check that your field is
at least this wide. Note that you will not be able to access scripts whose address lines
have been truncated because they will not have complete address information. On the
other hand you will still be able to access the scripts of handlers displayed after those
with names greater than 75 characters in length.
To give you a feel for what a card using these scripts could look like we’ve
included a picture of the version we use in Figure 2.
Figure 2
We’ve used a popup menu XFCN as an interface in these scripts because it works
well and is an unobtrusive interface. If you don’t have access to any of the several
popup menu XFCN’s presently available you have a couple of simple options. You could
add a few checkbox buttons to your card which correspond to the popup menu options,
or implement a completely HyperTalk-based popup menu using the techniques
described in the MacTutor article “Pop-up Menus in HyperTalk” by Joseph
Bergin(Vol 4 #5 May 1988 pp85). Notice since the popup menu is always accessed
through the function popmenu(in listing 4) you only have to change the call to the
XFCN there in order to eliminate the need for the XFCN in the stack.
Please send any comments, bug reports, insults, etc. to
GEnie T.Trinko
AppleLink Trinko
Referenced by (2):