{Begin SubSec Manipulating File Directories}
{Title Manipulating File Directories}
{Text

The following function allows the user to conveniently specify and/or program a variety of directory operations:


{note {fn DIRECTORY} was written by L.M. Masinter.}



{FnDef {FnName DIRECTORY} {FnArgs FILES COMMANDS DEFAULTEXT DEFAULTVERS}
{Text
{arg FILES} is either [1] {lisp NIL} (which is equivalent to {lisp *.*;*}); or [2] an atom which can contain {lisp $}'s or {lisp *}'s (equivalent) which match any number of characters or {lisp ?}'s which match a single character, or else [3] {arg FILES} is a list of the form {lisp ({arg FILES} + {arg FILES})}, {lisp ({arg FILES} - {arg FILES})}, or {lisp ({arg FILES} * {arg FILES})},{foot
{lisp OR} can be used for {lisp +}, and {lisp AND} for {lisp*}.
}{comment endfootnote}
e.g., {lisp (T$ + $L)} will match with any file beginning with {lisp T} or ending in {lisp L}, {lisp (T$ - *.DCOM)} matches all files that begin with {lisp T} and are not {lisp .DCOM} files.
}}



For each file that matches, each command in {arg COMMANDS} is executed with the following interpretation:


{Begin LabeledList interpretation of DIRECTORY commands}

{Label {lisp P}}
{Item
Print file name.
}


{Label {lisp PP}}
{Item
Print file name (except for version number).
}


{Label a string}
{Item
Prints the string.
}


{Label {lisp READDATE}, {lisp WRITEDATE}, {lisp CREATIONDATE}}
{Label {lisp SIZE}, {lisp LENGTH}, {lisp BYTESIZE}}
{Label {lisp PROTECTION}, {lisp AUTHOR}, {lisp TYPE}}
{Item
Prints the appropriate information returned by {fn GETFILEINFO} ({PageRef Fn GETFILEINFO}).

{note the list FILEINFOTYPES provides additional formatting information to the DIRECTORY function}
}


{Label {lisp COLLECT}}
{Item
The value of {fn DIRECTORY} will be a list of file names; add the complete file name of this file to that list.
}


{Label {lisp COUNTSIZE}}
{Item
The value of {fn DIRECTORY} will be a sum; add the size of this file to that sum.
}


{Label {lisp PAUSE}}
{Item
Wait until the user types any char before proceeding with the rest of the commands (good for display if you want to ponder).
}


{Label {lisp PROMPT {arg MESS}}}
{Item
Prompts with {arg MESS}; if user responds with {lisp N}o, abort command processing for this file.
}


{Label {lisp OLDERTHAN {arg N}}}
{Item
Continue command processing if the file hasn't been referenced (read or written) in {arg N} days.
}


{Label {lisp OLDVERSIONS {arg N}}}
{Item
Continue command processing if there are at least {arg N} more recent versions of the same file.

{note note that this IS NOT IMPLEMENTED for TOPS20 and DIRECTORY will complain if you try to use it on a TOPS-20 system}
}


{Label {lisp BY {arg USER}}}
{Item
Continue command processing if the file was last written by the given user.
}


{Label {lisp @ {arg X}}}
{Item
{arg X} is either a function of one argument ({arg JFN}), a function of two arguments ({arg JFN} {arg FILENAME}) or an arbitrary expression which uses the variablers {lisp JFN} and/or the variables {lisp FILENAME} freely.  If {arg X} returns {lisp NIL}, abort command processing for this file.

{note it is a minor efficiency hack that if FILENAME is not used in the expression, it isn't computed}
}


{Label {lisp DELETED}}
{Item
Allows {fn DIRECTORY} to examine deleted files (normally, they are not mapped over.
}


{Label {lisp OUT {arg FILE}}}
{Item
Directs output to {arg FILE}.
}


{Label {lisp COLUMNS {arg N}}}
{Item
Attempt to format output in {arg N} columns (rather than just 1).
}


{Label {lisp TRIMTO {arg N}}}
{Item
Deletes all but {arg N} versions of file ({arg N}{GE}0).
}


{Label {lisp DELETE}}
{Item
Deletes file.  If this is specified, the value of {fn DIRECTORY} is {lisp NIL} if no {lisp COLLECT} command is specified, otherwise the list of files deleted.
}


{Label {lisp UNDELETE}}
{Item
Undeletes the indicated files that have been deleted.
}

{End LabeledList interpretation of DIRECTORY commands}


{fn DIRECTORY} uses {var DIRCOMMANDS}{index DIRCOMMANDS Var}{index spelling lists} to correct spelling, which also provides a way of defining abbreviations and synonyms ({PageRef Tag SpellingLists}).  Currently the following abbreviations are recognized:


{Begin LabeledList abbreviations}

{Indent 15percent}

{Label {lisp AU}}
{Item
{lisp =>    AUTHOR}
}

{Label {lisp -}}
{Item
{lisp =>    PAUSE}
}

{Label {lisp COLLECT?}}
{Item
{lisp =>    PROMPT " ? " COLLECT}
}

{Label {lisp DA}}
{Label {lisp TI}}
{Item
{lisp =>    WRITEDATE}
}


{Label {lisp DEL}}
{Item
{lisp =>    DELETE}
}


{Label {lisp DEL?}}
{Label {lisp DELETE?}}
{Item
{lisp =>    PROMPT " delete? " DELETE}
}

{Label {lisp OLD}}
{Item
{lisp =>    OLDERTHAN 90}
}


{Label {lisp PR}}
{Item
{lisp =>    PROTECTION}
}

{Label {lisp SI}}
{Item
{lisp =>    SIZE}
}

{End LabeledList abbreviations}


{FnDef {FnName FILDIR} {FnArgs FILEGROUP {anonarg}}
{Text
{arg FILEGROUP} is a file group descriptor, i.e., it can contain stars.
{fn FILDIR} returns a list of the files which match {arg FILEGROUP}, a la the {fn DIRECTORY} function, e.g., {lisp (FILDIR '*.COM;0)}.
}}



{index *PRIMARY* DIR PA}

There is also a programmer's assistant command {pacom DIR} which calls the function {fn DIRECTORY}:

{Def {Type PACom} {Name DIR} {Args FILES {lisp .} COMMANDS} {NoParens}
{Text
Calls the function {fn DIRECTORY} with {lisp (P . {arg COMMANDS})} as the command list and {lisp *} and {lisp *} as the default extension and default version respectively.
}}

For example, to {lisp DELVER} only those files which you ok, do
{lisp DIR {arg FILES} PROMPT "?" TRIMTO 1}.


{Begin Note}
Date: 19 NOV 1978 1550-PST
From: MASINTER

Fixed DIRECTORY to put back in the TRIMTO option (request from Vittal, as the OLDVERSIONS feature I had put in before did not work for TOPS-20. Note that several versions ago, I installed a new DIRECTORY package with several new features which I need to document -in particular, I moved over some of the things which were in EXEC where the cost of having them in the code was slight). Main important feature is that the DELETE and UNDELETE options of a DIR command are undoable; /DELFILE and /UNDELFILE are included in the system. 
{End Note}

{Begin Note}
Date: 3 Dec 1978 3:57 pm (Sunday)
From: Masinter
Subject: new DIR features

a couple of weeks (months?) ago, I installed a new version of the DIRECTORY package, with a couple of things cleaned up. This version has been stable long enough that I am now documenting the new features.

...


Also as part of the DIRECTORY package, the functions

/delfile[filename]	delete filename (undoably).
undelfile[filename]	undelete filename
/undelfile[filename]	undelete filename (undoably)

are provided. At type-in, delfile is converted to /delfile.
{End Note}


}{End SubSec Manipulating File Directories}