[_CDMiwok_01_]<cedarcommon2.0>Documentation>TiogaDWIMDoc.tioga!1

TiogaDWIMDoc.tioga

Mike Spreitzer, March 1, 1987 6:45:25 pm PST

Rick Beach, March 12, 1987 7:07:32 pm PST

Last tweaked by Mike Spreitzer on December 14, 1988 10:53:18 am PST

TIOGADWIM

CEDAR 7.0 — FOR INTERNAL XEROX USE ONLY

TiogaDWIM

Mike Spreitzer

Abstract: TiogaDWIM provides smarts for the "Get", "GetImpl", and "Def" buttons in Tioga viewers. These smarts understand the common languages and practices used in programming in CSL. Thus, the "Get" smarts understand DF-file contents, and also the idea of following the attachment to Foo.BCD to find Foo.Mesa. The "Def" button tries to determine the language of the file being searched, and search according to the rules of that language. The "GetImpl" button first does a "Def" search, and then looks for the implementation of the result. Cedar sources are recognized by their filename extension. TiogaDWIM understands these features of the Cedar language: type renaming, DIRECTORY and IMPORTS statements, and the optional OPEN on the outermost block, and the fact that declarations are of the form idlist: Type. It's been known to work on object-oriented invocations too. TiogaDWIM also understands JaM files and Style files, and has a rudimentary understanding of LISP files.

Created by: Mike Spreitzer

Maintained by: Mike Spreitzer <Spreitzer.pa>

Keywords: DWIM (do what I mean), file, DF file, Tioga extensions, attachment, file lookup, definition search, Cedar language, Mesa language, Lisp language, JaM language, style files

XEROX Xerox Corporation
Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304

For Internal Xerox Use Only

0. Introduction

The TiogaDWIM package has two main parts: FileDWIM and DefDWIM. They both export both a programmer's interface and a user interface. The programmer's interfaces are named, oddly enough, FileDWIM and DefDWIM. The user interfaces are the "Get", "GetImpl", and "Def" buttons. FileDWIM enabled/disabled by user profile options. DefDWIM is invoked if the "Def" button is clicked with the middle mouse button un-shifted, or if the "GetImpl" button is clicked with a shift key held down.

1. Installation

To install TiogaDWIM, say

% Install TiogaDWIM

To install only FileDWIM or only DefDWIM, say one of the following:

% Install FileDWIM

% Install DefDWIM

2. FileDWIM

FileDWIM.ResolveHint is it. Given a file name hint, possible short or relative, and a context file name for the hint to be relative to, it returns the full name of an existing file. Furthermore, if the argument searchHack is true, ResolveHint considers the possibility that the hint is actually of the form Interface.Element, and tries to return a full file name for the interface and the name of the interface element to search for. This is part of the standard misbehavior of the "Get" button, and is an abomination --- it is properly part of the "Def" function.

FileDWIM is invoked from the user interface when you select a file name, and click the "Get" entry in the menu of a Tioga viewer, but Tioga can't easily find the selected file. The viewer whose "Get" button was clicked provides the contextFileName.

Beyond the obvious straightforward lookup, FileDWIM adds some heuristics about how to find a file.

One heuristic involves DF-files. If the contextFileName is a DF-file, FileDWIM will process the DF-file, looking for the filename you selected. This feature is enabled/disabled with the UserProfile entry FileDWIM.ProcessDF: Boolean (defaults to TRUE).

Another heuristic is the standard one of searching the version maps for short names.

Another heuristic says that files whose names differ only in the extensions are often found in the same directory. The last heuristic assists this; it says that when a local name has an attachment to a remote name, the remote name's directory is a good place to look. These last two are enabled/disabled by the UserProfile entries FileDWIM.AssociateExtensions and FileDWIM.FollowAttachments (both take Booleans and default to TRUE).

3. DefDWIM

DefDWIM is given a ROPE to search for the definition of, and a place in a Tioga document to start searching. DefDWIM tries first to determine what language that Tioga document is written in, and then to search according to the rules of that language. If it cannot recognize the language of the document, the search is done according to some simple default rules (currently these are what the standard "Def" button does). DefDWIM's knowledge of languages is extensible. It starts out with a reasonably good knowledge of Cedar, and a primitive knowledge of LISP.

DefDWIM is invoked when you hit the "Def" menu entry in a Tioga viewer with the middle mouse button (without a shift key held down), if the user profile entry DefDWIM.Enabled is TRUE (which it defaults to). If the control key is being held down, the search is ``deep'', otherwise ``shallow''. The exact meaning, if any, of deep vs. shallow is language dependent.

DefDWIM.FindDef is the programmer's interface. It may raise Failure.

DefDWIM also provides augmented functionality for the "GetImpl" menu entry in Tioga viewers. When clicked with a shift key held down, and the filename of the containing viewer is directory>base.ext!ver, it's sort of like doing an unshifted GetImpl of base.selection. The difference is that first a deep DefDWIM.FindDef is done on the selection. For example, if you have a renaming OPEN VF:ViewerForkers, and somewhere in your program you select VF.ForkCall and shift-middle click GetImpl, you get to the ForkCall procedure in ViewerForkersImpl.

3.1. DefDWIM for Cedar

DefDWIM decides the document is in the Cedar language if the filename extension is "Mesa" or "Cedar".

DefDWIM for Cedar tries to follow real Cedar semantics and correctly find the declaration of a selected expression. It is not ambitious enough to maintain an on-line real live semantic analysis, however. What it actually does is to try to fake it with text searches, and an on-line analysis of the "header" of the program. The header includes all the stuff up to the optional OPEN and the begin of the outermost block. The text searches are of higher quality than the standard "Def" provides.

DefDWIM for Cedar works on expressions of the form x.y.z, for any number of dots. It can either look for the declaration of field z in the type of x.y, or look for the definition of the type of x.y.z. The latter kind are called "deep" searches, and the former shallow. DefDWIM for Cedar works recursively, in the obvious way.

DefDWIM for Cedar just happens to be pretty good at object-oriented invocations too. If you select aStream.GetToken in aStream.GetToken[] in some program using an IO.STREAM named aStream and middle-click Def, you get to the definition of GetToken in IO.Mesa.

The high-quality text searches take a lot of time. So low-quality searches, and some Cedar semantic analysis, are tried first. However, if they fail, the high-quality-low-speed searches will be tried. If anyone has a faster regular expression package than CedarChest's RegularExpression ...

When DefDWIM has just about run out of places to look for the definition of a name, it is willing to suppose that name is something that belongs in the DIRECTORY statement but hasn't yet been put there --- i.e., it will look for a file with that short name. This will be done if the user profile entry DefDWIM.GuessDIRECTORY is TRUE (which it defaults to) and the leftmost argument to DefDWIM.FindDef is TRUE.

3.2. DefDWIM for JaM and Style files

DefDWIM recognizes JaM and Style files by their filename extension. It knows about: double-quoted strings, parenthesized strings, square-bracketed and curly-braced arrays, .cvx, .def, /def, /xdef, .run, AttachStyle, StyleRule, ScreenRule, and PrintRule. A "deep" search for "x" means to look for the definition of "look.x".

3.3. DefDWIM for LISP

DefDWIM decides the document is in LISP if the first non-blank character, excluding comment nodes, is a left parenthesis, and the last non-blank character, excluding comment nodes, is a right parenthesis.

DefDWIM for LISP is rather primitive. When asked to find the definition of "foo", DefDWIM for LISP does a case-sensitive non-nodebreak-spanning word search for "(defun foo".

4. Other

TiogaDWIM's organization includes a number of smaller packages that might prove interesting in themselves:

TiogaRopes presents Tioga documents as ROPEs, without having to catenate all the node ropes.

DocCache provides a cached mapping from file names to Tioga documents.

TDLexing provides a simple but useful Cedar lexer.

MesaAnalyses maintains, on demand, analyses of Tioga documents that are in fact Cedar sources.