<commit_before>/******************************************************************************
 * This file is part of the Gluon Development Platform
 * Copyright (c) 2009 <NAME> <<EMAIL>>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */
#ifndef GLUON_CORE_GDLHANDLER_H
#define GLUON_CORE_GDLHANDLER_H

#include <QtCore/QObject>
#include <QtCore/QString>

#include "singleton.h"
#include "gluon_core_export.h"

namespace GluonCore
{
    class GluonObject;

    /**
     * \brief Functionality for serializing and deserializing GluonObjects
     *
     * This singleton class provides functionality for serializing and deserializing
     * GluonObject instances to and from the GDL object definition language.
     * 
     * A generalized use scenario for GDLHandler is loading a gdl file from disk and
     * deserializing it into GluonObject instances, do a change to some object in
     * the hierarchy and then save it back into a file. The following function will
     * do that:
     * 
     * \code
bool fiddleWithObjects(QString filename)
{
    QFile projectFile(QFileInfo(filename().toLocalFile()).fileName());
    if (!projectFile.open(QIODevice::ReadWrite))
        return false;
    
    QTextStream projectReader(&projectFile);
    QString fileContents = projectReader.readAll();
    
    if (fileContents.isEmpty())
        return false;
    
    QList<GluonObject*> objectList = GluonCore::GDLHandler::instance()->parseGDL(fileContents, this->parent());
    
    foreach(GluonObject* obj, objectList)
    {
        obj->setName(QString("%1 %2").arg(obj->name()).arg("changed"));
    }
    
    QString serializedData = GluonCore::GDLHandler::instance()->serializeGDL();
    QTextStream out(&projectFile);
    out << serializedData;
    projectFile.close();
    
    return true;
}\endcode
     * 
     * <b>The Gluon Definition Language</b>
     *
     * The Gluon Definition Language, or GDL, is a very simple, hierarchical object
     * definition language, designed for use with GluonObject derived classes. The
     * structure of the language can easiest be described as follows:
     * 
     * \verbatim
{ ClassName(ObjectName)
    PropertyName DataTypeName(Value)
    PropertyName2 DataTypeName2(Value2)
    { ClassName(ObjectName)
        PropertyName DataTypeName(Value)
    }
}
\endverbatim
     * 
     * The above sample represents two nested objects of the type ClassName, both named
     * ObjectName. The fully qualified name for the objects respectively are ObjectName
     * and ObjectName.ObjectName and this can be used in properties as well.
     * 
     * PropertyName and PropertyName2 are as the names indicate properties named that way.
     * Their values are Value and Value2 respectively, and the data type contained in the
     * properties are DataTypeName and DataTypeName2 respectively.
     * 
     * An important aspect of GDL is the ability for any property to reference any other
     * object in the hierarchy. An example of this might be:
     * 
     * \verbatim
{ GluonObject(AnotherObject)
    reference GluonObject(AnObject.AChildObject)
}
{ GluonObject(AnObject)
    { GluonObject(AChildObject)
    }
}
\endverbatim
     * 
     * The property reference on the AnotherObject object is then a reference to the object
     * with the fully qualified name AnObject.AChildObject. Also shown here is the the fact
     * that an object does not have to be defined before it is able to be referenced.
     * 
     * Finally, this example also shows how GDL can have multiple root nodes in the same
     * file. For these references to work correctly, it is vital that all the objects
     * have the same object parent (that is, the parent passed in the parseGDL function).
     */
    class GLUON_CORE_EXPORT GDLHandler : public Singleton<GDLHandler>
    {
            Q_OBJECT

        public:
            /**
             * Deserialise a GDL string representation into their GluonObject counterpart
             * 
             * \note Please be aware that in the case of an incorrect GDL string, you will not be given
             * a correct list of GluonObjects. That is, the function does not currently degrade gracefully.
             * As such, please ensure the data is acceptable upon return.
             * 
             * @param   parseThis   The GDL string that you wish to parse into GluonObject instances
             * @param   parent      The QObject you wish the objects to be parented to
             * @return  A list of generated GluonObject instances
             */
            QList<GluonObject *> parseGDL(const QString parseThis, QObject * parent);
            
            /**
             * Serialize a list of GluonObject instances into a GDL representation
             * @param   serializeThis   The list of GluonObject instances you wish to serialize
             * @return  The serialized objects
             */
            QString serializeGDL(QList<const GluonObject *> serializeThis);

        private:
            friend class Singleton<GDLHandler>;

            GDLHandler();<commit_msg>Add descriptions of the various supported data types to the GDL documentation<commit_after>/******************************************************************************
 * This file is part of the Gluon Development Platform
 * Copyright (c) 2009 <NAME> <<EMAIL>>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */
#ifndef GLUON_CORE_GDLHANDLER_H
#define GLUON_CORE_GDLHANDLER_H

#include <QtCore/QObject>
#include <QtCore/QString>

#include "singleton.h"
#include "gluon_core_export.h"

namespace GluonCore
{
    class GluonObject;

    /**
     * \brief Functionality for serializing and deserializing GluonObjects
     *
     * This singleton class provides functionality for serializing and deserializing
     * GluonObject instances to and from the GDL object definition language.
     * 
     * A generalized use scenario for GDLHandler is loading a gdl file from disk and
     * deserializing it into GluonObject instances, do a change to some object in
     * the hierarchy and then save it back into a file. The following function will
     * do that:
     * 
     * \code
bool fiddleWithObjects(QString filename)
{
    QFile projectFile(QFileInfo(filename().toLocalFile()).fileName());
    if (!projectFile.open(QIODevice::ReadWrite))
        return false;
    
    QTextStream projectReader(&projectFile);
    QString fileContents = projectReader.readAll();
    
    if (fileContents.isEmpty())
        return false;
    
    QList<GluonObject*> objectList = GluonCore::GDLHandler::instance()->parseGDL(fileContents, this->parent());
    
    foreach(GluonObject* obj, objectList)
    {
        obj->setName(QString("%1 %2").arg(obj->name()).arg("changed"));
    }
    
    QString serializedData = GluonCore::GDLHandler::instance()->serializeGDL();
    QTextStream out(&projectFile);
    out << serializedData;
    projectFile.close();
    
    return true;
}\endcode
     * 
     * <b>The Gluon Definition Language</b>
     *
     * The Gluon Definition Language, or GDL, is a very simple, hierarchical object
     * definition language, designed for use with GluonObject derived classes. The
     * structure of the language can easiest be described as follows:
     * 
     * \verbatim
{ ClassName(ObjectName)
    PropertyName DataTypeName(Value)
    PropertyName2 DataTypeName2(Value2)
    { ClassName(ObjectName)
        PropertyName DataTypeName(Value)
    }
}
\endverbatim
     * 
     * The above sample represents two nested objects of the type ClassName, both named
     * ObjectName. The fully qualified name for the objects respectively are ObjectName
     * and ObjectName.ObjectName and this can be used in properties as well.
     * 
     * PropertyName and PropertyName2 are as the names indicate properties named that way.
     * Their values are Value and Value2 respectively, and the data type contained in the
     * properties are DataTypeName and DataTypeName2 respectively.
     * 
     * An important aspect of GDL is the ability for any property to reference any other
     * object in the hierarchy. An example of this might be:
     * 
     * \verbatim
{ GluonObject(AnotherObject)
    reference GluonObject(AnObject.AChildObject)
}
{ GluonObject(AnObject)
    { GluonObject(AChildObject)
    }
}
\endverbatim
     * 
     * The property reference on the AnotherObject object is then a reference to the object
     * with the fully qualified name AnObject.AChildObject. Also shown here is the the fact
     * that an object does not have to be defined before it is able to be referenced.
     * 
     * Finally, this example also shows how GDL can have multiple root nodes in the same
     * file. For these references to work correctly, it is vital that all the objects
     * have the same object parent (that is, the parent passed in the parseGDL function).
     * 
     * <b>Data types</b>
     * 
     * Data types supported by GDL outside of the classes registered in GluonObjectFactory are:
     * 
     * - string(value) where value is any string
     * - bool(value) where value is the string literal true or false
     * - float(value) where value is any floating point number
     * - vector3d(value;value;value) where value is any floating point number
     * - quaternion(value;value;value;value) where value is any floating point number
     * - int(value) where value is any integer value
     * - uint(value) where value is any unsigned integer value
     * - size2d(value;value) where value is any floating point value
     * - vector2d(value;value) where value is any floating point value
     * - rgba(value;value;value;value) where value is a number between 0 and 255 inclucive
     * - file(value) where value is a valid filename ( see also GluonEngine::Asset:file )
     * - url(value) where value is a valid URL
     * 
     */
    class GLUON_CORE_EXPORT GDLHandler : public Singleton<GDLHandler>
    {
            Q_OBJECT

        public:
            /**
             * Deserialise a GDL string representation into their GluonObject counterpart
             * 
             * \note Please be aware that in the case of an incorrect GDL string, you will not be given
             * a correct list of GluonObjects. That is, the function does not currently degrade gracefully.
             * As such, please ensure the data is acceptable upon return.
             * 
             * @param   parseThis   The GDL string that you wish to parse into GluonObject instances
             * @param   parent      The QObject you wish the objects to be parented to
             * @return  A list of generated GluonObject instances
             */
            QList<GluonObject *> parseGDL(const QString parseThis, QObject * parent);
            
            /**
             * Serialize a list of GluonObject instances into a GDL representation
             * @param   serializeThis   The list of GluonObject instances you wish to serialize
             * @return  The serialized objects
             */
            QString serializeGDL(QList<const GluonObject *> serializeThis);

        private:
            friend class Singleton<GDLHandler>;

            GDLHandler();
{'fraction_non_alphanumeric': 0.07547619047619047, 'fraction_numerical': 0.004523809523809524, 'mean_word_length': 2.8808130582075764, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 39, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '574391', 'n_tokens_mistral': 3338, 'n_tokens_neox': 3182, 'n_words': 1354}