[Alephmodular-devel] TS Draft: File abstraction

[Br'fin <br...@ma...>]

I've been trying to resist the urge to just get in and tussle with  
portable_files.h If I'm going to ask Woody to try and document stuff, I  
should hold myself accountable too.

Is this too much overhead for our backwoods project? No idea. On the  
other hand, you do get to see some of my thinking before I commit it to  
the source tree. And I get to do my thinking before hand instead of  
waffling over where to put a detail after the fact.

Let's see if we can keep me doing it.

-Jeremy Parsons

Here is my current thinking on redoing portable_files.h Now is it too  
high or low a system? On one hand, it's fairly straight forward. It  
opens and closes files. It reads files. And with most system with a c  
stdio library, some of it is downright lazy/lame. On the other hand, it  
  is one of the bones I have to pick with AlephOne.

Also there is waffle room.
To me FILE_DESC_FACTORY->ConstructFileDesc(CFileDesc *directory,  
FileName) seems no better or worse than CFileDesc *foo =  
myCFileDesc->ConstructFileDesc(FileNameToAdd) So I'd not mind some  
feedback on the issue. And while I can see doing everything within  
CFileDesc (Using the class in many/all of the circumstances where I'm  
using the factory) It doesn't seem like the right thing to do.


And finally, here's the draft:

Technical Specification: File Hardware Abstraction

First there was portable_files.h and it was good in concept. But there  
was only a Macintosh implementation. And even so, there was an evident  
bios in the structure towards the Macintosh.

Please note that this does not handle file browsing. That is in the  
realm of the GUI.


Platform specific stuff can use the platform specific CFileDesc  
constructor.
IE Mac would wave CMacFileDesc(FSSpec&)

But in order to naviagte, you can't use CFileDesc(...) You would need  
to use a factory to build up the CFileDesc... ala

CFileDesc *foo = FILE_DESC_FACTORY->ConstructFileDesc(CFileDesc  
*directory, "file");
...
delete foo;

The factory is also the most reasonable place to provide access to  
CFileDescs for specific platform specific places. Ala preferences  
directory and application directory

CFileDesc *foo =  
FILE_DESC_FACTORY- 
 >GetSpecificDir(CFileDescFactory::ApplicationsDirectory);
// It is an error to delete this foo

Specific directories so far are
	ApplicationDirectory - The directory the application has been run from
			(Current dir if command line, directory of application executable  
otherwise)
	PreferencesDirectory
	

CFileDesc represents a file's location.
Under Unix, this would be the full path to a file. Under Macintosh this  
is akin to a FSSpec. Most typically it refers to a parent directory and  
knows the name of its file within that directory.
Most notably this has functions for creating the specified file,  
opening the file for reading, or opening the file for writing.

A given platform specific derivative should accept platform native file  
specifications. (For interfacing with native file browsers)

Operations include
	create_file
	open_file_for_reading (Returns CFileRef)
	open_file_for_writing (Returns CFileRef)
	delete_file


CFileRef represents an open file

Operations include
	get_fpos
	set_fpos
	set_eof
	get_file_length
	read_file
	write_file
	close_file