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

The function {fn DIRECTORY} 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
Returns, lists, or performs arbitrary operations on all files specified by the "file group" {arg FILES}.{index File Group}  A file group has the form of a regular file name, except that the character {lisp *}{index * (In File Group)} can be used to match any number of characters in the file name.  For example, the file group {lisp A*B} matches all file names beginning with the character {lisp A} and ending with the character {lisp B}.  The file group {lisp *.DCOM} matches all files with an extension of {lisp DCOM}.

Unspecified fields in the file group default to {lisp *}, except when the preceding field delimiter is included, in which case the field is explicitly null.  Null version is interpreted as "highest".  Thus:  {arg FILES} = {lisp *} or {lisp *.*} or {lisp *.*;*} enumerates all files; {arg FILES} = {lisp *.} or {lisp *.;*} enumerates all versions of files with null extension; {arg FILES} = {lisp *.;} enumerates the highest version of files with null extension; and {arg FILES} = {lisp *.*;} enumerates the highest version of all files.  If {arg FILES} is {lisp NIL}, it defaults to {lisp *.*;*}.

Note: Some hosts/devices are not capable of supporting "highest version" in enumeration.  Such hosts instead enumerate ALL versions.


For each file that matches the file group {arg FILES}, the "file commands" in {arg COMMANDS} are executed in order.  Some of the file commands allow aborting the command processing for a given file.  This can be used to further screen the files.  The interpretation of the different file commands is described below.  If {arg COMMANDS} is {lisp NIL}, it defaults to {lisp (COLLECT)}, which collects the matching file names in a list and returns it as the value of {fn DIRECTORY}.
}}

The "file commands" in {arg COMANDS} are interpreted as follows:

{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 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 FILENAME}), or an arbitrary expression which uses the variable {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 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 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.
}


{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}
{Text
{arg FILEGROUP} is a file group descriptor, i.e., it can contain the character {lisp *} to match any number of characters.  {fn FILDIR} returns a list of the files which match {arg FILEGROUP}, like 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.
}}

{Def {Type PACom} {Name NDIR} {Args FILES {lisp .} COMMANDS} {NoParens}
{Text
Version of {lisp DIR} which lists the file names in a multi-column format.  Also, by default only lists the most recent version of files.
}}


}{End SubSec Manipulating File Directories}