Resources vs. PhysFS
====================

PhysFS is a small library available at:

http://icculus.org/physfs/

Its a small C library that is in some parts similar to
CL_ResourceManager or CL_InputSource, however it apears to be quite a
bit cleaner and more powerfull in some aspects. See also the resource
caching rfc. The following rfc should give some details on what PhysFS
can do that Clanlib can't and visa verse.

File Handling: CL_InputSource/CL_OutputSource vs. PHYSFS_file[1]
================================================================

Both ClanLIb and PhysFS provide access to files, provide functions to
read, write, seek in a file. Both libraries appear to provide more or
less the same features here.

Directory Handling
==================

Directory creation, deletion and browsing is doable in physfs via:

PHYSFS_delete
PHYSFS_mkdir
PHYSFS_enumerateFiles
PHYSFS_addToSearchPath
etc.

Mounting of Zip files and normal directories into a virtual file
system is possible. Its also possible to restrict write access to a
single directory, thus making it impossible to escape from in-game
scripts. Directory access is portable and doesn't rely on system
specific convention (directory seperator and such) beside from in the
call that mounts the directory/zip.

ClanLib provides directory manipulation via CL_Directory and
CL_DirectoryScanner, zip file access is done via CL_Zip_Archive, the
interface to all these classes doesn't have much in common, mounting
directory trees or zip files isn't possible, neither is limiting the
write access. Differences in pathnames aren't hidden across platforms
and some functions don't even perform portable:

Win32: DirectoryScanner::scan("foo/", "*.*");

vs

Linux: DirectoryScanner::scan("foo/", "*");

CL_ResourceManager
==================

CL_ResourceManager provides a way to abstract the filesystem, but
instead of giving an abstracted, but still file based view on the
system, it requires a .xml file which specifies all object in the
filesystem and then gives only access to 'objects', not raw files.
Object in this context are ClanLib objects, such as sprites, surfaces,
sound files, etc. 

In addition to just converting a .png to a CL_Surface the resource
file allows in attition to that to specify data that the file itself
does not contain, such as the are of a .png that should be used, which
frames belong to which sprite and such.

Support for 'mounting' directories or batch conversion of file objects
to resource objects is missing, ie. something like:

<include name="$file.$ext" pattern="images/*.png" type="surface" />

Might be helpfull.

Proposal
========

Add proper directory handling to ClanLib, unify normal directory and
zip file access and thus allow to create a special directory class
that allows mounting of other directories. The following classes are
just a very very rought draft, corrections, additions and comments are
welcome:

class CL_Directory
{
public:
  // Return a iterator to the begin of the directory
  iterator begin();
  // Return a iterator to the end of the directory
  iterator end();
  // Return the name of the current entry
  CL_DirectoryEntry& operator*();
};

// Class for accessing the systems native filesytem
class CL_SystemFileSystem
{
public:
  CL_Directory open_directory(std::string name);
};

class CL_ZipFileSystem
{
public:
  CL_ZipFileSystem(CL_InputSource in);
  CL_Directory open_directory(std::string name);   

  // save the zipfile
  void save();
};

class CL_VirtualFileSystem
{
public:
  CL_Directory open_directory(std::string name);  

  CL_InputSource  open_write(std::string pathname);
  CL_OutputSource open_read(std::string pathname);

  void mount(std::string path, CL_FileSystem fs);
  void unmount(std::string path);
  void unmount(CL_FileSystem fs);
};

class CL_DirectoryEntry
{
public:
  std::string  get_name();
  unsigned int get_mtime();

  bool is_directory();
  bool is_file();
  bool is_symlink();

  CL_InputSource  open_write();
  CL_OutputSource open_read();
};


[1] http://icculus.org/physfs/docs/html/structPHYSFS__file.html

# EOF #