CommandToolCommands.Tioga
Russ Atkinson, July 25, 1984 11:35:41 am PDT
COMMANDTOOL COMMANDS
COMMANDTOOL COMMANDS
CEDAR 5.3 — FOR INTERNAL XEROX USE ONLY
CEDAR 5.3 — FOR INTERNAL XEROX USE ONLY
CommandTool Commands
Release as: [Indigo]<Cedar5.3>Documentation>CommandToolCommands.Tioga

© Copyright 1984 Xerox Corporation. All rights reserved.
Abstract: This document is a user's guide for the default commands provided by the CommandTool in Cedar 5.
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

For Internal Xerox Use Only
Commands
name Abort:
syntax
Abort
description
Raise ABORTED. This command will cause itself to exit abnormally. It will also have the effect of unwinding all nested instances of the command tool.
examples
% Abort
...Aborted

%
Suppose that Abort1.cm contains "Abort2.cm\nDate\n" and Abort2.cm contains "Abort\n":
% Abort1.cm
> Abort2.cm
>> Abort
...Aborted

%
Notice that the Date command was not executed.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name AddDebugSearchRules:
syntax
AddDebugSearchRules {directories}*
description
The symbol table machinery, in particular, the interface AMFiles, maintains a list of directories in which to look for symbols and source files. This command changes that list by adding each of the directories on the command line to the end of the search list. If a directory is already there, it will not be added again.
Related commands are SetDebugSearchRules and PrintDebugSearchRules.
examples
% PrintDebugSearchRules
( /// )
% AddDebugSearchRules ///Junk/ ///Acme/
% PrintDebugSearchRules
( /// ///Junk/ ///Acme/ )
%
warnings
AddDebugSearchRules does not make many consistancy checks on directory names.
implementation
CommandToolImpl.mesa in CommandTool.df
name AddSearchRules:
syntax
AddSearchRules {directory}*
description
Add a directory to the CommandTool search rules.
examples
% PrintSearchRules
( ///Commands/ )
% AddSearchRules ///Wierd /Ivy/Stewart/Commands/
% PrintSearchRules
( ///Commands/ ///Wierd/ /Ivy/Stewart/Commands/ )
%
warnings
Like SetSearchRules, AddSearchRules makes little attemp to check the validity of its arguments.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Alias:
syntax
Alias newName {(formal-parameter-list)} commandLine
description
Aliases provide a substitution macro facility for the first token on a line. Alias bro bringover /o will cause bro mumble to be expanded into bringover /o mumble. Aliases can also be given an (optional) argument list, in which case the tokens on the command line following the alias name will be substituted for the formal parameters, e.g., Alias brob (file df) bringover /a /o file.mesa file.bcd df would cause brob rope rigging to expand to bringover /a /o rope.mesa rope.bcd rigging.df.
Most things that can be done with Alias can also be done with command files.
examples
% Alias Backup List -u *!H
% Backup
AliasDoc.tioga!2
Binder.Log!1
commandtool.df!12
%
% Alias
%
warnings
Probably Alias should print the actual command line that is executed.
implementation
AliasImpl.mesa in CommandTool.df
name CacheFindExcessVersions:, CacheKillExcessVersions:
Syntax
CacheFindExcessVersions {pattern}*
description
Find (or flush) excess versions in the file cache. Excess versions are all versions other than the highest numbered version of a file.
examples
% CacheFindExcessVersions /Indigo/*fs.df
[Indigo]<Cedar5.3>Top>FS.df!1
%
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name Checkpoint:
Syntax
Checkpoint
description
Create a checkpoint. This is a simple interface to Booting.Checkpoint and is otherwise the same as the procedure called by the Checkpoint button in the herald.
examples
% Checkpoint
Checkpoint created at November 25, 1983 9:01 pm
%
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Command:, Source:
syntax
Command
Source
Create a new, independent, command tool.
Command file
Source file
Create a nested command tool which will execute commands from the command file file. If file cannot be found, then file.cm is tried. If file is not a full path name, then the command tool will try the current working directory and all directories on the command tool search rules.
Command file arg1 arg2
Source file arg1 arg2
Run the command file file with the "arguments" arg1 arg2 . . . Arguments to a command file can be gotten from commands inside that command file by use of the formal arguments $1, $2, etc.
description
Create a new Command Tool or run a command file. Nested instances of the command tool tend to use some number of '> characters as a prompt in order to indicate the depth of nesting.
The source command does not copy the process and command tool property lists, so that commands run from a "source" can change the properties seen by the command tool which invoked the source. A ChangeWorkingDirectory in a command file run with "Cmd" does not persist, but a ChangeWorkingDirectory in a command file run with "Source" holds its effects.
examples
Suppose the file Test1.cm contains "Date\nCommander Test2.cm\n" and Test2.cm contains "User\n":
% Command Test1
> Date
November 1, 1983 6:43 pm
> Command Test2.cm
>> User
User: Stewart.pa
%
warnings
There are doubtless many bugs. A careful reading of CommandToolDoc.tioga will answer many questions.
Don't type Command&, it doesn't do anything useful. Actually, it directs the error streams to the new window that gets created, which isn't that useful.
Suppose the file Test3.cm contains "Command Test3.cm\n":
% Command Test3.cm
> Command Test3.cm
>> Command Test3.cm
>>> Command Test3.cm
>>>> Command Test3.cm
>>>>> Command Test3.cm
>>>>>> Command Test3.cm
...Aborted

%
implementation
CommandTool.df, especially CommandToolImpl.mesa
name Copy:
syntax
Copy {-c} to ← from
Copy a single file.
Copy {-c} {-r} target-directory ← list-of-patterns
Copy {-c} {-r} list-of-patterns
Copy a group of files to a new directory. The target-directory may be explicit, as in the first case, or will default to the current working directory in the second case.
description
The copy command is a thin veneer user interface to FS.Copy. In particular: FS.Copy[from: from, to: to, keep: createKeep, attach: TRUE]. createKeep is a global variable in FSFileCommandsImpl.mesa. FS.Copy will be called with attach: FALSE if the -c switch is set.
The first form of copy is Copy to ← from. This form copies a single file.
FS uses the current working directory if either to or from are not full path names.
The second and third forms of Copy create a series of FS attachments from local names to each remote name matched by an argument. This is a very fast way to establish a local copy of a complete remote subtree. Since attachments are used, the bits of the files are only retrieved when needed. (However, if the -c switch is set, the actual bits are copied!)
The pattern '* does not match the characters '/ or '>, but the pattern "**" does. This means that unless you use "**", copy will not copy any files in subdirectories. If the -r switch is set, (and ** is used) then Copy will retain the directory structure of the source. If the -r switch is absent, the shortnames of the source files will be retained, but subdirectory structure will be lost.
Here is the discussion of Copy from FS.mesa.
(To be updated from the appropriate version of FSDoc.tioga.)
The version of the "to" file created is one larger than the existing !H version, unless "to" is a GName on a server that does not support version numbers, in which case an existing global file will be overwritten.
Case 1: "to" is a GName and "attach" is FALSE — FS does an FS.Open[from, read, wantedCreatedTime, remoteCheck, wdir] and stores the contents and properties of the opened file directly in the new "to" file on the remote server.
Case 2: "to" is an LName and "attach" is FALSE — FS does an FS.Open[from, read, wantedCreatedTime, remoteCheck, wDir] to generate a "from" open file, and FS.Create[to, setKeep, keep, wDir] to generate a "to" OpenFile. The contents and properties are copied from the "from" OpenFile to the "to" OpenFile, and both are closed. (In the case of copying from an uncached global file, the global file is not added to the cache. The only pages allocated on the local volume are those needed to hold the target local file.)
Case 3: "to" is a GName, "attach" is TRUE, and "from" is a LName — Things proceed as in case 1, except a "write" lock is acquired for the "from" file. Once the transfer is completed, the LName is attached to the GName. Case 3 is used by "SModel".
Case 4: "to" is an LName, "attach" is TRUE, and from" is a GName — Like case 2 except that instead of an actual transfer of contents and properties, the LName is attached to the GName / created-time. If no "wantedCreatedTime" is specified, or if "remoteCheck" is TRUE, then FS.FileInfo[to, wantedCreatedTime, TRUE] is performed first to determine/check the version number and created-time for the GName and any resulting FS.Error is passed on to the client. When "remoteCheck" is FALSE (but a wantedCreatedTime" is specified) then the attachment is made to the "from" and "wantedCreatedTime" arguments without checking either the remote server or the cache. Case 4 is used by "BringOver".
Case 5: both "from" and "to" are LNames, or both are GNames, and "attach is "TRUE" — FS proceeds as though "attach" were FALSE (see cases 1 and 2 above).
examples
% Copy TrapsImpl.bcd ← /indigo/PreCedar/MesaRuntime/TrapsImpl.bcd!1
% Copy /Ivy/Stewart/Temp/Compiler.log ← Compiler.log
%
% CD ///test/
% Copy /ivy/stewart/temp/W*
///test/w1aw.txt ← [ivy]<Stewart>temp>w1aw.txt!3
///test/WFReal.mesa ← [ivy]<Stewart>temp>WFReal.mesa!1
///test/wfrealimpl.mesa ← [ivy]<Stewart>temp>wfrealimpl.mesa!4
///test/wfrealtest.mesa ← [ivy]<Stewart>temp>wfrealtest.mesa!4
///test/wink.mesa ← [ivy]<Stewart>temp>wink.mesa!1
%
% Copy ///test/ ← /ivy/stewart/temp/protocol.txt /ivy/stewart/temp/printcl.bcd
///test/protocol.txt ← [ivy]<Stewart>temp>protocol.txt!1
///test/printcl.bcd ← [ivy]<Stewart>temp>printcl.bcd!1
%
warnings
There is presently no way to change the value of createKeep, but the SetKeep command will change the keep for a particular file.
If a pattern does not include a version number specification, then !H is appended.
If a pattern which matches a subtree (files in subdirectories) is used, the subdirectory structure will be lost.
It is likely that Copy remote-pattern!* does not do what you think!
% Copy /Ivy/Stewart/temp/W1aw.txt!*
///wierd/w1aw.txt ← [Ivy]<Stewart>temp>w1aw.txt!1
///wierd/w1aw.txt ← [Ivy]<Stewart>temp>w1aw.txt!2
///wierd/w1aw.txt ← [Ivy]<Stewart>temp>w1aw.txt!3
% list w1aw.txt
[]<>wierd>w1aw.txt!2 []<>wierd>w1aw.txt!3
%
The attachments were made in the order shown, but the default keep = 2 has causes w1aw.txt!1 to fall off the edge. There is no guarantee that the local w1aw.txt!2 is the same as the remote w1aw.txt!2, as can be seen by the following example:
% Copy /Ivy/Stewart/temp/W1aw.txt!*
///wierd/w1aw.txt ← [ivy]<Stewart>temp>w1aw.txt!1
///wierd/w1aw.txt ← [ivy]<Stewart>temp>w1aw.txt!2
///wierd/w1aw.txt ← [ivy]<Stewart>temp>w1aw.txt!3
% list w1aw.txt
[]<>wierd>w1aw.txt!5 []<>wierd>w1aw.txt!6
%
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name CopyCommand:
syntax
CopyCommand newName ← oldName
If newName is not a full path name, then CopyCommand will register it in the current working directory. CopyCommand uses CommandTool.LookupWithSearchRules to find the commandProc corresponding to oldName.
description
Attach a new name to an existing command without deleting the old name. This command merely makes a new entry in the Commander registry with the new name and the old CommandProc.
examples
% CopyCommand Acme ← Date
% Acme
November 1, 1983 5:39 pm
% Date
 November 1, 1983 5:39 pm
%
warnings
At this writing, both oldName and newName must be exact, the working directory and lookup stuff is not implemented.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name CreateButton:
syntax
CreateButton buttonName commandLine
description
The command appends a button to the herald of the CommandTool in which it is run. The name of the button is buttonName. When the button is clicked, the commandLine is transformed as described below and stuffed into the CommandTool input. Before stuffing, the button procedure checks to see whether or not the current input buffer of the CommandTool ends with a CR. If it does not, then the buffer is erased back to the last CR.
The button procedure appends a CR to the end of commandLine if there is not one there already.
Substitutions are done on commandLine before stuffing it. The following special strings are replaced as shown:
$CurrentSelection$ => replaced by the current selection up to but not including the first carriage return
$FileNameSelection$ => replaced by the current selection if it appears to be a file name, otherwise replaced by the name of the selected viewer
$ShortFileNameSelection$ => same as $FileNameSelection$ except that version number and directory are omitted
$SelectedViewerName$ => replaced by the name of the selected viewer
$ViewerPosition$ => replaced by the position of the current selection in a viewer
$MouseButton$ => "left", "middle", or "right"
$ShiftKey$ => "shift", "noShift"
$ControlKey$ "control", "noControl"
The idea is that one writes an ordinary command line CommandProc to do some job, then use CreateButton to hook up a button to it.
examples
% CreateButton Test // CurrentSelection = $CurrentSelection$, FileNameSelection = $FileNameSelection$, SelectedViewerName = $SelectedViewerName$, ViewerPosition = $ViewerPosition$, MouseButton = $MouseButton$, ShiftKey = $ShiftKey$, ControlKey = $ControlKey$
% -- Select something like "Atom" in the viewer CommandsCImpl.mesa and click control shift middle
% // CurrentSelection = Atom, FileNameSelection = Atom, SelectedViewerName = []<>ct>commandscimpl.mesa, ViewerPosition = 12, MouseButton = middle, ShiftKey = shift, ControlKey = control
%
warnings
For now, you have to type a carriage return yourself to make the button push really happen.
implementation
CommandsCImpl.mesa in CommandTool.df
name Date:
syntax
Date
description
Print date and time on standard output stream.
examples
% Date
November 1, 1983 4:00 pm
%
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Delete:
syntax
Delete {pattern}*
description
Delete deletes FS files. It does not ask for confirmation. Both local and remote patterns can be used. If there is no version number, the default is !L.
Delete does an FS.EnumerateForNames and deletes the files it finds. The pattern '* does not match the characters '/ or '>, but the pattern "**" does. This means that unless you use "**", delete will not delete any files in subdirectories.
Here is the discussion of Delete from FS.mesa.
(To be updated from some version of FSDoc.tioga)
A missing verion part defaults to !L. If "name" is an GName then the file is deleted directly from the remote server (and removed from the cache). An FS.Error[lock, $lockConflict] occurs if the specified file is currently open. If "name" is an LName that is attached to some GName, then just the LName is deleted; the global file is not deleted. Note that deleting the !H verison may cause a previous verison to become the new !H version, and therefore cause the keep on the previous version to become the controlling keep for the set of versions.
examples
% Delete /Ivy/Stewart/Temp/W1aw.txt!2
deleting /Ivy/Stewart/Temp/W1aw.txt!2

% Delete ///temp/*
deleting []<>temp>Binder.Log!1
deleting []<>temp>commands.txt!1
deleting []<>temp>foo.cm!1

% Delete ///temp/*
deleting []<>temp>commands.txt!2

%
warnings
Delete does not ask for confirmation.
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name Echo:
syntax
Echo ... anything ...
description
Echo parses its command line with CommandTool.Parse and prints the resulting tokens with separating spaces and a final carriage return. It is most useful to see what one of your command lines expands into. It is also useful for getting star patterns into a file.
examples
% Echo a b c
a b c
%
In the very simplest cases, Echo repeats the argument string.
% Echo j*
[]<>JaMStuff.df!1 []<>junk.txt!1
%
Echo does star expansion.
% Echo a&Prompt b
a%% b
%
Echo does Ampersand substitution.
Suppose that the command file EchoTest.cm contains "Echo arg1 = |$1| arg2 = |$2|\n":
% EchoTest.cm XXX YYY
> Echo arg1 = <$1> arg2 = <$2>
arg1 = <XXX> arg2 = <YYY>
%
Echo does Dollar substitution.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Fail:
syntax
Fail
description
This Commander.CommandProc merely returns [$Failure, "This Command Always Fails"]. This will terminate processing of further commands on the same line.
examples
% Date; Fail; Date
November 1, 1983 4:03 pm
This Command Always Fails
[[Command Failed]]
%
This command was implemented in order to test whether nested instances of the command tool would work.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name FindExcessVersions:, KillExcessVersions:
syntax
FindExcessVersions {pattern}*
description
FindExcessVersions finds (KillExcessVersions deletes) excess version of files that match the given patterns (* is the default). Excess versions are all versions other than the highest numbered version of a file.
examples
% kill
 deleting []<>Cedar5.3>Binder.df!1
. . .
%
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name FlushCache:
syntax
FlushCache {pattern}*
description
FlushCache deletes files from the FS local disk cache. It has no implact on Cedar 5 except in performance. (However, if the server which stores the file that you just flushed is down, you will be out of luck.)
It can be used:
a) to force a retrieval of a certain file when naext referenced.
b) to give advice to FS that a file or group of files will not be needed for a long time.
examples
% FlushCache [Ivy]<Stewart>CommandTool>*
 flushing [Ivy]<Stewart>CommandTool>CompileCommandTool.cm!2
flushing [Ivy]<Stewart>CommandTool>FSFileCommandsImpl.bcd!4
. . .
%
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name GetProperties:, GetProcessProperties:
syntax
GetProperties {-d INT} {-w INT} {key}*
GetProcessProperties {-d INT} {-w INT} {key}*
If the -d switch is found, the next command line token is interpreted as the depth to which to print nested property structure. If the -w switch is found, the next command line token is interpreted as the width to which to print property structure such as arrays. The default depth is 5 and the default wideth is 32. Any other command line tokens are interpreted as specific keys for properties to be printed. If no keys are found, the entire property list is printed. If a key is of the form $key, then Atom.MakeAtom[key] is used as the key. If the first character of a key is not '$, then it is interpreted as a rope. Commander.GetProperty is used for individual property lookups, so rope keys are matched on content. (However, the use of ATOMs for property list keys is strongly encouraged.)
description
Display one or more properties from the commander or process properties lists. Refer to CommandLine.tioga for information on the standard properties and their uses.
GetProperties prints properties from the commander property list, while GetProcessProperties prints properties from the process property list.
examples
% GetProperties $Prompt
$Prompt = "%% "
%
% GetProcessProperties $WorkingDirectory
process properties:
$WorkingDirectory = "///"
%
% GetProperties -d 3
commander properties:
(^[key: $Prompt, val: "%% "], ^[key: $ErrorInputStream, val: 3343504B^], ^[key: $ReadEvalPrintHandle, val: 6214556B^], ^[key: $SearchRules, val: 7314462B^], ^[key: $Lookup, val: 7314630B^], ^[key: $Result, val: NIL])
%
This is a benign command, so try a few things!
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Help: ?:
syntax
? pattern {pattern}*
Help {pattern}*
If pattern does not include a *, then a CommandTool.LookupCommand is done to find the command. This has some interesting consequences described in the warnings section!
If pattern is a directory name, then a * is appended -- ? directoryName will display all commands registered in a particular directory and its subdirectories.
If pattern is not a full path name, and includes a *, then a * is prepended. Thus ? lis* will behave like ? *Lis*.
Documentation CommandName
Where CommandName is a single argument.
description
The ? command lists registered commands. ? searches the commander registry for command names and prints the documentation rope, which is likely to be terse...
Help is synonymous with ?.
examples
% ? Version Date
///Commands/Version Print Cedar version number
///Commands/Date Print date and time
%
% ? ve*
///Commands/FSBringover FSBringover list-of-remote-patterns
///Commands/Scavenge Scavenge {volumeName} -- FS scavenge
///Commands/Version Print Cedar version number
%
warnings
If a pattern passed to ? does not include a *, then a CommandTool.LookupCommand is done to find it. If the command exists, this does the right thing, as shown above by the ? Version Date command. However, LookupCommand works by calling each procedure stored under the $Lookup property. . .
One of the default procedures is one which calls command files. Suppose there is no registered command named foo, but there is a command file named foo.cm in a directory on the commander search rules:
% Help foo
(Generic command) Commander ///foo.cm!3
%
What happened was that the command file lookup procedure decided that the appropriate action was to call the Commander command (see Commander) with ///t1.cm!3 as its first argument. This would be a clue that foo is something that is interpreted by the Commander command, but ? does not follow it up, you can do it yourself of course by typing Help Commander.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Indent:
Syntax
Indent
The default argument is 8.
Indent n
n must be a number IN [0..80]
description
Indent is a filter which reads the standard input and prints each line (delimited by CR) on the standard output after printing some number of spaces.
examples
% Date | Indent 10
November 1, 1983 7:20 pm
%
warnings
Indent catches ViewerIO.Rubout, so if it is started reading from the keyboard, a DEL will stop it. It also catches IO.Error, so an unexpectedly closed stream will not break it.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name List:, LS:
syntax
List {switch | pattern}*
Switches (case not important)
~ negates the sense of the following switch
A prints Attachments (← false)
B inhibits printing of size and create date (← false)
D sorts files by create Date (← no sort)
F forces Full file name printing (← false)
K prints Keep information (← false)
N forces Narrow printing (size and date on separate line) (← false)
O forces printing to One line where reasonable (← false)
P prints only Prefixes (directories) (← false)
R forces Remote checking (← false)
S sorts files by Size in bytes (← no sort)
U prints only Unattached files (← false)
X eXact level match (causes "*" to not match ">") (← false)
> causes sorting by most recent first for dates, largest first for sizes (default)
< causes sorting by least recent first for dates, smallest first for sizes
Switches can appear anywhere within a command line. Their effect is cumulative within the command.
List -U prints only those files which are not FS attachments and which consequently are not backed up anywhere. List -u ///* is a good way to get a list of all such files. List -u ///*!H is probably most helpful, since only the most recent files are of particular interest.
The user can tailor the default switches for List by the user profile. As an example, to default the F and R switches to true, use:
ListCommand.DefaultSwitches: fr
description
The list command prints names and possibly information about files in the FS directory system. It is a user interface for the FS.EnumerateForInfo and FS.EnumerateForNames calls.
List works for both local and remote patterns.
List works in the current working directory if a pattern is not a full path.
List works with both / and [ style filenames.
If a pattern given to List is a directory name, (ends with a '/ or '>) then a '* is appended.
examples
% list ///Compiler.log
[]<>Compiler.log!212 237 11-Jul-84 20:39:07 PDT
-- 1 files, 237 total bytes
% list -f ///Compiler.*
[]<>Compiler.bcd!3 294400 16-May-84 19:47:10 PDT
[]<>Compiler.config!1 3064 25-Jan-84 12:49:23 PST
[]<>Compiler.df!6 17634 30-May-84 10:40:40 PDT
[]<>Compiler.load!2 78 21-Nov-83 14:55:08 PST
[]<>Compiler.log!212 237 11-Jul-84 20:39:07 PDT
-- 5 files, 315413 total bytes
% list -bfo ///Compiler.log
[]<>Compiler.bcd!3 []<>Compiler.config!1 []<>Compiler.df!7 []<>Compiler.load!2
-- 4 files
% list -n ///Compiler.* -d ///Compiler.*
[]<>
Compiler.bcd!3 294400 16-May-84 19:47:10 PDT
Compiler.config!1 3064 25-Jan-84 12:49:23 PST
Compiler.df!6 17634 30-May-84 10:40:40 PDT
Compiler.load!2 78 21-Nov-83 14:55:08 PST
Compiler.log!212 237 11-Jul-84 20:39:07 PDT
[]<>
Compiler.log!212 237 11-Jul-84 20:39:07 PDT
Compiler.df!6 17634 30-May-84 10:40:40 PDT
Compiler.bcd!3 294400 16-May-84 19:47:10 PDT
Compiler.config!1 3064 25-Jan-84 12:49:23 PST
Compiler.load!2 78 21-Nov-83 14:55:08 PST
-- 10 files, 630826 total bytes
implementation
ListCommandImpl.mesa in CommandTool.df
name ListBTree:
syntax
ListBTree {-switches} {pattern}*
-l switch (local) print files which are local (not-backed up)
-a switch (attached) print files which are attachments but which are not cached locally
-c switch (cached) print files which are attachments and which are cached locally
The default switches are -lc because those are precisely the files which occupy space on the local disk.
description
ListBTree lists files in the FS cache. The first character of a line indicates the type of file (L means local, A means attached, C means cached). Local files print their names only, attached files prinnt both LName and GName. Cached files print their GNames and the time last used.
examples
% ListBTree [Ivy]*
[Ivy]<CedarViewers>Viewers>Standard.icons!6
used at November 4, 1983 1:16 pm
[Ivy]<Stewart>Cedar>bugs.txt!1
used at November 2, 1983 5:32 pm
. . .
%
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name Load:
syntax
Load {pattern}*
If the pattern does not include a version number, then !H is appended.
description
Load forces FS to retrieve the actual bits of one or more files to the local disk. it does this by opening each file in read mode and then closing it again. Naturally, if the number of files Loaded exceeds the local disk capacity, the FS replacement algorithm may flush some of them again.
examples
% Load /Ivy/Stewart/Top/*
loading [Ivy]<Stewart>Top>Commander5.df!13
loading [Ivy]<Stewart>Top>CommandTool.df!17
. . .
%
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name Open:, New:
syntax
New
Open {pattern}*
If open does not have an argument, then it creates an empty viewer, otherwise it opens a viewer on each of the files expanded by the List of Pattern. There is a list of extensions that are tried. See the documentation for the User.profile (I think).
description
Open tioga viewer(s) on file(s) or create an empty tioga viewer.
examples
% Open xxx.mesa
%
% New
%
% Open foo*.mesa bar*.mesa!H
%
warnings
If you open a pattern without an explicit version number, then a "!H" will be appended.
If a "!H" is found in a pattern, then Open will strip off the version numbers before opening the viewers. If !*, or !L, or explicit version numbers of any form other than !H are used, the viewers opened will be version number locked (funny things will happen if you try to save).
implementation
InitialCommandsImpl.mesa in CommandTool.df
name PrintDebugSearchRules:
syntax
PrintDebugSearchRules
description
The symbol table machinery, in particular, the interface AMFiles, maintains a list of directories in which to look for symbols and source files. This command prints that list.
Related commands are AddDebugSearchRules and SetDebugSearchRules.
examples
% PrintDebugSearchRules
( /// ///ct/ )
%
implementation
CommandToolImpl.mesa in CommandTool.df
name RemoveButton:
syntax
RemoveButton buttonName
description
The command removes a button from the menu of the CommandTool in which it is run. The name of the button is buttonName.
examples
% CreateButton Test Echo Test
% RemoveButton Test
%
implementation
CommandsCImpl.mesa in CommandTool.df
name Rename:
syntax
Rename newFile ← oldFile
The second argument must be exactly ←, and must be surrounded by spaces.
Rename {-r} target-directory ← list-of-patterns
Rename {-r} list-of-patterns
Rename a group of files to a new directory. The target-directory may be explicit, as in the first case, or will default to the current working directory in the second case.
description
Rename renames files using FS.Rename. If full path names are not used, FS will operate on files in the current working directory.
The pattern '* does not match the characters '/ or '>, but the pattern "**" does. This means that unless you use "**", rename will not rename any files in subdirectories. If the -r switch is set, (and ** is used) then Copy will retain the directory structure of the source. If the -r switch is absent, the shortnames of the source files will be retained, but subdirectory structure will be lost.
Here is description of Rename from FS.mesa.
(To be updated from FSDoc.tioga.)
A missing version part defaults to !H for the "from" name. FS.Rename is the same as FS.Copy followed by FS.Delete, with the performance optimization that in many cases the actual transfer of bits can be skipped. An FS.Error[lock, $lockConflict] occurs if the specified file is currently open. Renaming that implies copying from one server to another is allowed. Renaming (and implied copying or deletion) on global servers occurs synchronously.
examples
% rename bar ← junk.txt
% rename bar.txt ← [ivy]<Stewart>temp>w1aw.txt
% rename /Ivy/Stewart/Temp/Compiler.log ← Compiler.log
% rename /Ivy/Stewart/Notes/Compiler.log ← /Ivy/Stewart/Temp/Compiler.log
% rename /Ivy/Stewart/Temp/*
Move all files in /Ivy/Stewart/Temp/ to the current working directory.
% rename ///Temp/ ← /Ivy/Stewart/Temp/*
Move all files in /Ivy/Stewart/Temp/ to ///Temp/.
warnings
If a pattern does not include a version number specification, then !H is appended.
If a pattern which matches a subtree (files in subdirectories) is used, the subdirectory structure will be lost.
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name Rollback:
Syntax
Rollback
description
Roll back to previous a checkpoint. This is a simple interface to Booting.Boot and is otherwise the same as the procedure called by the Rollback button in the herald.
examples
% Rollback
{poof}
% Checkpoint
Checkpoint created at November 25, 1983 9:01 pm
%
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Run:
syntax
Run {-d} {-a} file*
load and start a BCD. You may omit the extension if it is ".bcd". The -d switch says to not START the BCDs if they have unbound imports. The -a switch says to load and Start a .bcd whether or not it has been previously loaded.
description
load a BCD UNLESS it is already loaded, in which case return normally without doing anything. An appropriate message will be printed to indicate the action taken. Interface to Loader.Instantiate and Loader.Start. See CommandTool.Run.
The -a overrides the unless it is already loaded clause.
The -d causes the bcd to not be STARTed if it has unbound imports.
warnings
You will find out about version mismatches etc. If there are any errors other than unbound imports, the module or configuration will not be STARTed. If there were unbound imports, the BCD will be STARTed unless the -d switch is set.
implementation
CommandToolImpl.mesa in CommandTool.df
name Scavenge:
description
Scavenge {volumeName}
The volumeName defaults to the current volume.
description
Scavenge invokes FSBackdoor.ScavengeDirectoryAndCache. This command takes a long time.
examples
% Scavenge
%
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name SetDebugSearchRules:
syntax
SetDebugSearchRules {directory}*
description
The symbol table machinery, in particular, the interface AMFiles, maintains a list of directories in which to look for symbols and source files. This command changes that list by deleting the old one and installing each of the directories on the command line.
If the directory /// is not present on the command line it will be added as well.
Related commands are AddDebugSearchRules and PrintDebugSearchRules.
examples
% SetDebugSearchRules ///Junk/ ///Acme/
% PrintDebugSearchRules
( ///Junk/ ///Acme/ /// )
%
warnings
SetDebugSearchRules does not make many consistancy checks on directory names.
implementation
CommandToolImpl.mesa in CommandTool.df
name SetFreeboard:
syntax
SetFreeboard nPages
nPages should be a positive integer
description
Set the FS cache freeboard parameter. This command is an interface to FSBackdoor.SetFreeboard.
examples
% SetFreeboard 1100
% PrintFSCacheInfo
size = 27999, free = 1501, freeboard = 1100
%
warnings
Does SetFreeboard to a large value actually cause cache flushes? Experiment says not...
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name SetKeep:
syntax
SetKeep keep {pattern}*
Keep should be a positive integer. A keep value of 0 leaves the current keep alone, but does the keep processing of deleting any versions that are not in use and which are inconsistant with the existing keep value.
description
Set the FS keep parameter of local files. SetKeep will actually delete on the spot any versions of the file which are not in use and which would not be retained given the new value of keep. This command is an interface to FS.SetKeep.
examples
% SetKeep 2 /ivy/stewart/temp/w1aw.txt
... FS.Error[Can't set the keep on a GName.]
%
SetKeep doesn't work for remote files (they have no FS keep property).
% SetKeep 2 Test3.cm
%
warnings
One cannot call SetKeep using a name that has a version number! I'm not sure why. Consequently, using a pattern doesn't make sense yet.
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name SetProperty:, SetProcessProperty:
syntax
SetProperty key value
SetProcessProperty key value
If key is of the form $key then it is interpreted as the name of an ATOM, otherwise it is interpreted as a rope. Commander.PutProperty is used, so ropes match bases on contents.
Values are always ropes, with the exception that the value NIL is interpreted as NIL. SetProperty key NIL essentially clears that property altogether.
description
These commands will set the values of properties on the commander or process properties lists.
examples
% SetProperty $Prompt "Hello "
Hello SetProperty $Prompt "%% "
%
You are probably wondering why "%% " is used above. The CommandTool uses ReadEvalPrint to manage user interaction, ReadEvalPrint uses IO.PutF to print prompts, and % is a special character to PutF. . .
% SetProperty $Prompt "% "
#####SetProperty $Prompt "%% "
%
Where ##### is the default PutF reaction to a malformed format string.
% SetProcessProperty $WorkingDirectory ///Wierd/
% PrintWorkingDirectory
///Wierd/
%
This is an effective way to change your working directory, but the ChangeWorkingDirectory or CD commands are more sensible.
warnings
Many properties are not Rope.ROPEs, so setting them to some rope value is likely to produce unusual results, such as an uncaught signal.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name SetSearchRules:
syntax
SetSearchRules {directory}*
description
Set the CommandTool search rules. The arguments should be names of directories. SetSearchRules will append a '/ (or '> as appropriate) to any directory name that does not already have one.
examples
% SetSearchRules ///Commands/ ///Wierd/
% PrintSearchRules
( ///Commands/ ///Wierd/ )
%
warnings
SetSearchRules makes only brief checks that its arguments are really directories. SetSearchRules rejects any directory name shorter than three characters because /// is the shortest directory name and it rejects any name that does not start with '/ or '[.
% ///Commands/SetSearchRules [!#!#!#!
% ///Commands/PrintSearchRules
( [!#!#!#!> )
%
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Shift:, ShiftInterp:
syntax
Shift command-line
ShiftInterp command-line
description
Execute the given command line using CommandTool.DoCommand. Shift is an uninterpreted command while ShiftInterp is interpreted. You can user ShiftInterp to run a normally uninterpreted command in interpreted mode, getting IO redirection etc.
examples
% Shift Echo a b c
% Echo a b c
a b c
%
warnings
Be careful that the command line syntax interpreted by the command tool does not conflict with that required by an uninterpreted command.
There is no way to get a normally interpreted command to run uninterpreted.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Sleep:
syntax
Sleep n
n should be a valid CARDINAL.
description
Pause for n seconds, using Process.Pause
examples
% Sleep 5
%
warnings
The argument should be a valid CARDINAL.
% Sleep xxx
Bad arg
%
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Statistics:
syntax
Statistics
description
Toggle statistics printing. This command (when ON) prints running time, number of words allocated, and page faults for each command run in that CommandTool.
examples
% Statistics
% Date
November 1, 1983 6:31 pm
{00:00:00.07 seconds, 26 words, 2 page faults}
% Statistics
% Date
November 1, 1983 6:31 pm
%
warnings
Statistics do not yet behave sensibly with commands started with & or pipes.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Tee:
syntax
Tee
copy to standard output only, a null filter
Tee file
copy to file and to standard output
description
Tee is a filter which copies the standard input to a file and to the standard output. It can be used to obtain a log copy of the activities of some command.
examples
% List -u * | Tee UnbackedUpFiles.txt
. . .
%
warnings
Tee catches ViewerIO.Rubout, so if it is started reading from the keyboard, a DEL will stop it. It also catches IO.Error, so an unexpectedly closed stream will not break it.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Time:
syntax
Time command-line
description
Print the execution time of a command. Time uses CommandTool.DoCommand to "run" its arguments as a command line, then prints how long it took.
examples
% time Date
November 8, 1983 4:33 pm
Running time: 00:00:00.05
%
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Type:
syntax
Type {pattern}*
description
Print the contents of one or more files on the standard output. fileName (in executive window).
Because standard streams are used to read from the file., Tioga formatting and comment nodes disappear.
examples
% type test.cm
-- test.cm
///Commands/echo sleeping now
///Commands/sleep 1
///Commands/echo done sleeping
% type [ivy]<Stewart>temp>bu*

--bugs.txt
DONE command files do not print their command lines

...Aborted

%
The typeout was halted by clicking STOP!
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name Unregister:
syntax
Unregister fullPathName
A Commander.Lookup[fullPathName] is done. If the name exists, then the name is re-registered with a NIL CommandProc, effectively wiping out what was there before.
description
Unregister a command, so that it can no longer be invoked.
examples
% Unregister Alias
Unregister: Alias not found
% Unregister ///Commands/Alias
% Alias
[[Alias . . . not found]]
%
warnings
Unregister just sets the proc field of the stored record to NIL, so that clients of Commander.Lookup must be careful to check that the proc field of the CommandProcHandles returned by Lookup are not NIL.
Someday, this command may merely rename these to-be-deleted commands into another "directory" from which they can be retrieved.
implementation
InitialCommandsImpl.mesa in CommandTool.df
name User:
syntax
User
description
Print name of logged in user on standard output stream.
examples
% User
User: Stewart.pa
%
implementation
InitialCommandsImpl.mesa in CommandTool.df
name Version:
syntax
Version
description
Print Cedar version number on standard output stream.
examples
% Version
Cedar 5.0.101 of October 28, 1983 10:37 am
%
implementation
InitialCommandsImpl.mesa in CommandTool.df
Working directory commands
The working directory commands are grouped together to facilitate understanding their interactions.
name PushWorkingDirectory: Push:
name PopWorkingDirectory: Pop:
name ChangeWorkingDirectory: CD:
name PrintWorkingDirectory: PWD:
Syntax
ChangeWorkingDirectory directoryName
CD directoryName
PushWorkingDirectory directoryName
Push directoryName
If the directoryName is empty, then the user's home directoy is used (///Users/UserName/). The argument is converted to slash format and a relative paths is resolved. If the directoryName does not end with '/, then one is appended.
PrintWorkingDirectory
PWD
PopWorkingDirectory
Pop
No arguments
description
ChangeWorkingDirectory sets the $WorkingDirectory property of the process properties list. FS uses this property whenever no explicit working directory is passed to an FS procedure. ChangeWorkingDirectory clears the "stack" that Push and Pop use.
PrintWorkingDirectory prints the current working directory. This command is a specialized case of GetProcessProperties $WorkingDirectory. In addition to printing the value of the property, PrintWorkingDirectory changes the herald of the CommandToolWindow (if there is one) to the correct value. PrintWorkingDirectory is a good way to make sure the herald is right.
Push and Pop are inverse operations on the working directory. Push sets the working directory and saves the previous working directory on a stack (implemented as the $WorkingDirectoryStack property). Pop restores the working directory from the stack. If the stack was empty, Pop does nothing.
All these commands rewrite the herald of the CommandTool viewer if there is one.
CD and Push will accept relative path names as well as full path names. For example, .. refers to the parent of the current working directory.
examples
Suppose you want to switch directories to work on the Bustle program.
% cd ///Projects/Bustle/
% pwd
///Projects/Bustle/
%
Suppose you want to browse for a while in the Cedar documentation, but then wish to return.
% PrintWorkingDirectory
///Projects/Bustle/
% Push [Indigo]<Cedar>Documentation>
% Open DFIncludes.txt
Created Viewer: [Indigo]<Cedar>Documentation>DFIncludes.txt
. . .

% Pop
% PrintWorkingDirectory
///Projects/Bustle/
%
Here are some examples of the kinds of names that work:
% cd ///
% cd []<>
%
Both slash and bracket format names work.
% pwd
% ///Projects/Bustle/
% cd temp/foo
%
Relative change to the directory ///Projects/Bustle/temp/foo/.
% cd ../..
%
Change the working directory back to ///Projects/Bustle/, which is the grandparent of ///Projects/Bustle/temp/foo/.
% cd ../bar/.
%
Change the working directory to be bar/, which is a subdirectory of the parent directory of the present working directory.
warnings
CD (and Push) do not make many checks on the reasonableness of the directoryName parameter:
% cd #~#~#~#
%
PrintWorkingDirectory calls CommandTool.CurrentWorkingDirectory[] which has a couple of side effects besides just returning the property value. If the working directory property doesn't exist, CurrentWorkingDirectory sets it to the same as the default working directory. CurrentWorkingDirectory also converts the working directory name to slash format and appends a '/ if the last character is not '/.
At this writing, some Cedar 5 subsystems behave badly when the working directory is not ///.
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name PrintDefaultWorkingDirectory:
syntax
PrintDefaultWorkingDirectory
description
Print FS the default working directory. This is a user interface to FS.GetDefaultWDir. The default working directory is what FS uses if you do not specify full path names and there is no $WorkingDirectory property on the process property list.
examples
% PrintDefaultWorkingDirectory
 ... default working directory is []<>
%
implementation
FSFileCommandsImpl.mesa in CommandTool.df
name SetDefaultWorkingDirectory:
syntax
SetDefaultWorkingDirectory directoryName
description
The the FS default working directory. This is just an interface to FS.SetDefaultWDir. The default working directory is what FS uses if you do not specify full path names and there is no $WorkingDirectory property on the process property list.
examples
% SetDefaultWorkingDirectory ///temp/
... default working directory is []<>temp>
% SetDefaultWorkingDirectory []<>
... default working directory is []<>
%
warnings
SetDefaultWorkingDirectory will produce FS errors if the argument is not a valid directory name. Probably this should be fixed.
implementation
FSFileCommandsImpl.mesa in CommandTool.df