//! \~\file pivaluetree_conversions.h
//! \~\ingroup Serialization
//! \~\brief
//! \~english %PIValueTree conversion helpers
//! \~russian Вспомогательные преобразования %PIValueTree
/*
    PIP - Platform Independent Primitives
    PIValueTree conversions
    Ivan Pelipenko peri4ko@yandex.ru

    This program 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 3 of the License, or
    (at your option) any later version.

    This program 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 program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef pivaluetree_conversions_H
#define pivaluetree_conversions_H

#include "pivaluetree.h"

class PIPropertyStorage;
class PIJSON;
class PIIODevice;

//! \relatesalso PIValueTree
//! \~english Namespace with conversions between %PIValueTree and other public serialization formats.
//! \~russian Пространство имен с преобразованиями между %PIValueTree и другими публичными форматами сериализации.
namespace PIValueTreeConversions {

//! \~english Conversion options.
//! \~russian Параметры преобразования.
enum Option {
    WithAttributes = 0x1 /** \~english Include node attributes \~russian Включать атрибуты узлов */,
    WithComment    = 0x2 /** \~english Include node comments \~russian Включать комментарии узлов */,
    WithType       = 0x4 /** \~english Include textual value type information \~russian Включать текстовую информацию о типе значения */,
    WithAll        = 0xFFF /** \~english Enable all content flags \~russian Включать все флаги содержимого */,
    IncludeRoot    = 0x1000 /** \~english Serialize the passed root node itself instead of only its children \~russian Сериализовать сам
                               переданный корневой узел, а не только его дочерние элементы */
        ,
    Default = WithAll /** \~english Default conversion options \~russian Параметры преобразования по умолчанию */
};

//! \~english Bit mask of %PIValueTree conversion options.
//! \~russian Набор флагов параметров преобразования %PIValueTree.
typedef PIFlags<Option> Options;

//! \~english Builds a tree from flat %PIPropertyStorage entries.
//! \~russian Создает дерево из плоского набора записей %PIPropertyStorage.
PIP_EXPORT PIValueTree fromPropertyStorage(const PIPropertyStorage & ps);

//! \~english Builds a tree whose top-level children come from a %PIVariantMap.
//! \~russian Создает дерево, в котором дочерние элементы верхнего уровня берутся из %PIVariantMap.
PIP_EXPORT PIValueTree fromVariantMap(const PIVariantMap & vm);

//! \~english Converts JSON tree representation produced by this module into %PIValueTree.
//! \~russian Преобразует JSON-представление дерева, создаваемое этим модулем, в %PIValueTree.
PIP_EXPORT PIValueTree fromJSON(const PIJSON & json);

//! \~english Parses PIP text configuration format from a device into %PIValueTree.
//! \~russian Разбирает текстовый конфигурационный формат PIP из устройства в %PIValueTree.
PIP_EXPORT PIValueTree fromText(PIIODevice * device);

//! \~english Parses PIP text configuration format from a string into %PIValueTree.
//! \~russian Разбирает текстовый конфигурационный формат PIP из строки в %PIValueTree.
PIP_EXPORT PIValueTree fromText(const PIString & str);

//! \~english Loads JSON tree text from file and merges an optional \c .override companion file when it exists.
//! \~russian Загружает JSON-представление дерева из файла и объединяет его с дополнительным файлом \c .override, если он существует.
PIP_EXPORT PIValueTree fromJSONFile(const PIString & path);

//! \~english Loads text tree configuration from file and merges an optional \c .override companion file when it exists.
//! \~russian Загружает текстовую конфигурацию дерева из файла и объединяет ее с дополнительным файлом \c .override, если он существует.
PIP_EXPORT PIValueTree fromTextFile(const PIString & path);

//! \~english Converts %PIValueTree to the module JSON tree representation.
//! \~russian Преобразует %PIValueTree в JSON-представление дерева этого модуля.
PIP_EXPORT PIJSON toJSON(const PIValueTree & root, Options options = Default);

//! \~english Converts %PIValueTree to the PIP text configuration format.
//! \~russian Преобразует %PIValueTree в текстовый конфигурационный формат PIP.
PIP_EXPORT PIString toText(const PIValueTree & root, Options options = Default);

//! \~english Writes JSON tree text to file. Returns \c true when the whole output was written.
//! \~russian Записывает JSON-представление дерева в файл. Возвращает \c true, если записан весь результат.
PIP_EXPORT bool toJSONFile(const PIString & path, const PIValueTree & root, Options options = Default);

//! \~english Writes text tree configuration to file. Returns \c true when the whole output was written.
//! \~russian Записывает текстовую конфигурацию дерева в файл. Возвращает \c true, если записан весь результат.
PIP_EXPORT bool toTextFile(const PIString & path, const PIValueTree & root, Options options = Default);

} // namespace PIValueTreeConversions

#endif