The XB file template simplifies handling of "real world" XB files. It provides an abstraction of a file into a xb::document. The template must be instantiated with one of available policies. This policy defines how is the actual file treated.
namespace xb {
template <typename POLICY = read_write>
class file {
public:
explicit file (const std::string &, const xb::codec & = xb::null_codec);
explicit file (const std::wstring &, const xb::codec & = xb::null_codec);
~file () throw ();
private:
file (const file &);
file & operator = (const file &);
public:
using POLICY::operator [];
public:
void set_dtor_failure_flag (bool *) throw ();
};
// policies for xb::file
class read_write {
public:
xb::document & document;
public:
void commit ();
void commit_to (const std::string &);
void commit_to (const std::wstring &);
void set_codec (const xb::codec &);
public:
const xb::node & operator [] (const xb::element & e) const;
xb::node & operator [] (const xb::element & e);
};
class read_only {
public:
const xb::document & document;
public:
const xb::node & operator [] (const xb::element & e) const;
};
class new_file : public read_write {
// no new public members introduced
};
class read_header_only : public read_only {
// no new public members introduced
};
};
The xb::file constructor has only one parameter, the file name. The file name can be provided as both ANSI and UNICODE string. Note that the file may remain inaccessible while the xb::file object exists. The exact behavior depends on policy used.
Provide reference to a codec in the second parameter of the constructor, if you expect the file being opened to be encoded. If the file is not encoded, the codec is ignored. If different codec has been used to encode the file or the codec failed to decode it, the std::runtime_error exception is thrown.
Note that xb::file is not copy-constructible nor assignable for obvious reasons.
The std::runtime_error exception is throw when the file cannot be opened.
The .commit () member function is available only when instantiated with xb::read_write or xb::new_file policy. The member function updates the opened file with current content of the .document. If the xb::codec object is passed as the parameter it is used to encode whole document acording to rules described in definition.
The std::runtime_error or std::bad_alloc exceptions may be thrown
by this member function on error.
The .commit_to () member function effectively implements the "Save as..." functionality for the xb::file. The first function parameter is the new name for the file, the second (optional) parameter is an xb::codec object that is passed to the .commit () member function after the xb::file target is renamed.
The old file is not changed nor deleted when using this member function.
The .operator [] member function provides an simplified access to .document nodes.
When an xb::file <xb::read_write> (or xb::file <> only) object is created, the file is parsed into .document member.
When an xb::file <xb::read_only> object is created, the file is parsed into .document member. Note that documents opened using this policy cannot be updated.
The xb::file <xb::new_file> behavior is very similar as if the xb::read_write policy would be used, but the file is initialy empty. If no file of given name exists, an empty file is created. If the file already exists, it is truncated to size of zero.
Using the xb::file <xb::read_header_only>, the file is opened for reading only and no document data is loaded. Only header node is parsed (if any). This way you can determine the version and codec information without the need to load whole file.
// ...
try {
xb::file <xb::read_only> setup ("setup.xb");
// ... would read data from setup file here
} catch (const std::runtime_error &) {
// failed to open setup file
};
// ...
try {
xb::file <> database ("database.xb");
// ... read from and update database here
database [key] = value;
// write data to disk
try {
database.commit ();
} catch (const std::runtime_error &) {
// failed to update database file
};
// ...
} catch (const std::runtime_error &) {
// failed to open database file
};
// ...
None.
[index]