Stroika::Foundation::DataExchange::OptionsFile Class Reference

#include <OptionsFile.h>

Public Types
enum class	ReadFlags
using	ModuleNameToFileVersionMapperType = function< optional< Common::Version >(const String &moduleName)>
using	ModuleDataUpgraderType = function< VariantValue(const optional< Common::Version > &version, const VariantValue &rawVariantValue)>

Public Member Functions
nonvirtual BLOB	ReadRaw () const
nonvirtual void	WriteRaw (const BLOB &blob)
template<typename T >
nonvirtual optional< T >	Read ()
template<typename T >
nonvirtual void	Write (const T &optionsObject)

Static Public Attributes
static const LoggerType	kDefaultLogger
static const ModuleDataUpgraderType	kDefaultUpgrader
static const Variant::Reader	kDefaultReader = Variant::JSON::Reader{}
static const Variant::Writer	kDefaultWriter = Variant::JSON::Writer{}

Detailed Description

Simple wrapper on ObjectVariantMapper code, and code to serialize to/from JSON/XML etc, to wrap all this into an easy to use (but configurable/customizable) helper to serialize configuration data between disk and module-specific C++ objects.

This is SOMEWHAT flexible and customizable, but not so much. Its mostly intended to be a one-size-fits all utility that will often be useful, and will save some typing. If it does fit your needs, don't use it, and use ObjectVariantMapper and the reader abstractions directly.

Example Usage

struct  MyData_ {
    bool                 fEnabled = false;
    optional<DateTime>   fLastSynchronizedAt;
};
// Execution::Logger::Activator logMgrActivator;    // be sure a line like this in Main before the 'of' object usage
OptionsFile of {
    "MyModule",
    [] () -> ObjectVariantMapper {
        ObjectVariantMapper mapper;
        mapper.AddClass<MyData_> (initializer_list<StructFieldInfo> {
            { "Enabled"sv, &MyData_::fEnabled },
            { "Last-Synchronized-At"sv, &MyData_::fLastSynchronizedAt },
        });
        return mapper;
    } (),
    OptionsFile::kDefaultUpgrader,
    [] (const String & moduleName, const String & fileSuffix) -> String {
        return  IO::FileSystem::WellKnownLocations::GetTemporary () + moduleName;
    }
};
MyData_ m = of.Read<MyData_> (MyData_{});  // will return default values if file not present
of.Write (m);                              // test writing

Definition at line 79 of file OptionsFile.h.

Member Typedef Documentation

ModuleNameToFileVersionMapperType

using Stroika::Foundation::DataExchange::OptionsFile::ModuleNameToFileVersionMapperType = function<optional<Common::Version> (const String& moduleName)>

Optionally provide (based on filenames/locations) information about the incoming file(read file) version.

Definition at line 112 of file OptionsFile.h.

ModuleDataUpgraderType

using Stroika::Foundation::DataExchange::OptionsFile::ModuleDataUpgraderType = function<VariantValue (const optional<Common::Version>& version, const VariantValue& rawVariantValue)>

This function gets a crack at revising the form (in variant/tree form) of the data to accomodate a version change. The version may not be known, in which case the function is still called, but with the verison information missing.

Definition at line 125 of file OptionsFile.h.

Member Enumeration Documentation

ReadFlags

enum class Stroika::Foundation::DataExchange::OptionsFile::ReadFlags

strong

Just a parameter to Read() function.

Definition at line 178 of file OptionsFile.h.

Member Function Documentation

ReadRaw()

BLOB OptionsFile::ReadRaw

(

)

const

Read the content of the associated file as a BLOB.

Definition at line 183 of file OptionsFile.cpp.

WriteRaw()

void OptionsFile::WriteRaw

(

const BLOB &

blob

)

Writes the given blob to the associated file, if it represents a change. This will silently avoid writing, if the blob is already the same as what is on disk.

Definition at line 189 of file OptionsFile.cpp.

Read()

template<typename T >

nonvirtual optional< T > Stroika::Foundation::DataExchange::OptionsFile::Read

(

)

Read () reads in the data from the associated options file, and returns it as a struct you've defined.

The mapping to/from external format is defined by OptionsFile constructor parameters.

The predefined (template specialization) of Read<VariantValue> doesn't use ObjectVariantMapper: it does the raw read (just using the Reader object).

Note also that Read<VariantValue> does use any provided ModuleDataUpgrader, so that the data is upgraded before its seen by the object variant mapper.

Read () will emit warnings, and maps to 'isMissing' or default value (depending on overload) if read data is corrupted. To avoid this behavior, use ReadRaw() directly.

Write()

template<typename T >

nonvirtual void Stroika::Foundation::DataExchange::OptionsFile::Write

(

const T &

optionsObject

)

Note - predefined version Write<VariantValue> doesn't use ObjectVariantMapper.

Write () serializes T, and then invokes WriteRaw ().

Note

WriteRaw () - and so Write () makes no changes to the external file if the contents being written serialize to the same value.

Member Data Documentation

kDefaultLogger

const OptionsFile::LoggerType OptionsFile::kDefaultLogger

static

Initial value:

= [] (const LoggerMessage& message) {
    using Execution::Logger;
    Logger::Priority priority = Logger::eError;
    using Msg                 = OptionsFile::LoggerMessage::Msg;
    switch (message.fMsg) {
        case Msg::eSuccessfullyReadFile:
            priority = Logger::eInfo;
            break;
        case Msg::eFailedToReadFile:
            priority = Logger::eWarning; 
            break;
        case Msg::eWritingConfigFile_SoDefaultsEditable:
        case Msg::eWritingConfigFile_BecauseUpgraded:
        case Msg::eWritingConfigFile_BecauseSomethingChanged:
            priority = Logger::eInfo;
            break;
 
        case Msg::eFailedToParseReadFile:
        case Msg::eFailedToParseReadFileBadFormat:
            
            priority = Logger::eCriticalError;
            break;
    }
    Logger::sThe.Log (priority, "{}"_f, message.FormatMessage ());
}

Note

- Since this uses Execution::Logger::sThe, if therefore requires use of Execution::Logger::Activator logMgrActivator

Definition at line 95 of file OptionsFile.h.

kDefaultUpgrader

const OptionsFile::ModuleDataUpgraderType OptionsFile::kDefaultUpgrader

static

Initial value:

=
    [] (const optional<Common::Version>& , const VariantValue& rawVariantValue) -> VariantValue { return rawVariantValue; }

kDefaultUpgrader does nothing (no-op)

Definition at line 131 of file OptionsFile.h.

kDefaultReader

const Variant::Reader OptionsFile::kDefaultReader = Variant::JSON::Reader{}

static

Format serializer

Definition at line 137 of file OptionsFile.h.

kDefaultWriter

const Variant::Writer OptionsFile::kDefaultWriter = Variant::JSON::Writer{}

static

Format serializer

Definition at line 143 of file OptionsFile.h.

---

The documentation for this class was generated from the following files:

• OptionsFile.h
• OptionsFile.cpp
• OptionsFile.inl