Table des matières

• Sérialisation / Désérialisation
• Introduction à Serde
• Implémentation du trait Deserialize
  • Utilisation d’un Deserializers
  • Le trait Visitor
  • Le trait MapAccess
  • Désérialisation d’une structure de plus d’un champ (approche naïve)
  • Désérialisation d’une structure de plus d’un champ (approche systématique)
  • Désérialisation depuis d’autres formats
  • Composition de structures
  • Désérialiser un tableau
  • Désérialiser une énumération
• Implémentation du trait Serialize
• Les dérivations
• Désérialisation personnalisée
  • Format simple
  • Format complexe
  • Format hexadécimal
  • On fusionne tout
  • Serialize with
• Conclusion

Bonjour à toutes et à tous 😀

Une fois n’est pas coutume, nous allons partir d’un cahier des charges.

Je dispose de 3 fichiers:

Un YAML

color: "r:66,v:38,b:128"

Un JSON

{
    "color": "66,38,128"
}

Un TOML

color = "#422d80"

Je désire obtenir mes données dans la structure Rust suivante:

struct Color {
    r: u8,
    v: u8,
    b: u8
}

struct Data {
    color: Color
}

De quelle manière peut-on réaliser cela en Rust ?

C’est ce que l’on va voir dans la suite.

C’est parti !

Sérialisation / Désérialisation

Lorsque vous jouez aux jeux-vidéos à moins que vous soyez sur un jeu datant d’avant le Déluge, vous avez la possibilité de sauvegarder votre partie.

Celle-ci sera stockée dans la mémoire sous la forme d’un fichier.

Exemple : Vous êtes au niveau 40, votre inventaire est composé d’une épée en bois et d’une gourde, vous avez 10 pv.

Ces informations peuvent-être stockées de manière textuelle ainsi :

lvl=40
pv=10
inventory=wood_sword,flask

Ce fichier sera alors lu et interprété pour reconstituer l’état du jeu avant sauvegarde.

On vient de réaliser un processus de sérialisation/désérialisation.

  

flowchart LR
  Jeu-- "Sérialisation"-->Sauvegarde
  Sauvegarde -- "Désérialisation"-->Jeu

Le format de sérialisation est libre, vous pouvez tout aussi bien définir un protocole qui vous est propre.

Par exemple la sauvegarde du dessus qui est relativement explicite, pourrait être plus cryptique :

40;10;4,9

Les données sont les mêmes, mais ne sont pas représentées dans la sauvegarde de la même manière.

Le processus de sérialisation consiste donc à transformer une structure de données en un format pouvant être stocké et transmis.

La principale caractéristique d’une bonne sérialisation, c’est qu’elle est réversible via le processus inverse de désérialisation.

  

flowchart LR
  A[Structure de Données]
  B[Données sérialisées]
  A-- "Sérialisation"-->B
  B-- "Désérialisation"-->A

Remarque

Écrire du code en programmation, c’est sérialiser la pensée humaine 🤯

Introduction à Serde

Lorsque l’on débute dans le monde de la sérialisation/désérialisation en Rust, on se retrouve très vite à entendre parler de serde.

A comprendre SERialisationDEserialization

Serde est une crate qui fourni à la fois une série de traits mais aussi une batterie de fonctions utilitaires, ainsi que de macros.

Nous allons voir dans la suite de l’article comment nous en servir.

Implémentation du trait Deserialize

En recherchant un peu sur internet, on finit par découvrir la crate serde_yaml. Celle-ci comme son nom l’indique, permet de sérialiser et de désérialiser des structures de données au format YAML.

On installe celle-ci

cargo add serde_yaml

Exemple le fichier suivant

value:12

Nous voulons la structure suivante :

struct Data {
    value: u8
}

En creusant dans la documentation de la crate serde_yaml, nous trouvons une fonction qui prend en paramètre une chaîne de caractères.

Celle-ci renvoie un résultat sous la forme d’un Result<T> où T implémente le trait Deserialize.

En l’absence d’indices pour le compilateur, vous devez spécifier le type de T

fn main() {
    let str_data = r#"value: 12"#;
    let data = serde_yaml::from_str(str_data)
        .expect("Something goes wrong");
}

Sinon vous recevrez cette erreur :

error[E0282]: type annotations needed
  |
  |     let data = serde_yaml::from_str(str_data)
  |         ^^^^ consider giving `data` a type

Que vous pouvez corriger ainsi

let data : Data = serde_yaml::from_str(str_data)
        .expect("Something goes wrong");

ou

let data  = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");

Mais cela conduit à une seconde erreur:

error[E0277]: the trait bound `Data: Deserialize<'_>` is not satisfied
     |
     |     let data = serde_yaml::from_str::<Data>(str_data)
     |                                       ^^^^ 
the trait `Deserialize<'_>` is not implemented for `Data`

Ce trait Deserialize est notre premier pas dans l’utilisation de la crate serde. En effet se trait fait partie du module serde::de::Deserialize.

Nous devons donc pour rendre compatible notre structure Data en venant implémenter le trait serde::de::Deserialize.

struct Data {
    value: u8
}

// On rajoute notre implémentation Deserialize à notre structure Data
impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        todo!()
    }
}

fn main() {
    let str_data = r#"value: 12"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
}

Cela va bien évidemment provoquer une erreur de code non implémenté.

Ceci peut être fait en renvoyant une structure Data par défaut :

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        Ok(Data {
            value: 0,
            value2: false,
        })
    }
}

Ce code compile, mais ne renverra bien sûr pas de résultat qui varie en fonction de l’entrée.

Pour ce faire, nous devons utiliser une autre partie de la crate serde.

Utilisation d’un Deserializers

Il s’agit des Deserializers.

Ça tombe bien la méthode deserialize nous fourni ce Deserializer, ou plutôt serde_yaml nous en fourni un.

Nous verrons dans une partie suivante comment créer notre propre Deserializer

Ce désérialiser implémente le trait Deserializer, celui-ci nous fourni une série de fonctions.

La méthode qui va nous intéresser se nomme deserialize_map.

Le trait Visitor

Comme l’indique la documentation la méthode deserialize_map prend un paramètre qui implémente un trait serde::de::Visitor

Si vous ne connaissez pas le pattern visitor, vous pouvez vous y former ici.

Ce trait Visitor possèdent une fonction et un type qui doivent être définis.

Nous pouvons alors modifier notre code en conséquence :

struct DataVisitor;

impl<'de> Visitor<'de> for DataVisitor {
    // Nous allons désérialiser vers la structure Data
    type Value = Data;

    // Défini l'erreur renvoyée en cas de souci
    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("Expecting data")
    }    
}

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(DataVisitor);
    }
}

Si l’on exécute le code

struct Data {
    value: u8
}

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(DataVisitor);
    }
}

struct DataVisitor;

impl<'de> Visitor<'de> for DataVisitor {
    // Nous allons désérialiser vers la structure Data
    type Value = Data;

    // Défini l'erreur renvoyée en cas de souci
    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("Expecting data")
    }    
}

fn main() {
    let str_data = r#"value: 12"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
}

Celui-ci nous renvoie une erreur :

Error("invalid type: map, expected Expecting data", line: 1, column: 1)

Ce qu’il nous dit énigmatiquement, c’est qu’il a tenté de visiter une map mais que le visiteur n’est pas capable de le faire.

Nous allons donc devoir implémenter la méthode visit_map sur notre DataVisitor.

impl<'de> Visitor<'de> for DataVisitor {
    // Nous allons désérialiser vers la structure Data
    type Value = Data;

    // Défini l'erreur renvoyée en cas de souci
    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("Expecting data")
    }
    
    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        unimplemented!()
    }
}

Si l’on relance, on arrive dans notre fonction avec un joli panic!

thread 'main' panicked at 'not implemented

Ça échoue avec succès, c’est parfait !

Le trait MapAccess

Si l’on analyse un peu plus en détails la signature de la méthode visit_map. On voit que celle-ci renvoie un

Result<Self::Value, E>

Ce Self::Value est en fait le type Value de notre DataVisitor.

impl<'de> Visitor<'de> for DataVisitor {
    type Value = Data;
}

Par conséquent, nous devons également faire renvoyer un Result<Data, E> à notre visit_map.

struct Data {
    value: u8
}

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(DataVisitor);
    }
}

struct DataVisitor;

impl<'de> Visitor<'de> for DataVisitor {
    // Nous allons désérialiser vers la structure Data
    type Value = Data;

    // Défini l'erreur renvoyée en cas de souci
    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("Expecting data")
    }
    
    // On défini la variante map pour notre visiteur
    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        Ok(Data {
            value: 0
        })
    }
}

fn main() {
    let str_data = r#"value: 12"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
}

Ce qui conduit à encore une erreur :

Error("invalid length 1, expected map containing 0 entries", line: 1, column: 1)

Ok! Là, c’est un peu plus énigmatique ! 😕

Pour comprendre, il faut analyser le paramètre d’entrée de la fonction visit_map, il nous fournit une structure qui implémente le trait MapAccess.

Dans les méthodes implémentées par ce trait, deux d’entre-elles vont nous intéresser.

• next_key
• next_value

Elles vont nous permettre de désérialiser respectivement la clef et la valeur de chaque entrée de la map qui représente notre structure de données Data.

Cette map à une particularité : les clefs sont toujours des chaînes de caractères.

Map<&str, T:Deserialize>

Nous allons pouvoir récupérer nos données.

Notre structrure ne possédant qu’un seul champ. Si l’on exécute next_value nous sommes certains d’accéder à la valeur du champ value.

Ce champ étant un u8, nous demandons à next_value de désérialiser vers une valeur de u8.

    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        let value = map.next_value::<u8>();

        Ok(Data {
            value
        })
    }

Une erreur survient

thread 'main' panicked at 'unexpected end of mapping'

Cette erreur est due à la manière dont la map est consommée par le deserializer: il vient d’abord analyser la clef de l’entrée puis passe au séparateur et enfin atteint la valeur.

┌-- clef
|        ┌-- valeur  
↓        ↓
value : 12
    ^^^^ séparateur

Nous devons donc consommer la clef avant de pouvoir le faire avec la valeur. Comme nous savons que la clef est toujours du type &str. Nous pouvons utiliser la désérialisation de la clef vers une chaîne de caractères.

struct Data {
    value: u8
}

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(DataVisitor);
    }
}

struct DataVisitor;

impl<'de> Visitor<'de> for DataVisitor {
    // Nous allons désérialiser vers la structure Data
    type Value = Data;

    // Défini l'erreur renvoyée en cas de souci
    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("Expecting data")
    }
    
    // On défini la variante map pour notre visiteur
    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        // On consomme la clef "value"
        map.next_key();
        // On se permet un unwrap pour l'exemple
        let value = map.next_value::<u8>().unwrap();

        Ok(Data {
            value
        })
    }
}

fn main() {
    let str_data = r#"value: 12"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
    dbg!(data)
}

data = Ok(
    Data {
        value: 12,
    },
)

Cette fois-ci c’est bon. 😀

Désérialisation d’une structure de plus d’un champ (approche naïve)

C’est cool, mais pour l’instant, il n’y a qu’une entrée dans notre structure.

Que se passe-t-il si la structure ressemble plutôt à ceci :

struct Data {
    value: u8,
    value2: bool
}

Si l’on exécute à nouveau notre code précédent, mais avec des données plus complexes qui comportent les deux champs :

• value
• value2

impl<'de> Visitor<'de> for DataVisitor {
    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        map.next_key();
        let value = map.next_value::<u8>().unwrap();

        Ok(Data {
            value,
            // on force la vaeur pour passer la compilation
            value2: false
        })
    }
}


fn main() {
    let str_data = r#"value: 12`
value2: true"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
    dbg!(data)
}

Cela provoque une erreur :

Error("invalid length 2, expected map containing 1 entry", line: 1, column: 1)

Maintenant que nous parlons la langue des deserializer, nous comprenons que nous ne consommons qu’une seule entrée sur les 2 existantes dans la map fourni par le serde_yaml.

struct Data {
    value: u8,
    value2: bool
}

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(DataVisitor);
    }
}

struct DataVisitor;

impl<'de> Visitor<'de> for DataVisitor {
    // Nous allons désérialiser vers la structure Data
    type Value = Data;

    // Défini l'erreur renvoyée en cas de souci
    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("Expecting data")
    }
    
    // On défini la variante map pour notre visiteur
    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        // On consomme la clef "value"
        map.next_key();
        // On se permet un unwrap pour l'exemple
        let value = map.next_value::<u8>().unwrap();

        // On consomme la clef "value2"
        map.next_key();
        // On se permet un unwrap pour l'exemple
        let value2 = map.next_value::<bool>().unwrap();

        Ok(Data {
            value,
            value2
        })
    }
}

fn main() {
    let str_data = r#"value: 12`
value2: true"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
    dbg!(data)
}

Cette fois-ci ça fonctionne ! 😀

Désérialisation d’une structure de plus d’un champ (approche systématique)

Bon, nous avons réparé notre désérialiser.

Par contre, nous avons posé une hypothèse en présumant de l’ordre des entrées lors de la désérialisation du yaml.

fn main() {
    let str_data = r#"value2: true
value: 12"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
    dbg!(data)
}

Cette fois-ci l’erreur est claire !

Error("value2: invalid type: boolean `true`, expected u8", line: 1, column: 9)

Nous avons supposé l’ordre d’apparition de value et value2 et nous nous sommes trompés !

Il est temps d’utiliser le next_key::<&str>.

Celui-ci va nous renvoyer un résultat de type Result<Option<&str>>.

Tant qu’il existe une clef qui n’a pas été consommée, un Some(&str) est renvoyé. Si la dernière clef a déjà été consommée, c’est un None.

On peut utiliser la structure while let pour déstructurer et boucler sur les résultats de notre next_key.

On utilise également la syntaxe ? pour nous débarrasser de l’éventuelle erreur de désérialisation de la clef.

while let Some(key) = next_key()? {

}

À partir de ce moment, on peut définir deux variables mutables.

let mut value = None::<u8>;
let mut value2 = None::<bool>;

On peut alors venir matcher la clef. Et désérialiser selon le bon type.

match key {
    "value" => {
        value = Some(map.next_value::<u8>()?);
    }
    "value2" => {
        value2 = Some(map.next_value::<bool>()?);
    }
    _ => {
        let _ = map.next_value::<serde::de::IgnoredAny>()?;
    }
}

Finalement, une fois que toutes les entrées ont été désérialisées, l’on peut détecter si les champs de la structure Data,ont correctement été désérialisés.

Si l’un des champs n’a pas été trouvé lors de la désérialisation, on renvoie une erreur.

let value = if let Some(x) = value {
    x
} else {
    return Err(Error::missing_field("value"));
};

let value2 = if let Some(x) = value2 {
    x
} else {
    return Err(Error::missing_field("value2"));
};

struct Data {
    value: u8,
    value2: bool
}

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(DataVisitor);
    }
}

struct DataVisitor;

impl<'de> Visitor<'de> for DataVisitor {
    // Nous allons désérialiser vers la structure Data
    type Value = Data;

    // Défini l'erreur renvoyée en cas de souci
    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("Expecting data")
    }
    
    // On défini la variante map pour notre visiteur
    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        // on initialise les différents champs
        let mut value = None::<u8>;
        let mut value2 = None::<bool>;

        // on boucle sur chaque entrées
        while let Some(key) = map.next_key::<&str>()? {
            match key {
                "value" => {
                    value = Some(map.next_value::<u8>()?);
                }
                "value2" => {
                    value2 = Some(map.next_value::<bool>()?);
                }
                _ => {
                    // on consomme toutes les entrées inconnus
                    // pour éviter des soucis de désérialisation partielle
                    let _ = map.next_value::<serde::de::IgnoredAny>()?;
                }
            }
        }

        // On vérifie que les champs ont bien été désérialisés.
        let value = if let Some(x) = value {
            x
        } else {
            return Err(Error::missing_field("value"));
        };
        let value2 = if let Some(x) = value2 {
            x
        } else {
            return Err(Error::missing_field("value2"));
        };

        Ok(Data {
            value,
            value2
        })
    }
}

Avec cette nouvelle implémentation, à la fois

fn main() {
    let str_data = r#"value: 12`
value2: true"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
}

Et

fn main() {
    let str_data = r#"value2: true`
value: 12"#;
    let data = serde_yaml::from_str::<Data>(str_data)
        .expect("Something goes wrong");
}

Fonctionnent correctement. 😁

Désérialisation depuis d’autres formats

En bonus, on peut aussi désérialiser du JSON sans avoir à changer notre trait Deserialize.

On installe la crate serde_json et sa méthode from_str.

cargo add serde_json

fn main() {
    let str_data = r#"{
    "value" : 12,
    "value2": true
}"#;
    let data = serde_json::from_str::<Data>(str_data)
        .expect("Something goes wrong");
}

C’est la grande force de serde, à partir du moment où l’on définit le trait Deserialize on peut l’utiliser avec, n’importe quel Deserializer.

Composition de structures

Imaginons que l’on souhaite désérialiser vers une structure qui a plutôt cette forme :

struct Person {
    name: String,
    age: u8,
}

struct Data {
    value: u8,
    value2: bool,
    person: Person,
}

On se retrouve avec un champ “person” qui doit également être désérialisé.

Pour cela on implémente le trait Deserialize pour la structure Person.

impl<'de> Visitor<'de> for PersonVisitor {
    type Value = Person;

    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("expecting ")
    }

    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        let mut name = None::<String>;
        let mut age = None::<u8>;

        while let Some(key) = map.next_key::<&str>()? {
            match key {
                "name" => name = Some(map.next_value::<String>()?),
                "age" => age = Some(map.next_value::<u8>()?),
                _ => {
                    map.next_value::<IgnoredAny>()?;
                }
            }
        }

        let name = if let Some(x) = name {
            x
        } else {
            return Err(Error::missing_field("name"));
        };
        let age = if let Some(x) = age {
            x
        } else {
            return Err(Error::missing_field("age"));
        };

        Ok(Person { name, age })
    }
}

impl<'de> Deserialize<'de> for Person {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(PersonVisitor)
    }
}

Je ne détaille pas plus, on est dans la même situation que pour la structure Data.

Puis on modifie le visit_map du trait Visitor du DataVisitor:

fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
where
    A: MapAccess<'de>,
{
    let mut value = None::<u8>;
    let mut value2 = None::<bool>;
    let mut person = None::<Person>;

    while let Some(key) = map.next_key::<&str>()? {
        match key {
            "value" => {
                value = Some(map.next_value::<u8>()?);
            }
            "value2" => {
                value2 = Some(map.next_value::<bool>()?);
            }
            "person" => {
                // On utilise le trait Deserialize de Person
                person = Some(map.next_value::<Person>()?);
            }
            _ => {
                let _ = map.next_value::<serde::de::IgnoredAny>()?;
            }
        }
    }

    let value = if let Some(x) = value {
        x
    } else {
        return Err(Error::missing_field("value"));
    };
    let value2 = if let Some(x) = value2 {
        x
    } else {
        return Err(Error::missing_field("value2"));
    };
    // Le nouveau champ
    let person = if let Some(x) = person {
        x
    } else {
        return Err(Error::missing_field("person"));
    };

    Ok(Data {
        value,
        value2,
        person,
    })
}

On peut alors l’utiliser

pub fn main() {

    let str_data = r#"value2: true
value: 12
person:
  age: 78
  name: "Jane""#;

    let data = serde_yaml::from_str::<Data>(str_data);
    dbg!(data);

    let str_data = r#"{
    "value" : 13,
    "value2": true,
    "person": {
    "name" : "Bob",
    "age" : 42
    }
}"#;
    let data = serde_json::from_str::<Data>(str_data).expect("Something goes wrong");
    dbg!(data);
}

Désérialiser un tableau

Maintenant, nous sommes rodés, on peut commencer à désérialiser ce que l’on veut ! Par exemple, on peut automatiquement désérialiser tout

Vec<T : Deserialize>

Ce qui nous permet de pouvoir faire :

struct Person {
    name: String,
    age: u8,
    addresses: Vec<String>,
}

On modifie le visit_map en conséquence.

fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
where
    A: MapAccess<'de>,
{
    let mut name = None::<String>;
    let mut age = None::<u8>;
    let mut addresses = None::<Vec<String>>;

    while let Some(key) = map.next_key::<&str>()? {
        match key {
            "name" => name = Some(map.next_value::<String>()?),
            "age" => age = Some(map.next_value::<u8>()?),
            "addresses" => {
                // On désérialise le tableau
                addresses = Some(map.next_value::<Vec<String>>()?);
            }
            _ => {
                map.next_value::<IgnoredAny>()?;
            }
        }
    }

    let name = if let Some(x) = name {
        x
    } else {
        return Err(Error::missing_field("name"));
    };
    let age = if let Some(x) = age {
        x
    } else {
        return Err(Error::missing_field("age"));
    };
    let addresses = if let Some(x) = addresses {
        x
    } else {
        return Err(Error::missing_field("addresses"));
    };

    Ok(Person {
        name,
        age,
        addresses,
    })
}

Que l’on utilise ainsi :

fn main() {

    let str_data = r#"
person:
  age: 78
  name: "Jane"
  addresses:
  - "test"
  - test2
"#;

    let data = serde_yaml::from_str::<Data>(str_data);
    dbg!(data);

use serde::de::{Error, IgnoredAny, MapAccess, Visitor};
use serde::{Deserialize, Deserializer};
use std::fmt::Formatter;

#[derive(Debug)]
struct Person {
    name: String,
    age: u8,
    addresses: Vec<String>,
}

#[derive(Debug)]
struct Data {
    person: Person,
}

struct DataVisitor;
struct PersonVisitor;

impl<'de> Visitor<'de> for PersonVisitor {
    type Value = Person;

    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("expecting ")
    }

    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        let mut name = None::<String>;
        let mut age = None::<u8>;
        let mut addresses = None::<Vec<String>>;

        while let Some(key) = map.next_key::<&str>()? {
            match key {
                "name" => name = Some(map.next_value::<String>()?),
                "age" => age = Some(map.next_value::<u8>()?),
                "addresses" => {
                    addresses = Some(map.next_value::<Vec<String>>()?);
                }
                _ => {
                    map.next_value::<IgnoredAny>()?;
                }
            }
        }

        let name = if let Some(x) = name {
            x
        } else {
            return Err(Error::missing_field("name"));
        };
        let age = if let Some(x) = age {
            x
        } else {
            return Err(Error::missing_field("age"));
        };
        let addresses = if let Some(x) = addresses {
            x
        } else {
            return Err(Error::missing_field("addresses"));
        };

        Ok(Person {
            name,
            age,
            addresses,
        })
    }
}

impl<'de> Visitor<'de> for DataVisitor {
    type Value = Data;

    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("Expecting data")
    }

    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {

        let mut value = None::<u8>;
        let mut value2 = None::<bool>;
        let mut person = None::<Person>;

        while let Some(key) = map.next_key::<&str>()? {
            match key {
                "person" => person = Some(map.next_value::<Person>()?),
                _ => {
                    let _ = map.next_value::<IgnoredAny>()?;
                }
            }
        }


        let person = if let Some(x) = person {
            x
        } else {
            return Err(Error::missing_field("person"));
        };

        Ok(Data {
            person,
        })
    }
}

impl<'de> Deserialize<'de> for Person {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(PersonVisitor)
    }
}

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(DataVisitor)
    }
}

pub fn main() {
    let str_data = r#"
person:
  age: 78
  name: "Jane"
  addresses:
  - "test"
  - test2
"#;

    let data = serde_yaml::from_str::<Data>(str_data);
    dbg!(data);

    let str_data = r#"{
    "person": {
        "name" : "Bob",
        "age" : 42,
        "addresses": [
            "test",
            "test2"
        ]
    }
}"#;
    let data = serde_json::from_str::<Data>(str_data).expect("Something goes wrong");
    dbg!(data);
}

Désérialiser une énumération

Une énumération en Rust est un objet complexe, il peut prendre plusieurs formes :

Nous allons tenter de désérialiser la structure suivante :

Elle possède des champs qui se désérialisent sous la forme d’une énumération.

Cette énumération a pour particularité d’avoir une variante possédant un paramètre de type chaîne de caractères.

enum Housing {
    House,
    Flat,
    Other(String),
}

struct Data {
    housing: Housing,
}

Nous allons définir deux formats valides, permettant la sérialisation de ce champ housing.

La première défini cette énumération comme une chaîne de caractère.

housing: house
---
housing: flat
---
housing: other

La seconde sous la forme d’une structure.

housing:
    type: house
---
housing:
    type: flat
---
housing:
    type: other
    details: van

Je passe l’implémentation du trait Deserialize pour la structure Data.

Et on s’attaque tout de suite à l’implémentation de notre trait Deserialize pour l’énumération Housing.

impl<'de> Deserialize<'de> for Housing {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_any(HousingVisitor)
    }
}

On utilise deserialize_any pour gérer le cas visit_str et visit_map.

Puis, on s’attaque à l’implémentation du HousingVisitor

struct HousingVisitor;

impl<'de> Visitor<'de> for HousingVisitor {
    type Value = Housing;

    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("expecting housing")
    }
}

On définit d’abord la méthode visit_str:

fn visit_str<E>(self, kind: &str) -> Result<Self::Value, E>
where
    E: Error,
{
    const VARIANTS: &[&str] = &["house", "flat", "other"];

    match kind.to_lowercase().as_str() {
        "house" => Ok(Housing::House),
        "flat" => Ok(Housing::Flat),
        "other" => Ok(Housing::Other("".to_string())),
        _ => Err(Error::unknown_variant(kind, VARIANTS)),
    }
}

Elle vient réaliser une correspondance entre la chaîne de caractères désérialisée et une variante de notre énumération Housing.

La fonction visit_map ressemble beaucoup à ce que l’on a déjà fait : on vient désérialiser les entrées kind et details.

La différence, c’est que le champ details n’est utilisé que pour la variante Other.

fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
where
    A: MapAccess<'de>,
{
    let mut kind = None::<&str>;
    let mut details = None::<String>;

    while let Some(key) = map.next_key::<&str>()? {
        match key {
            "kind" => kind = Some(map.next_value::<&str>()?),
            "details" => details = map.next_value::<Option<String>>()?,
            _ => {
                map.next_value::<IgnoredAny>()?;
            }
        }
    }

    const VARIANTS: &[&str] = &["house", "flat", "other"];

    if let Some(kind) = kind {
        match kind.to_lowercase().as_str() {
            "house" => Ok(Housing::House),
            "flat" => Ok(Housing::Flat),
            "other" => Ok(Housing::Other(details.unwrap_or_default())),
            _ => Err(Error::unknown_variant(kind, VARIANTS)),
        }
    } else {
        Err(Error::missing_field("kind"))
    }
}

En rassemblant le tout :

use serde::de::{Error, IgnoredAny, MapAccess, Visitor};
use serde::{Deserialize, Deserializer};
use std::fmt::Formatter;

#[derive(Debug)]
enum Housing {
    House,
    Flat,
    Other(String),
}

#[derive(Debug)]
struct Data {
    housing: Housing,
}

struct HousingVisitor;

impl<'de> Visitor<'de> for HousingVisitor {
    type Value = Housing;

    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("expecting housing")
    }

    fn visit_str<E>(self, kind: &str) -> Result<Self::Value, E>
    where
        E: Error,
    {
        const VARIANTS: &[&str] = &["house", "flat", "other"];

        match kind.to_lowercase().as_str() {
            "house" => Ok(Housing::House),
            "flat" => Ok(Housing::Flat),
            "other" => Ok(Housing::Other("".to_string())),
            _ => Err(Error::unknown_variant(kind, VARIANTS)),
        }
    }

    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        let mut kind = None::<&str>;
        let mut details = None::<String>;

        while let Some(key) = map.next_key::<&str>()? {
            match key {
                "kind" => kind = Some(map.next_value::<&str>()?),
                "details" => details = map.next_value::<Option<String>>()?,
                _ => {
                    map.next_value::<IgnoredAny>()?;
                }
            }
        }

        const VARIANTS: &[&str] = &["house", "flat", "other"];

        if let Some(kind) = kind {
            match kind.to_lowercase().as_str() {
                "house" => Ok(Housing::House),
                "flat" => Ok(Housing::Flat),
                "other" => Ok(Housing::Other(details.unwrap_or_default())),
                _ => Err(Error::unknown_variant(kind, VARIANTS)),
            }
        } else {
            Err(Error::missing_field("kind"))
        }
    }
}

struct DataVisitor;

impl<'de> Visitor<'de> for DataVisitor {
    type Value = Data;

    fn expecting(&self, formatter: &mut Formatter) -> std::fmt::Result {
        formatter.write_str("expecting data")
    }

    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        let mut housing = None::<Housing>;
        while let Some(key) = map.next_key()? {
            match key {
                "housing" => housing = Some(map.next_value::<Housing>()?),
                _ => {
                    map.next_value::<IgnoredAny>()?;
                }
            }
        }

        let housing = if let Some(x) = housing {
            x
        } else {
            return Err(Error::missing_field("housing"));
        };

        Ok(Data { housing })
    }
}

impl<'de> Deserialize<'de> for Data {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_map(DataVisitor)
    }
}

impl<'de> Deserialize<'de> for Housing {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_any(HousingVisitor)
    }
}

On peut alors désérialiser nos structures :

fn main() {
    let str_data = r#"
housing: House
"#;

    let data = serde_yaml::from_str::<Data>(str_data);
    dbg!(data);

    let str_data = r#"
housing:
    kind: other
    details: "van"
"#;

    let data = serde_yaml::from_str::<Data>(str_data);
    dbg!(data);
}

Implémentation du trait Serialize

Ce trait est le pendant du trait Deserialize.

Il est nécessaire pour la transformation d’une structure de données Rust en chaîne de caractères en format JSON, TOML, ou YAML par exemple.

On le retrouve dès que l’on souhaite utiliser les méthodes to_string des différents serializers:

• TOML
• JSON
• YAML

Ces trois méthodes possèdent la même signature qui prend en paramètre d’entrée, une référence vers structure de données implémentant le trait Serialize.

Celui-ci nous impose d’implémenter la méthode serialize.

Si on possède une structure comme celle-ci :

enum Housing {
    House,
    Flat,
    Other(String),
}

struct Person {
    name: String,
    age: u8,
    housings: Vec<Housing>,
}

Comme énoncé dans la documentation, il est facile d’implémenter le sérialiseur de notre structure.

impl Serialize for Person {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let mut map_serializer = serializer.serialize_map(Some(3_usize))?;
        map_serializer.serialize_entry("name", &self.name)?;
        map_serializer.serialize_entry("age", &self.age)?;
        map_serializer.serialize_entry("housings", &self.housings)?;
        map_serializer.end()
    }
}

Par contre, le serialize_entry pour “housings” pose souci. En effet, la value doit implémenter Serialize, or l’énumération Housing n’implémente pas ce trait.

Ce qui provoque cette erreur :

the trait bound `Housing: Serialize` is not satisfied
     |
     |     map_serializer.serialize_entry("housings", &self.housings)?;
the trait `Serialize` is not implemented for `Housing ^^^^^^^^^^^^^^ 

Nous allons remédier à cela.

Pour sérialiser notre énumération Housing. Nous allons en faire une structure possédant 2 champs

• kind : sera rempli avec la dénomination sous forme de chaîne de caractères de la variante
• details : il sera seulement rempli dans le cas de la variante Housing::Other

impl Serialize for Housing {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let (kind, details) = match self {
            Housing::House => ("House", ""),
            Housing::Flat => ("Flat", ""),
            Housing::Other(details) => ("Other", details.as_str()),
        };

        let mut map_serializer = serializer.serialize_map(Some(2))?;
        map_serializer.serialize_entry("kind", kind)?;
        map_serializer.serialize_entry("details", details)?;
        map_serializer.end()
    }
}

Ceci fait, nous pouvons alors utiliser notre structure Person dans n’importe quel sérialiseur !

On installe tout le monde

cargo add serde_json serde_yaml toml

Puis, on définit notre structure à sérialiser et on l’utilise dans les sérialiseurs. 😀

fn main() {
    let bob = Person {
        name: "Bob".to_string(),
        age: 36,
        housings: vec![
            Housing::House,
            Housing::Other("van".to_string()),
            Housing::Flat,
            Housing::Other("travel trailer".to_string()),
        ],
    };

    let str_yaml = serde_yaml::to_string(&bob);
    println!("{}", str_yaml.unwrap());

    let str_yaml = serde_json::to_string(&bob);
    println!("{}", str_yaml.unwrap());

    println!();

    let str_yaml = toml::to_string(&bob);
    println!("{}", str_yaml.unwrap());
}

Le code complet

use serde::ser::{SerializeMap, SerializeTupleVariant};
use serde::{Serialize, Serializer};

enum Housing {
    House,
    Flat,
    Other(String),
}

impl Serialize for Housing {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let (kind, details) = match self {
            Housing::House => ("House", ""),
            Housing::Flat => ("Flat", ""),
            Housing::Other(details) => ("Other", details.as_str()),
        };

        let mut map_serializer = serializer.serialize_map(Some(2))?;
        map_serializer.serialize_entry("kind", kind)?;
        map_serializer.serialize_entry("details", details)?;
        map_serializer.end()
    }
}

struct Person {
    name: String,
    age: u8,
    housings: Vec<Housing>,
}

impl Serialize for Person {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let mut map_serializer = serializer.serialize_map(Some(3_usize))?;
        map_serializer.serialize_entry("name", &self.name)?;
        map_serializer.serialize_entry("age", &self.age)?;
        map_serializer.serialize_entry("housings", &self.housings)?;
        map_serializer.end()
    }
}

fn main() {
    let bob = Person {
        name: "Bob".to_string(),
        age: 36,
        housings: vec![
            Housing::House,
            Housing::Other("van".to_string()),
            Housing::Flat,
            Housing::Other("travel trailer".to_string()),
        ],
    };

    let str_yaml = serde_yaml::to_string(&bob);
    println!("{}", str_yaml.unwrap());

    let str_yaml = serde_json::to_string(&bob);
    println!("{}", str_yaml.unwrap());

    println!();

    let str_yaml = toml::to_string(&bob);
    println!("{}", str_yaml.unwrap());
}