Cedar Creature Comforts
Release as [Indigo]<Cedar>Documentation>NewStuff.tioga
By
 Warren Teitelman
Last edited
 By Warren Teitelman on March 31, 1983 4:58 pm
Abstract This document describes a collection of facilities that generally fall under the category of creature comforts: they are not essential, but they make life more pleasant. These facilities are enabled by running NewStuffImpl.bcd, e.g. by including "run newstuffimpl" in the CommandsFrom entry in your user profile. (NewStuffImpl.bcd automatically comes over as part of the release; you may obtain the latest version via [Indigo]<PreCedar>Top>NewStuff.df.) In addition, some of the facilities can be parameterized, or disabled, via various user profile entries described below.
Extensions to Abbreviation Expansion
CTRL-E can now be used following any expression whose value is of type procedure, record, error, signal, etc., i.e. any type whose syntax involves square brackets and named fields, to generate an appropriate "form" for that expression. For example:
User types: Rope.Find{CTRL-E}
produces: Rope.Find[s1: ROPE, s2: ROPE, pos1: INT ← 0, case: BOOL ← TRUE]
User types: IO.Error{CTRL-E}
produces: IO.Error[ec: IO.ErrorCode, stream: STREAM]
The user can move back and forth among the fields using {NEXT} (Spare2) and {SHIFT-NEXT} in the standard fashion. When finished with the form, he can type CTRL-NEXT which will have the effect of deleting any fields not filled in, plus advancing the caret to just beyond the terminating ']. For example:
User types: Rope.Find{CTRL-E}r{NEXT}key{CTRL-NEXT}
produces: Rope.Find[s1: r, s2: key]
i.e. typing "r" filled in the first ROPE field, and typing "key" filled in the second ROPE field, and {CTRL-NEXT} deleted ", pos1: INT ← 0, case: BOOL ← TRUE" and moved the caret to after '].
Note that CTRL-E can also be used to construct forms when typing to the interpreter in a work-area (since typescripts are now editable).
Another useful application is typing CTRL-E following an expression whose value is a procedure type. The will cause the insertion of a comment describing the arguments and return values for the procedure type, and then an appropriate form for the procedure body. For example:
User types: RedSave: Menus.ClickProc{CTRL-E}
produces: RedSave: Menus.ClickProc -- [parent: REF ANY, clientData: REF ANY ← NIL, mouseButton: Menus.MouseButton ← red, shift: BOOL ← FALSE, control: BOOL ← FALSE] -- = {
Body
};
Since this operation involves the interpreter, it can be slow (but so is selecting Rope.Find and clicking Open in order to find out the arguments), especially the first time for a particular interface.
In the case of misspellings, spelling correction will take place according to your user profile. If confirmation is required, Yes No menu buttons will be posted in the corresponding viewer.
CTRL-NEXT
As described above, CTRL-NEXT is used as a "I'm finished with this, go on" in conjunction with CTRL-E abbreviation expansion. It deletes all of the fields that have default values. If there are any fields that have not been filled out that do not have default values, the first of these fields is selected and a message printed in the message window. Thus the user can use CTRL-NEXT to eliminate all fields with default values, and then proceed to fill in the remaining fields.
For convenience, CTRL-NEXT can also be used in other contexts involving forms. If the current selection is a placeHolder, CTRL-NEXT deletes the placeHolder and then does moves to the next placeholder.
Updating Last Edited Entry
When you (red) click save on a Tioga document, the system will search for a comment containing a date and your name, and if found, will automatically update the date. The algorithm used is as follows: start searching at the beginning of the document looking at all comments, where a comment is either a tioga node with the comment property, or any line beginning with -- or //, (i.e. this feature also works equally well for documents that have not been converted to Tioga node structure). In each comment, look and see if your name (i.e. the name of the user that is logged in) appears, and if there is also a date. Stop searching at the first non-empty non-comment node. If a comment of the appropriate form was found, update the date of the last such comment (so that user can have separate CreatedOn, LastEditedOn comments). Otherwise, provided that at least one comment was seen, insert a new comment of the form "Last edited by: your name, date", following the last comment.
For example, the first few lines of the file CompatibilityPackage.df are:

-- CompatibilityPackage.df
-- last edited by Levin on November 16, 1982 11:33 am
-- last edited by Andrew Birrell on August 5, 1982 11:46 am

Directory [Indigo]<Cedar>Top> CameFrom [Indigo]<PreCedar>Top>

CompatibilityPackage.df 1-Dec-82 13:19:57 PST

If Andrew Birrell were to edit this file and click save, the file would look like:

-- CompatibilityPackage.df
-- last edited by Levin on November 16, 1982 11:33 am
-- last edited by Andrew Birrell on December 1, 1982 9:57 pm

Directory [Indigo]<Cedar>Top> CameFrom [Indigo]<PreCedar>Top>

CompatibilityPackage.df 1-Dec-82 13:19:57 PST

But if Warren Teitelman were to edit the file and click save, the file would look like:

-- CompatibilityPackage.df
-- last edited by Levin on November 16, 1982 11:33 am
-- last edited by Andrew Birrell on August 5, 1982 11:46 am
-- Last Edited by: Teitelman, December 1, 1982 9:57 pm

Directory [Indigo]<Cedar>Top> CameFrom [Indigo]<PreCedar>Top>

CompatibilityPackage.df 1-Dec-82 13:19:57 PST

Note that this feature will never insert a comment unless one is already there, and will also never insert a comment at the top of the file. It can be disabled by including the entry UpdateLastEdited: FALSE in your profile (the default is TRUE), or can be bypassed for a particular file by clicking the save button with the blue mouse button, rather than the red.
Updating Change Logs
A facility for automatically generating change log entries for documents that employ Tioga node structure is available through the ChangeLog menu button, which is added to the first menu line of all Tioga documents as a result of running NewStuffImpl.bcd. Red-clicking ChangeLog will cause the system to create a change log entry at the end of the document being edited. The entry consists of a Tioga node of the form: "Edited on", the date, "by ", your name, followed by a nested node beginning with "changes to:", followed by a list of the items changed. PlaceHolders for comments are inserted following each item. (Filling in these comments is optional: any placeHolder in the change log entry that is not filled in will be automatically deleted when the file is saved.)
The changed list is generated as follows: for each Tioga node that has been edited, add an entry to the changed list, if one does not already exist, corresponding to the first (most tightly bound) type declaration that this node is under. Only consider type declarations which contain a block as part of its definition (i.e. local variable declarations of a procedure that are edited do not rate separate entries, local procedures do). If there is no such declaration, e.g. the edit is to the DIRECTORY list, or to some expression in the start code, etc., use the highest node that is not a comment. If there is such a declaration, and it is local to some higher declaration, indicate that declaration also when printing the change entry.
For example, if I edit the file PrintTVImpl.mesa by changing: (a) several of the DIRECTORY clauses, (b) the IMPORTS list, (c) the top level declaration for the type UnderLongString, and (d) the procedures EnsureInit, PutCardRope, and innerPut, the latter two of which are local procedures, the change log entry that would be produced would look like:
Edited on December 1, 1982 10:36 pm, by Teitelman
general comments
changes to: DIRECTORY, IMPORTS, UnderLongString, EnsureInit, PutCardRope (local of Print), innerPut (local of PutRecord, local of Print)
Continuing an edit "session"
A new change log entry is created only once for a particular edit session. This change log entry is said to be active as long as the corresponding document exists, and the corresponding node is part of that document, i.e. has not been deleted. In other words, the system will continue to treat edits as part of the same session as long as the user edits in the same viewer (or a viewer created as a result of splitting this viewer), and as long as the corresponding change log entry still exists. In this case, when the user clicks ChangeLog or Save (see below), a new change log entry is not created, but instead the active change log entry is updated by appending those entries that were not previously written to it at the end of the entry. (Thus the user can edit comments in the change log entry and when that entry is subsequently updated, the comments will not be touched.)
Often a single edit session will logically span several boot or rollback operations, e.g. the user makes some edits, recompiles, rollsback, reloads the file, discovers some additional problems which require more editing. In this case, it is desirable to have the latter set of edits look as though they had been performed in the same session as those performed a short while previously. In order to accomodate this behaviour, if a previous change log entry is found, and this entry is dated within 24 hours of the current time, the current set of changes will be merged with those in the previous entry, i.e. the effect is the same as though they occurred in the same edit session. (The test for whether or not such an entry exists is to search backwards from the end of the file looking at nodes with comment properties. If a node is found which contains a date, and one of the node's children begins with the characters "changes to: ", then the test succeeds. The test fails at the first non-empty, non-comment node.)
The user can override the merging of change logs and force a new change log entry by yellow-clicking ChangeLog. Similarly, the user can explicitly request merging with the previous change log, even if more than 24 hours have elapsed (e.g. to continue Friday afternoon edits on Monday morning) by blue-clicking ChangeLog.
Note that if the user clears or destroys the viewer, and then subsequently opens another viewer on the same document, or if the user deletes the active change log entry from the document, the effect is the same as though the user had booted or rolledback, i.e. a new session is started unless the previous change log entry occurred within 24 hours, etc.
Saving the file
In many situations, the user does not want to insert any comments in the change log, but simply wants to save the file with the list of changes. Rather than forcing the user to first click ChangeLog and then click Save, in those cases where the user has already indicated that he wants a change log maintained for this file, either by virtue of having previously created one by clicking ChangeLog, or by an appropriate declaration in his user profile, the user can simply click Save. Thus
(a) If there is an active change log entry, Red-clicking Save will update it, i.e. is the same as red-clicking ChangeLog and then doing the save.
(b) If the user has an entry in his profile of the form UpdateChangeLog: addIfPrevious (the default), and a change log entry was inserted by this facility in some previous edit session, then merge the two entries if their times are within 24 hours, otherwise create a new entry.
(c) If the user has an entry in his profile of the form UpdateChangeLog: createNew, and the file looks like a mesa file, then proceed as in (b). (The test for this is to search backwards from the end of the file for the first non-empty, non-comment node. This node must begin with the characters "END.". Note that this test will always fail for files that do not use Tioga node structure.)
(d) If you are feeling paranoid, Blue-clicking Save will simply cause the file to be saved without doing anything to the change log (or the Last-Edited date), regardless of your user profile, and regardless of whether a change log entry is currently active.
Summary
RedClick ChangeLog
If there is an active change log entry, update it, otherwise if there is a change log entry in the file created within the past 24 hours, merge with this entry, otherwise create a new change log entry.
YellowClick ChangeLog
Create a new change log entry.
BlueClick ChangeLog
Merge with previous change log entry if one exists,, regardless of when it was written, otherwise Create a new change log entry.
RedClick Save
If there is an active change log entry, update it, otherwise, if UpdateChangeLog = addIfPrevious, and there is a previous change log entry, create a new one (or merge with previous one if within 24 hours, otherwise, if UpdateChangeLog = createNew and file looks like a mesa file, create a new one or merge with previous one if within 24 hours.
BlueClick Save
Just write out the file.
Note that the system will never mess with your change log unless:
(1) You explicitly click ChangeLog.
(2) You explicitly clicked ChangeLog once before in this edit session.
(3) Your user profile contains UpdateChangeLog: addIfPrevious (the default), and there is already at least one change log entry there of the recognized form. In other words, in this mode, you have to start each file off with a change log the first time by explicitly yellow-clicking ChangeLog.
(4) Your user profile contains UpdateChangeLog: createNew, and the file looks like a mesa file. In other words, in this mode, change logs will automatically be started for you, but only if the file looks like a mesa file with node structure.
The system will never add duplicate entries to the change log.
The system will never disturb any changes that you make by hand to your change log, e.g. editing comments.
Remember: this facility is designed to be used ONLY in conjunction with Tioga node structures. The change log will be singularly uninteresting for a flat structured document, since all of the changes will appear to be at the same place.
Master Change Log
A facility for generating a log of all of the files that you save during a session is automatically enabled when NewStuffImpl is loaded, unless you have an entry in your user profile of the form CreateChangesLog: FALSE. This log is kept on the file Changes.Log which is created when it is first needed. Each time you save a file, the date, file name, and changes log entry that was inserted in your file via the facility Updating Changes Log discussed above, if there is such an entry, is added to this log. Here is an example of such a log:
Changes log created at 10-Mar-83 15:20:27 PST

Changed File: my.dfs
 Edited on 10-Mar-83 15:20:27 PST (no change log entry)

Changed File: io.DF
 Edited on 10-Mar-83 15:52:10 PST (no change log entry)

Changed File: teitelman.profile
 Edited on 10-Mar-83 17:16:44 PST (no change log entry)

Changed File: UserProfile.doc
 Edited on March 10, 1983 5:22 pm, by Teitelman
  changes to: Hardcopy

Changed File: UserExecImpl.df
 Edited on 10-Mar-83 17:23:44 PST (no change log entry)
The first time in a particular session that you save a file, a new Changes.Log file is created, and the existing one renamed to be Changes.Log$. For the purposes of this facility, a new session starts when you boot: rolling back reopens the existing change log, if any, and continues the previous session.
Remembering Previous Search
Whenever a Tioga document is searched via the Find, Word, or Def menu buttons, the target of the search is saved. If the target for this particular search, i.e. the current selection, is empty (i.e. a point selection), then the previous target is used instead. This enables searching for Foo, deleting it, and then searching for the next Foo by simply clicking the menu button again. It also enables searching for a particular target, changing the input focus in order to type something somewhere else, for example, to obtain a new viewer and load it with a particular file, and then searching again without having to reselect the target. (Note: if you simply point and click in a viewer, you typically will obtain a character selection, rather than a point selection, unless you point at an empty node. One simple way to convert a character selection into a point selection is to simply type anything, e.g. a space.)
Swapping icons with opened viewers
The viewers package allows you to load an existing viewer with a file while requesting that the current contents of the viewer be made iconic. This is accomplished by selecting the name of the file, and then right clicking get. NewStuff extends this feature to allow you to select an icon, and then right-click get in a viewer. This causes the icon to be opened in place of the viewer, and the viewer to be made iconic, i.e. the two are swapped. Similarly, selecting an icon and then middle clicking get will open the icon just below the viewer, and left clicking get will cause the icon to replace the viewer.