ImpPath Files

--------------------------
- 1. LIBRARY DESCRIPTION -
--------------------------

Imp::Path is a simple library for path manipulation.

Works with std::string and std::wstring.

Configurable (since v2.0), can support various path formats (e.g. POSIX and Windows with some limitations for simplicity).
Change IMP_PATH_CONFIG_HEADER macro in imp_path.h to choose one of the provided configurations, or write one yourself.

All configurations understand ".." (parent directory) and "." (current directory).
All characters except directory separators and absolute-path start sequences
are treated as parts of file/directory names. No checks are made for characters not valid in a path.

Never tries to access any real file system, and thus does not know anything about symbolic links.

Detailed interface description is provided as comments inside imp_path_impl.h.

Originally created as an internal part of IMP Framework project (still in development for now).

Latest version: 2.0 (13.09.2013)
Website: http:sourceforge.net/projects/imppath/
Author: Andrey Antsut (aka Kirinyale)

-------------------------------
- 2. AVAILABLE CONFIGURATIONS -
-------------------------------

Available configuration headers (for use in IMP_PATH_CONFIG_HEADER macro in imp_path.h):

1) imp_path_config_default_posix.h

Simple POSIX paths: forward slashes only, absolute paths start with a slash.
Identical to v1.1 behavior, except one bug fix (see version history above).

2) imp_path_config_default_posix_with_base.h

Same as 1), but additionally supports "base-relative" paths,
which are considered absolute (see their description in the next section).

3) imp_path_config_default_sandbox.h

Same as 2), but ONLY base-relative paths are considered absolute.

4) imp_path_config_default_win32.h

MS Windows paths with drive letters support, but no schemas, network paths etc.
Support both backslashes and forward slashes. Backslashes are preferred.
Absolute paths must start with any single character folowed with a colon (':'),
then at least one slash of any kind, OR end of line.
E.g. "c:", "c:\\", "c:/", "c:\\foo" "c:/foo" are absolute paths,
and "c:foo" is not (it's actually invalid, but considered relative by this library).
Paths like "file:///something", "http://www.example.com", "\\netpc\shared_dir" etc
are not supported and considered relative.

5) imp_path_config_default_win32_with_base.h

Same as 4), but additionally supports "base-relative" paths,
which are considered absolute (see their description in the next section).

--------------------------
- 3. BASE-RELATIVE PATHS -
--------------------------

RATIONALE.

This library was primarily designed for usage in a secure environment with known simple limitations.
For example, for working with internal application resource paths referencing
a "sandboxed" virtual filesystem (like with PhysicsFS - http://icculus.org/physfs/).
Still, there are situations when it must deal with native paths outside the sandbox as well.
For example, when an editor application shares the common code base with a game, 
the editor will work within a platform-specific file system, and the game will stick to its PhysFS sandbox.

Thus, to be able to correctly share some paths between the editor and the game, we need a way to mark
specific paths as being relative to the game's sandbox root. Without this, for example,
path string "/res/image.png" will have different meanings under the game and an editor running on *nix:
even though the editor might know exactly where the game's sandbox is located,
it still has to support "real" absolute paths, and would have no way of distinguishing them
from the paths shared with the game, which are actually relative to the sandbox root.

SOLUTION.

In all configurations with "base-relative" path support, any path starting with a colon (':'),
followed by a directory separator (e.g. slash) of any supported kind, or by the end of line,
is considered absolute. The calling application must preprocess such paths on its own,
e.g. remove the colon or replace it with a real absolute path to a known "base".

When forcing a relative path to become absolute (see toAbsolute() and absolute() functions),
":/" prefix is preferred over the native absolute path format.
E.g. with "POSIX with base" config absolute("foo") will return ":/foo",
while with normal POSIX it would be "/foo".

Of course, you can change the default base character (':') to anything else by slightly modifying
the config files (namely, absPrefixLen and defAbsPrefix functions).
You can even support more than one possible base characters - e.g. if you need one for sandbox root,
and another for embedded named resources not dependent on any file system.

RECOMMENDED CONFIGURATIONS.

imp_path_config_default_sandbox.h              - for a game using PhysicsFS library for file access.
imp_path_config_default_<PLATFORM>_with_base.h - for an editor sharing any resource paths with the game engine.
imp_path_config_default_<PLATFORM>.h           - for standalone applications which do not require sandboxing of any kind.

--------------
- 4. LICENSE -
--------------

zLib license:

 This software is provided 'as-is', without any express or implied
 warranty.  In no event will the authors be held liable for any damages
 arising from the use of this software.

 Permission is granted to anyone to use this software for any purpose,
 including commercial applications, and to alter it and redistribute it
 freely, subject to the following restrictions:

 1. The origin of this software must not be misrepresented; you must not
    claim that you wrote the original software. If you use this software
    in a product, an acknowledgment in the product documentation would be
    appreciated but is not required.
 2. Altered source versions must be plainly marked as such, and must not be
    misrepresented as being the original software.
 3. This notice may not be removed or altered from any source distribution.
 
-----------------
- 5. CHANGELIST -
-----------------

Version 2.0 (13 September 2013):

- Added different configurations support.
- Added resolve function.
- Fixed a bug with normalize("a/") under POSIX config.
- Removed duplicate source folder with Russian comments.
  Instead, both languages are now present in all imp_path.h comments.

Version 1.1 (28 July 2012):

- Added parentPath function.
- Renamed extension manipulation functions.
- Added new functions for last extension manipulation.
- Added author's name and license text into the main header file.

Version 1.0.1 (22 July 2012):

- Added std::wstring support.

Version 1.0 (21 July 2012):

- Supported only std::string.
- No configurations. POSIX paths only.