root/trunk/doost/util/serializer/Serializer.d

/*******************************************************************************

    License:    Boost Software License, v. 1.0
                Academic Free License, v. 3.0
                BSD License

    Authors:    Marcin Kuszczak, www.zapytajmnie.com (author's christian site)

    Version:    0.9.1
    Date:       30-Apr-2008

    History:    0.9.1 (30-Apr-2008) -   initial public version

 ******************************************************************************/

module doost.util.serializer.Serializer;

import doost.util.serializer.Exception;

import std.traits;
import doost.api.Common;
import doost.core.Traits;
import doost.storage.Storage;
import doost.util.serializer.Registry;


//------------------------------------------------------------------------------

/*******************************************************************************
 ******************************************************************************/
template Serializable() {
    void describeUdt(T)(T arch) {
        foreach(i, v; this.tupleof)
            //BUG: v nie jest przekazywane przez referencję? nie moÅŒna wstawić zamiast this.tupleof[i] - v
            //BUG: below will and all operations on v or this.tupleof[i] will fail
            //writefln(v.stringof);
            arch.describe(this.tupleof[i], this.tupleof[i].stringof);
    }
}

/*******************************************************************************
        Below templates are hacks for use with static arrays
 ******************************************************************************/
private void checkType(T : U[N], U, size_t N)(U[] arr) {
    if (arr.length>N)
        throw new SerializerException("Length of parsed array exeedes static array bounds.");
}

private void checkType(T)(T val) {
}

/*******************************************************************************
 ******************************************************************************/
enum Tracking {ON, OFF};
//FIXME: Archive powinno mieć dwie referencje, tak aby moÅŒna było mieć
//INPUT storage oraz output STORAGE
//------------------------------------------------------------------------------

//ENH: not possible - why?: class Serializer(alias T...)
//ENH: lack of static access to some member of templates without instantiation needed
//BUG: inner class Archive is invisible in default parameter of template
/*******************************************************************************
 ******************************************************************************/
class Serializer(alias CONCRETEARCHIVE, STORAGE=string) {
//ENH: when parameter of function is preceeding by alias, stringof on this parameter
//should give original name of symbol

private:
    //TODO: checks for type requirements
    const info = "Type '" ~ STORAGE.stringof ~ "' does not meet Storage requirements: ";
    //static assert(is(typeof(STORAGE.init) == STORAGE), info ~ "lack of init() method.");
    //static assert(is(typeof(STORAGE.dup) == STORAGE), info ~ "lack of dup() method.");

    enum Mode {LOAD, DUMP}

    alias StorageElementType!(STORAGE)    ELEMENTTYPE;
    alias StorageType!(STORAGE)           STORAGETYPE;

    static synchronized Archive m_archive;

//DMD-ENH: it should work:
//static synchronized Archive m_archive = new Archive;

public:

    /***************************************************************************
        Constructor
     **************************************************************************/
    this() {
        m_archive = new Archive;
        static if (is(typeof(init(Archive)) == bool)) {
            init(m_archive);
        }
    }

    /***************************************************************************
        Returns: copy of current global Archive instance
     **************************************************************************/
    Archive archive() {
        return m_archive.dup_info;
    }

    /***************************************************************************
        Params: arch = Archive instance which should be set as global
     **************************************************************************/
    void archive(Archive arch) {
        m_archive = arch.dup_info;
    }

    /***************************************************************************
        Returns: reference to global instance of Archive
     **************************************************************************/
    //TODO: zmienna globalna powinna być dla typu przy uÅŒyciu sztuczki ze static T val;
    Archive global() {
        return m_archive;
    }

    //ENH: not possible to use it with is expression
    //void wrapper(T : U[N], U, size_t N)(T val, void delegate(ref U[] value) dg);
    //BUG: specialization not allowed for deduced parameter
    //STORAGE dump(T : U[N], U, size_t N)(T v)

    STORAGE dump(VALUE)(VALUE v, STORAGE storage, Archive archive = null) {
        return dumpInternal(v, storage, archive);
    }

    STORAGE dump(VALUE)(VALUE v, Archive archive = null) {
        STORAGE storage;
        static if (is(STORAGE == class)) {
            assert(archive !is null && archive.storage !is null, "You must pass storage to dump method");
            storage = archive.storage;
        }
        return dumpInternal(v, storage, archive);
    }

    /***************************************************************************
        Dumps type into storage
     **************************************************************************/
    //FIXME: it would be better to make instatiations using STORAGE below, and not
    //when creating serializer
    private STORAGE dumpInternal(VALUE)(VALUE v, STORAGE storage, Archive archive = null) {
        Unqual!(normalizedType!(VALUE)) value = cast(Unqual!(normalizedType!(VALUE)))v;

        if (archive is null) archive = m_archive.dup_info;
            else archive = archive.dup_info;

        archive.mode = Mode.DUMP;
        archive.storage = storage;

        archive.start();
        bool res = archive.traverse(value);
        if (res == false)
            throw new SerializerException("Can not dump type " ~ VALUE.stringof ~ ".");
        archive.finish(archive);

        return archive.storage;
    }

    //BUG: in case of below signature, there is no way to add another template parameter
    //U[] load(T : U[N], U, size_t N)(STORAGE storage, Archive archive=null) {
    /***************************************************************************
     **************************************************************************/
    normalizedType!(VALUE) load(VALUE)(STORAGE storage, Archive archive = null) {
        //TODO: static asserts in serializer --> check if all template functions exists in Archive
        if (archive is null) archive = m_archive.dup_info;
            else archive = archive.dup_info;

        archive.mode = Mode.LOAD;
        archive.storage = storage;

        Unqual!(normalizedType!(VALUE)) value;

        archive.start();

        if (!archive.traverse(value))
            throw new SerializerException("Could not load type '" ~ VALUE.stringof ~ "'.");

        checkType(value);
        archive.finish(archive);

        return cast(normalizedType!(VALUE))value;
    }

//------------------------------------------------------------------------------

    /***************************************************************************
     **************************************************************************/
    //FIXME: Archiwum powinno być inicjowane dla konkretnego typu STORAGE
    //W przypadku klas moÅŒe to być tylko interfejs
    static class Archive {
        private:
        //BUG: private attribute is not applied to template functions
        //BUG: how to check if ArchiveExt is defined?

        mixin CONCRETEARCHIVE!(Archive);

        static assert (IndexOf!(STORAGETYPE, AvailableStorageTypes) != -1, "Only following storage types are available: " ~ AvailableStorageTypes.stringof);

        Mode mode = Mode.DUMP;              //serialization/deserialization
        Registry registry;

        this() {
            registry = new Registry;
            static if(is(typeof(init()))) {
                bool ret = init();
                if (!ret) {
                    throw new SerializerException("Could not init archiver");
                }
            }
        }

public:
        Archive dup_info() {
            Archive result;

            static if(is(typeof(dup_infoext()) == Archive)) {
                result = dup_infoext;
            } else result = new Archive;

            result.tracking = tracking;
            result.registry = registry.dup_info;

            result.level = level;
            result.mode = mode;

            return result;
        }

        //BUG: allow following style of declaration ??????:
        //void describe(TYPES...)(ref TYPES params, string name="")
        //or: void describe(TYPES...)(string name="", ref TYPES params)

        /***************************************************************************
         **************************************************************************/
        bool traverse(VALUE)(ref VALUE value) {
            pragma(msg, "traverse: " ~ VALUE.stringof);

            static if (!is(VALUE TYPE == typedef)) {
                //level is not increased for typedefs
                level++;
                scope(success) level--;
            }

            //Eventual additional operations ... at begining of traverse...
            //BUG: SFINAE should fail on syntax errors... Currently simple syntax errors
            //are very difficult to catch
            static if (is(typeof(begin!(VALUE)(value)) == bool)) {
                begin!(VALUE)(value);
            }

            //... and at the end
            static if (is(typeof(finish!(VALUE)(value)) == bool)) {
                scope(success) finish!(VALUE)(value);
            }

            //TODO: shouldn't it be an option?
            //runtime extension parsers for type;
            if (auto peek = registry.peek!(TypeDescription, VALUE)) {
                if (mode == Mode.LOAD && peek.loader !is null) return peek.loader(value, this);
                if (mode == Mode.DUMP && peek.dumper !is null) return peek.dumper(value, this);
            }

            //BUG: Trick with delegate doesn't work here. Why?
            //compile time extension function for parsing
            //Below line is for debuging; change 0 to 1
            static if (0 && CONCRETEARCHIVE.stringof == "JsonArchiveExt(ARCHIVE)" && VALUE.stringof =="Date") return extend!(VALUE)(value);
            static if (is(typeof(extend!(VALUE)(value)) == bool)) {
                return extend!(VALUE)(value);
            }

            //Typedefs
            static if (is(VALUE TYPE == typedef)) {
                return traverse(cast(Unqual!TYPE)value);
            } else
            //Pointers
            static if (is(VALUE TYPE == TYPE*)) {
                if (mode == Mode.LOAD) {
                    if(loadRef(value)) return true;

                    if (tracking == Tracking.ON) {
                        value = registry.get!(TypeDescription, VALUE).address(0); //construct and register
                    } else {
                        value = registry.get!(TypeDescription, VALUE).construct; //just construct - not register
                    }

                } else {
                    if(dumpRef(value)) return true;
                }

                return traverse(cast(Unqual!TYPE)*value);
            } else
            //Strings
            static if (isSomeString!(VALUE)) {
                if (mode == Mode.LOAD) return loadString(value);
                    else return dumpString(value);
            } else
            //Arrays
            static if (is(VALUE U == U[])) {
                if (mode == Mode.LOAD) return loadArray(value);
                    else return dumpArray(value);
            } else
            //Associative Arrays
            static if (isAssociativeArray!(VALUE)) {
                if (mode == Mode.LOAD) return loadAssociativeArray(value);
                    else return dumpAssociativeArray(value);
            } else
            //Structs
            static if (is(VALUE == struct)) {
                if (mode == Mode.LOAD) return loadUdt(value);
                    else return dumpUdt(value);
            } else
            //Classes
            static if (is(VALUE == class)) {
                if (mode == Mode.LOAD) {
                    if (loadRef(value)) return true;

                    if (tracking == Tracking.ON) {
                        value = registry.get!(TypeDescription, VALUE).address(0); //construct and register
                    } else {
                        value = registry.get!(TypeDescription, VALUE).construct; //just construct - not register
                    }

                    return loadUdt(value);
                } else {
                    if (dumpRef(value)) return true;
                    return dumpUdt(value);
                }
            } else
            static if (is(VALUE == bool)) {
                if (mode == Mode.LOAD) return loadBool(value);
                    else return dumpBool(value);
            } else
            static if (isNumeric!(VALUE)) {
                if (mode == Mode.LOAD) return loadNumber(value);
                    else return dumpNumber(value);
            } else
            static if (isSomeChar!(VALUE)) {
                if (mode == Mode.LOAD) return loadChar(value);
                    else return dumpChar(value);
            } else {
                static assert(false, "Unsupported type '" ~ VALUE.stringof ~
                "'. Types like void*, union, enum are not serializable without additional information");
            }
            //TODO: Unions - they are possibly serializable, but probably only through
            //loadUdt/dumpUdt; Enums should be also serializable
        }

        /***************************************************************************
            Returns: true if ok
         **************************************************************************/
        bool processMemberStruct(VALUE)(ref VALUE value) {
            uint defined_ver = 0;
            static if (is(typeof((cast(VALUE)value).versionUdt) == uint)) {
                defined_ver = (cast(VALUE)value).versionUdt;
            }

            auto reg = registry.peek!(TypeDescription, VALUE);
            if (reg !is null && reg.ver > 0) defined_ver = reg.ver;

            if (mode == Mode.LOAD) {
                uint stored_ver;
                bool loaded=false;
                auto verloaded = loadVersion(stored_ver);

                if (stored_ver != defined_ver) {
                    static if ( is(typeof(&value.transformUdt!(Archive)) == void delegate(Archive, ref VALUE, uint))) {
                        value.transformUdt(this, value, stored_ver);
                        loaded = true;
                    } else {
                        throw new SerializerException("Udt version in storage is different than in program");
                    }
                }

                if (!loaded) loadFields(value);

            } else {
                if (!dumpVersion(defined_ver))
                    throw new SerializerException("Can not dump version.");

                dumpFields(value);
            }
            return true;
        }

        /***************************************************************************
         **************************************************************************/
        bool processMemberStructFields(VALUE)(ref VALUE value) {

            //Load function exists
            //TODO: maybe functions loadUdt/dumpUdt/describeUdt should return bool as other functions?
            //or returning bool should be dumped comletely as it is enough to throw exception?
            static if ( is(typeof(&value.loadUdt!(Archive)) == void delegate(Archive))) {
                if (mode == Mode.LOAD) {value.loadUdt(this); return true;}
            } else alias bool notExistsLoad;

            //Dump function exists
            static if ( is(typeof(&value.dumpUdt!(Archive)) == void delegate(Archive))) {
                if (mode == Mode.DUMP) {value.dumpUdt(this); return true;}
            } else alias bool notExistsDump;


            //BUG: One more place where it would be much better to have alias defining
            //compile time constants
            //or enum bool notExistsLoad = true; will work?
            static if (is(notExistsLoad) || is(notExistsDump)) {
                //Exists describe function
                static if ( is(typeof(&value.describeUdt!(Archive)) == void delegate(Archive))) {
                    value.describeUdt(this);
                } else {
                    foreach(i, v; value.tupleof) {
                        if (mode == Mode.LOAD) {
                            normalizedType!(typeof(v)) elem;
                            loadOneField(elem, value.tupleof[i].stringof);
                            checkType!(typeof(v))(elem);

                            static if (isStaticArray!(typeof(v))) {
                                foreach(n, saval; value.tupleof[i]) value.tupleof[i][n] = elem[n];
                            } else {
                                value.tupleof[i]= elem;
                            }

                        } else {
                            normalizedType!(typeof(v)) elem = v;
                            dumpOneField(elem, value.tupleof[i].stringof);
                        }
                    }
                }
            }
            return true;
        }


        /***********************************************************************
         **********************************************************************/
        void describe(TYPE)(ref TYPE variable, string name) {
            bool result;
            //writefln("NAME: ", name, " TYPE: ", TYPE.stringof);
            if (mode == Mode.LOAD) result = loadOneField(variable, name);
                else result = dumpOneField(variable, name);

            if (!result) throw new SerializerException("Can not describe type '" ~ TYPE.stringof ~ "'.");
        }

        //BUG: Unfortunatelly doesn't work
        //void describe(alias TYPE)() {
        //    pragma(msg, "in alias version");
        //    pragma(msg, TYPE.stringof);
        //    describe!(typeof(TYPE))(*TYPE, TYPE.stringof);
        //}

        /***********************************************************************
         **********************************************************************/
        void transform(T)(ref T variable) {
            if (!loadFields(variable))
                throw new Exception("Can not import user defined class.");
        }

        /***********************************************************************
            Returns: reference to type description for type T
         **********************************************************************/
        TypeDescription!(T) typeDescription(T)() {
            return registry.get!(TypeDescription, T);
        }

        //FIXME: should not be public
        uint level = 0;                     ///current level in nested types
        STORAGE storage;                    ///storage type (upcasted to interface type, to decrease code bloat)
        Tracking tracking = Tracking.ON;    ///indicates if references should be tracked
    }
}