README

ttvfs -- tiny tree virtual file system

----------[ TL;DR ]------------
** Modify VFSDefines.h to your needs, or set the defines in your build system.
** See the examples for reference. Documentation is in the header files.
** #include <ttvfs.h>
** ???
** Profit
** You are encouraged to link this library statically.
** Supported and tested: Windows, Linux, MacOSX, FreeBSD, Haiku (maybe), POSIX.

----------[ Intro ]------------
ttvfs is a small C++ library designed to provide virtual file system support
inside of an application.

ttvfs provides some commonly used platform-dependent operations such as
enumerating files and directories, querying the size of files efficiently,
obtaining safe-to-write per-user directories, support for wildcards,
ignore case on otherwise case-sensitive file systems, and more.

ttvfs organizes files and directories in a tree structure.
By mounting, multiple directories can be mirrored inside one,
making runtime-replacing older files with updated ones trivial.

With the built-in zip extension, zip files can be accessed like directories:
    path/to/data.zip/file.txt.

Other archives are not supported out of the box, but it is easy to add
an extension that provides support for other archive types.
By adding custom file loaders, it is possible to load files from anywhere,
not only the local file system.

This library is licensed under the MIT license (see below).
If you use this code and like it, feel free to send me an email to
googlemail.com with false.genesis@ prepended.
- that'd make me happy.
Patches/improvements are welcome!

----------[ Howto ]------------

Build project/makefiles with CMake. It has sort of sane defaults so it should
build out of the box.
Some compile flags can be set with CMake, or simply by editing VFSDefines.h.

$ mkdir build
$ cd build
$ cmake ..
$ make

ttvfs core has no dependencies except the STL containers.
See VFSFile.h, VFSDir.h, VFSLoader.h for infos about how to write your own
classes that add functionality.
The zip extension uses miniz (https://code.google.com/p/miniz/) and should be
a good reference how to write your own extension.
To add ttvfs to your project, just copy the ttvfs/ subdir,
which is the best way in case you are using CMake; if not, copy all files
and add them to your build system of choice, or whatever.

Note that ttvfs is not thread safe - adding this would bloat it too much.
You probably have your own threading library if you care about thread safety.
The rules are simple:
* There is no global state, but be careful with ttvfs::Root objects.
* Do not access a ttvfs::Root object from multiple threads at the same time,
  even for reading. The tree is possibly modified by read operations.
* Same for individual ttvfs directory and file objects.

There is also no explicit support for UTF8. This may be a problem if
case insensitivity is enabled and file names are compared.
This can be avoided by either leaving case insensitivity disabled,
or by making sure that all relevant files have ASCII-only names.


------- [ Extensions ]--------

* liblvpa: https://github.com/fgenesis/liblvpa
-> contains bindings that add support for reading/writing LVPA files
   (a container file format optimized for games)


Made an extension? Let me know, send a mail!

---------[ License ]----------

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.


-------------------------------