ODS File System
---------------

Although the Object Data Storage (ODS) DB has been designed to provide minimal and high speed C++ persistence
it does suffer from the lack of any simple means to explore or edit persistent data. It's for this reason the
ODS File System was developed with the "ods_fsed" target being a simple console application for exploring and
editing persistent data.

File System Overview
--------------------

A familiar file and folder approach is used and folders can be nested in a directed acyclic graph in the same
manner as typical OS file systems do. A forward slash character is the folder separator and the "root" folder
is "/". It should be noted that "ods_file_system" is not thread-safe and instances must not be shared between
threads, however as locking occurs around each and every ODS DB operation it is no problem for many different
threads to be using the same underlying ODS DB (just ensure that each has its own "ods_file_system" object).

Although using "ods_fsed" you can add, move or remove both files and folders it is not recommended to perform
changes to a DB unless you really understand how it is being used by its owning application (assuming that it
has one). If you run "ods_fsed" without the optional "name" argument then it will operate with its own simple
DB which can be changed any way you like (but note that the regression tests will destroy any changes made as
this default DB is used for the "test_ods_fsed" test group).

Using the ODS FS explorer/editor
--------------------------------

The simple console application "ods_fsed" provides those familiar with console applications a fairly familiar
experience. When started a prompt that includes the current folder (being "/" for the root folder which it is
always at first) will appear. To see a list of the files in the root folder one would issue the following:

/> files

And to see the list of folders immediately below the root folder you would use this:

/> folders

To see both the files and folders together in a single list use the following:

/> objects

And in order to view all files, folders or objects below the current folder for every level below the current
folder use the "branch" command as per the following three examples:

/> branch files

/> branch folders

/> branch objects

For all of these commands an optional wildcard expression can be provided in a manner similar to the way such
wildcard expressions are handled for shell commands like "ls". Such expressions can use "?" to match a single
character or "*" to match zero or more characters. The following would display all files in the entire folder
structure that contain the string "test":

/> branch files *test*

To change the current folder use the command "cd" and note that you can use ".." (or "../..", etc.) at (only)
the start of the folder name to mean "parent folder" . Assuming the current folder is "/xxx" and one wants to
change it to "/yyy" then this can be achieved by either of the following two commands:

/xxx> cd /yyy

/xxx> cd ../yyy

Of course you can change to the root folder at any time using the following:

/xxx/yyy/zzz> cd /

Creating a folder below the current folder is as simple as the following:

/> folder_add xxx

It should be noted that a valid folder name cannot include various special characters (including "/", "<" and
">" amongst others) in order to make them compatible with other operating systems (as the "export" command is
used to export the branch below the current folder to an OS directory).

Assuming folders "xxx" and "yyy" both were children of the root folder then to move "yyy" below "xxx" is what
the following command would do:

/> folder_move yyy xxx

If you wanted to move "yyy" back below the root folder then that could be performed in either of these ways:

/xxx> folder_move yyy ..

/xxx> folder_move yyy /

To remove a folder that exists below the current folder is as follows:

/> folder_remove yyy

Assuming the current folder contains the file "ciyam_server.sio" then it can be easily added into this folder
with the following command:

/> file_add ciyam_server.sio

If you wanted it to instead be called "config" in the ODS FS then use the following:

/> file_add config ciyam_server.sio

Or if it had already been added incorrectly then simply rename it with "file_move" as follows:

/> file_move ciyam_server.sio config

It is also possible to manually type in text file content via the following:

/> file_add config -c
Enter multi-line content followed by a line with just a single dot (.) to finish:
This is a test.
.

If you wished to retrieve this file into the current OS file directory use the following:

/> file_get config

Moving a file to another folder is easily performed as follows:

/> file_move config xxx

And removing a file from the current folder or below it is also easily done as follows:

/> file_remove xxx/config

The ODS FS also supports a special form of file "linking" which allows for different names that can be placed
in different folders to all reference a single file.

/xxx> file_link config /ciyam_server.sio

Performing a "file_get" on such a file link will retrieve the exact same content as the source file that it's
linked to (but only one copy of the file content itself is being stored in the DB). If the link is removed it
has no effect upon the source file, however, if the source file is removed then any links to it are removed.

The "file_replace" command allows the content of a file to be replaced with different content (but the actual
OID of the file does not change). In particular this can be useful when file links are being used (as they're
automatically now linked to the new file content).

The "export" command allows the entire ODS FS structure (i.e. files and folders) to be replicated in the host
OS file system (except "link" files which are currently just being omitted).

Using the ODS FS in code
------------------------

All of the "ods_fsed" RPC calls are handled via the "ods_file_system" object methods and therefore can easily
be reproduced in code. A few extra methods have been created more specifically for code usage in applications
and they are as follows:

"store_file" - this method will either call "add_file" or "replace_file" depending upon whether or not a file
with the same name already exists.

"store_as_text_file" - provides some function overloads to simply store values as text files.
"fetch_from_text_file" - provides complimentary overloads to simply fetch values from text files.

As the application server uses the ODS FS for storing various settings you can use "ods_fsed" in order to see
an example of it in use (e.g. "ods_fsed Meta").