-- DFUser.Mesa, last edit February 9, 1983 11:31 am
-- interface to users of procedures that enumerate DF files

-- exported by DFSubrImpl, which is bound in DFUserImpl.Config

  DIRECTORY
  DFSubr: TYPE USING[DFSeq],
  IO: TYPE USING[Handle],
  Rope: TYPE USING[ROPE];
  
DFUser: DEFINITIONS = {

-- the user supplies a procedure with this type to be called, once
-- per file in the tree of DF files.
-- the user can then manipulate these arguments.
-- these strings are not reused, so they may be safely assigned without
-- copying their contents. Their memory is freed when DFUser.CleanupEnumerate[] is called.
--
-- parameters:
-- host  e.g. "Indigo"
-- directory e.g. "Cedar>Top"
-- shortName e.g. "Editor.Bcd"
-- version  e.g. 2
-- createTime e.g. 23-Mar-82 15:33:21
-- includedDFFile is true if this is a DF file being Included
-- importedDFFile is true if this is a DF file being Imported
-- readOnly is true if the file is "ReadOnly" or is an Import to this DF
-- immediateParentDF is the shortName of the DF file that contains this entry
-- internalDFSeq is the pointer to internal data
--
EnumerateProcType: TYPE = PROC[host, directory, shortName: LONG STRING,
 version: CARDINAL, createTime: LONG CARDINAL,
 includedDFFile, importedDFFile, readOnly: BOOL, immediateParentDF: LONG STRING,
 internalDFSeq: DFSubr.DFSeq];
 

SortOption: TYPE = {notSorted, byShortName, byLongName};

-- the user calls this procedure to have his procedure be called
-- the parameters are:
--  dfFileName: the DF file that is the root, e.g. "[Indigo]<Cedar>Top>PilotKernel.DF!33"
--   names without a host and directory are ok, then gets from local disk
-- nEntriesInDFFiles: the total number of entries in the tree of Df's descendent
--       from dfFileName
-- confirmBeforeOverwriting: ask user to confirm before retrieving a different version
--       of a DF file
-- printProgressMessages: print "Reading ..." messages giving info on where it is
-- procToCall: the proc to call with each file
--  sortOption: notSorted, means don't sort the entries
--   byShortName means sort on short name (e.g. BcdDefs.Mesa comes before Convert)
--   byLongName means sort on long name including host and directory
--    e.g. Indigo comes before Ivy, etc.
--  tryDollars:  if true then the DF files retrieved will be renamed (by adding '$$' to their
--      names) if there is a local copy of the Df file with a different create date
--  in is the stream used to read from. If not an edited stream, I will create one
--   from in and out
--
--  out is the stream used to print on
--
--  Confirm will be called with the in and out streams and a default letter.
--   It should return a letter in ('a, 'n, 'q, 'y) for the (all, no, quit, yest) question asked
--   by BringOver (there is an example in BringOverExecImpl)

EnumerateEntries: PROC[dfFileName: LONG STRING, procToCall: EnumerateProcType,
 nEntriesInDFFiles: CARDINAL ← 1000, confirmBeforeOverwriting: BOOL ← TRUE,
 printProgressMessages: BOOL ← FALSE,
 sortOption: SortOption ← notSorted, tryDollars: BOOL ← FALSE,
 in, out: IO.Handle,
 confirmData: REF ANY,
 Confirm: PROC[in, out: IO.Handle, data: REF ANY, msg: Rope.ROPE, dch: CHAR]
  RETURNS[CHAR]];


-- note: the current implementation reads the entire DF tree, and then calls the
-- client's procToCall for each file.

TooManyEntries: ERROR; -- raised by EnumerateEntries when nEntriesInDFFiles is too small


CleanupEnumerate: PROC; -- call to free all the memory used by EnumerateEntries
  -- after calling, all strings passed to you are invalid
  -- and will yield address faults.
  
}.