-- 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.
		
}.