En esta página

Convertidor de serialización

Cómo convertir entre diferentes formatos de serialización.

Este ejemplo permite la conversión entre JSON, CBOR, XML, QDataStream y algunos formatos de texto sencillos. Puede detectar automáticamente el formato que se está utilizando o se le puede indicar qué formato debe usar. No todos los formatos admiten tanto la entrada como la salida, y cada uno admite un conjunto diferente de tipos de datos de contenido. « QDataStream » y XML son los que admiten más tipos, seguidos de CBOR, luego JSON y, por último, los formatos de texto sin formato. La conversión a través de los formatos con menos capacidades tiende a provocar la pérdida de la estructura de los datos.

Salida de la terminal que muestra la conversión a JSON de los datos guardados del juego, con los niveles, los PNJ y la información del jugador

La clase «Converter»

La clase `Converter` es la superclase abstracta de todos los convertidores hacia y desde todos los formatos. Todos ellos convierten desde o hacia la clase ` QVariant `, que se utiliza para representar internamente todas las estructuras de datos.

class Converter
{
    static QList<const Converter *> &converters();
protected:
    Converter();
    static bool isNull(const Converter *converter); // in nullconverter.cpp

public:
    static const QList<const Converter *> &allConverters();

    enum class Direction { In = 1, Out = 2, InOut = In | Out };
    Q_DECLARE_FLAGS(Directions, Direction)

    enum Option { SupportsArbitraryMapKeys = 0x01 };
    Q_DECLARE_FLAGS(Options, Option)

    virtual ~Converter() = 0;

    virtual QString name() const = 0;
    virtual Directions directions() const = 0;
    virtual Options outputOptions() const;
    virtual const char *optionsHelp() const;
    virtual bool probeFile(QIODevice *f) const;
    virtual QVariant loadFile(QIODevice *f, const Converter *&outputConverter) const;
    virtual void saveFile(QIODevice *f, const QVariant &contents,
                          const QStringList &options) const = 0;
};

Q_DECLARE_OPERATORS_FOR_FLAGS(Converter::Directions)
Q_DECLARE_OPERATORS_FOR_FLAGS(Converter::Options)

El constructor y el destructor de Converter gestionan una lista de convertidores disponibles que utiliza el programa principal, de modo que este sepa qué convertidores hay disponibles. Cada tipo de convertidor define una instancia estática que garantiza su construcción y, por lo tanto, su disponibilidad para el programa principal a través de esta lista. El método ` allConverters() ` proporciona al código de ` main()` acceso a la lista.

Converter::Converter()
{
    converters().append(this);
}

Converter::~Converter()
{
    converters().removeAll(this);
}

QList<const Converter *> &Converter::converters()
{
    Q_CONSTINIT static QList<const Converter *> store;
    return store;
}

const QList<const Converter *> &Converter::allConverters()
{
    return converters();
}

La función name() devuelve el nombre del convertidor. La función directions() se utiliza para determinar si un convertidor puede utilizarse para la entrada, la salida o ambas. Esto permite al programa principal indicar qué convertidores están disponibles en su texto de ayuda para las opciones de la línea de comandos destinadas a seleccionar los formatos de entrada y salida.

    QStringList inputFormats;
    QStringList outputFormats;
    for (const Converter *conv : Converter::allConverters()) {
        auto direction = conv->directions();
        QString name = conv->name();
        if (direction.testFlag(Converter::Direction::In))
            inputFormats << name;
        if (direction.testFlag(Converter::Direction::Out))
            outputFormats << name;
    }

La función optionsHelp() se utiliza para indicar las distintas opciones de línea de comandos compatibles con los formatos disponibles, cuando se consulta mediante la opción de línea de comandos « --format-options <format> ».

       for (const Converter *conv: Converter::allConverters()) {
            if (conv->name()== format) {
                const char *help = conv->optionsHelp();
                if (help) {
                    qInfo("The following options are available for format '%s':\n\n%s",
                          qPrintable(format), help);
                } else {
                    qInfo("Format '%s' supports no options.", qPrintable(format));
                }
                return EXIT_SUCCESS;
            }
        }

La función outputOptions() informa de las capacidades de salida de un convertidor. En la actualidad, la única característica opcional es la compatibilidad con claves arbitrarias en las asignaciones de claves a valores. La función loadFile() de un convertidor de entrada puede utilizar esta información para adaptar el formato en el que presenta los datos que ha leído, de modo que el convertidor de salida los represente con la mayor fidelidad posible, dentro de las capacidades de este.

La función probeFile() se utiliza para determinar si un archivo se ajusta al formato del convertidor. El programa principal la utiliza para determinar qué formato emplear al leer o escribir un archivo, basándose en su nombre y, posiblemente, en su contenido, cuando el usuario no ha especificado el formato a utilizar en la línea de comandos.

La función `loadFile()` deserializa los datos. La función que la invoca indica a `loadFile()` qué serializador pretende utilizar, de modo que `loadFile()` pueda consultar sus `outputOptions()` para determinar la forma en que representar los datos cargados. Si la función que la invoca no ha elegido un conversor de salida, `loadFile()` le proporciona un conversor de salida por defecto adecuado para los datos que está devolviendo.

La función saveFile() serializa los datos. Se le pasan opciones desde la línea de comandos, tal y como describe loadHelp(), que permiten ajustar los detalles de cómo se representan los datos al guardarlos en un archivo.

Tanto `loadFile()` como `saveFile()` pueden utilizarse con un ` QIODevice` arbitrario. Esto significa que un `Converter` también podría utilizarse con un socket de red u otra fuente de datos, para leer o escribir en ella. En el presente programa, el programa principal siempre pasa un ` QFile`, accediendo bien a un archivo en disco, bien a uno de los flujos estándar del proceso.

Los convertidores disponibles

Se admiten varios convertidores, lo que ilustra cómo se podría adaptar el programa convertidor a otros formatos, en caso de que fuera necesario. Consulta el código fuente de cada uno para obtener más detalles. Los convertidores CBOR sirven como un ejemplo relativamente completo de las formas en que pueden funcionar los convertidores, que analizaremos con más detalle a continuación. Esta tabla resume los convertidores disponibles:

Clasemodoformato
CborConverterEntrada/SalidaCBOR
CborDiagnosticDumperSalidaDiagnóstico CBOR
DataStreamConverterEntrada/SalidaQDataStream
Volcado de texto de depuraciónSalidaSin pérdidas, no estándar, legible por humanos
JsonConverterEntrada/SalidaJSON
NullConverterSalidaSin salida
TextConverterEntrada/SalidaTexto sin formato estructurado
XmlConverterEntrada/SalidaXML

Los que admiten entrada se utilizan a sí mismos como convertidores de reserva de loadFile(), excepto los convertidores CBOR y QDataStream, que utilizan sus respectivas clases complementarias de volcado, destinadas únicamente a la salida. El convertidor nulo se puede utilizar como convertidor de salida al ejecutar el programa, con el fin de realizar cualquier validación o verificación que pueda llevar a cabo un convertidor de entrada.

Las clases CborConverter y CborDiagnosticDumper

La clase `CborConverter` admite la serialización hacia y desde el formato CBOR. Admite diversas opciones para configurar la salida de valores de coma flotante y una opción ` signature ` para determinar si su salida debe comenzar con una etiqueta CBOR que sirva como encabezado del archivo, identificando que este contiene datos CBOR.

También existe la clase `CborDiagnosticDumper`, que genera salida en notación de diagnóstico CBOR. No admite la carga de datos. El formato de su salida se puede configurar mediante dos opciones. Una de ellas permite seleccionar si se utiliza el formato de diagnóstico CBOR ampliado (más detallado). La otra controla si cada valor CBOR aparece en una línea separada.

La notación de diagnóstico simple es similar a JSON, pero no exactamente igual, ya que permite mostrar el contenido de un flujo CBOR sin pérdidas, mientras que la conversión a JSON puede conllevar pérdidas. El método loadFile() de CborConverter utiliza CborDiagnosticDumper como convertidor de salida alternativo, si el programa que lo invoca no ha determinado por sí mismo el formato de salida.

Las funciones auxiliares convertCborValue(), convertCborMap() y convertCborArray() se utilizan para convertir un objeto ` QCborValue ` en un ` QVariant`, en beneficio de `CborConverter::loadFile()`.

static QVariant convertCborValue(const QCborValue &value);

static QVariant convertCborMap(const QCborMap &map)
{
    VariantOrderedMap result;
    result.reserve(map.size());
    for (auto pair : map)
        result.append({ convertCborValue(pair.first), convertCborValue(pair.second) });
    return QVariant::fromValue(result);
}

static QVariant convertCborArray(const QCborArray &array)
{
    QVariantList result;
    result.reserve(array.size());
    for (auto value : array)
        result.append(convertCborValue(value));
    return result;
}

static QVariant convertCborValue(const QCborValue &value)
{
    if (value.isArray())
        return convertCborArray(value.toArray());
    if (value.isMap())
        return convertCborMap(value.toMap());
    return value.toVariant();
}

La función `convertFromVariant()` se utiliza para convertir un ` QVariant ` en un ` QCborValue ` para su salida mediante ` saveFile() ` de cualquiera de las dos clases.

enum TrimFloatingPoint { Double, Float, Float16 };
static QCborValue convertFromVariant(const QVariant &v, TrimFloatingPoint fpTrimming)
{
    if (v.userType() == QMetaType::QVariantList) {
        const QVariantList list = v.toList();
        QCborArray array;
        for (const QVariant &v : list)
            array.append(convertFromVariant(v, fpTrimming));

        return array;
    }

    if (v.userType() == qMetaTypeId<VariantOrderedMap>()) {
        const auto m = qvariant_cast<VariantOrderedMap>(v);
        QCborMap map;
        for (const auto &pair : m)
            map.insert(convertFromVariant(pair.first, fpTrimming),
                       convertFromVariant(pair.second, fpTrimming));
        return map;
    }

    if (v.userType() == QMetaType::Double && fpTrimming != Double) {
        float f = float(v.toDouble());
        if (fpTrimming == Float16)
            return float(qfloat16(f));
        return f;
    }

    return QCborValue::fromVariant(v);
}

El programa convert

La función ` main() ` configura un ` QApplication ` y un ` QCommandLineParser ` para interpretar las opciones especificadas por el usuario y proporcionar ayuda si este la solicita. Utiliza los valores obtenidos de las distintas instancias de ` QCommandLineOption ` que describen las elecciones del usuario, además de los argumentos posicionales para los nombres de archivo, con el fin de preparar los convertidores que va a utilizar.

A continuación, utiliza su convertidor de entrada para cargar los datos (y, posiblemente, determinar qué convertidor de salida utilizar, si aún no ha seleccionado ninguno) y su convertidor de salida para serializar dichos datos, teniendo en cuenta cualquier opción de salida que el usuario haya especificado en la línea de comandos.

    QStringList files = parser.positionalArguments();
    QFile input(files.value(0));
    QFile output(files.value(1));
    const Converter *inconv = prepareConverter(parser.value(inputFormatOption),
                                               Converter::Direction::In, &input);
    const Converter *outconv = prepareConverter(parser.value(outputFormatOption),
                                                Converter::Direction::Out, &output);

    // Now finally perform the conversion:
    QVariant data = inconv->loadFile(&input, outconv);
    Q_ASSERT_X(outconv, "Serialization Converter",
               "Internal error: converter format did not provide default");
    outconv->saveFile(&output, data, parser.values(optionOption));
    return EXIT_SUCCESS;

Proyecto de ejemplo en code.qt.io

Véase también «Análisis y visualización de datos CBOR», «Guardar y cargar una partida» y «Compatibilidad con CBOR en Qt».

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.