Apprendre à encoder/décoder du TOML avec toml-rs

Anthony Defranceschi

Pour réagir au contenu de ce tutoriel, un espace de dialogue vous est proposé sur le forum. Commentez

- Titre : Apprendre à encoder/décoder du TOML avec toml-rs

- Auteur : Anthony Defranceschi

- Parution : 23 avril 2018

- Mise à jour : 18 mai 2018

- Licence : Le contenu de cet article est rédigé par Anthony Defranceschi et est mis à disposition selon les termes de la Licence Creative Commons Attribution 3.0 non transposé. Les logos Developpez.com, en-tête, pied de page, css, et look & feel de l'article sont Copyright ® 2013 Developpez.com.

Sommaire

- I. Introduction

- II. Dépendances requises

- III. Apparition du format

- IV. Et pour toml-rs ?

- V. Décodage

- V-A. Les arguments optionnels

- V-B. Décoder à partir d'un fichier

- VI. Encodage

- VII. Les tables imbriquées

- VII-A. La macro toml!

- VIII. Annexe

- VIII-A. read_toml_file(path, buffer)

- VIII-B. create_toml_file(path, content)

- IX. Conclusion

- X. Note de la Rédaction de Developpez.com

I - Introduction

En passant par la création, la mise en cache d'un squelette dédié aux contrôles et les tests d'intégrités des entrées, la gestion des fichiers de configuration a toujours été(1), plus ou moins, fastidieuse en fonction de l'écosystème avec lequel nous travaillons.

Cependant, il semblerait que toml-rs fasse exception et facilite plutôt les choses, puisqu'elle vient directement s'appuyer sur le typage statique du compilateur pour effectuer automatiquement ces tests pour nous.

Si ça vous intéresse toujours, passons à la suite !

II - Dépendances requises

Avant toute chose, assurez-vous d'avoir déclaré dans votre Cargo.toml:

- La bibliothèque toml, bien entendu ;

- serde_derive, qui est une crate contenant les outils destinés à l'implémentation automatique des structures hôtes(2) ;

- serde.

1. [dependencies]

2. toml = "0.4"

3. serde_derive = "1.0.37"

4. serde = "1.0.37"

III - Apparition du format

TOML est un langage dédié à la représentation des données et vient s'ajouter aux formats « humainement intelligibles » tels que JSON et YAML. Voici un exemple de fichier toml:

1. # This is a TOML document.

3. title = "TOML Example"

5. [owner]

6. name = "Tom Preston-Werner"

7. dob = 1979-05-27T07:32:00-08:00 # First class dates

9. [database]

10. server = "192.168.1.1"

11. ports = [ 8001, 8001, 8002 ]

12. connection_max = 5000

13. enabled = true

15. [servers]

17. # Indentation (tabs and/or spaces) is allowed but not required

18. [servers.alpha]

19. ip = "10.0.0.1"

20. dc = "eqdc10"

22. [servers.beta]

23. ip = "10.0.0.2"

24. dc = "eqdc10"

26. [clients]

27. data = [ ["gamma", "delta"], [1, 2] ]

29. # Line breaks are OK when inside arrays

30. hosts = [

31. "alpha",

32. "omega"

33. ]

Il fut créé et publié par Tom Preston-Werner, le 23 février 2013.

Bien que les spécifications rédigées par ce dernier sont encore jugées immatures, TOML dispose aujourd'hui d'une place importante au sein de l'écosystème Rust et des composants officiels.

IV - Et pour toml-rs ?

toml-rs est donc une implémentation des spécifications dont je parlais dans la précédente section. Cette bibliothèque est destinée au décodage (dé-serialisation) ainsi qu'à l'encodage ( sérialisation) de fichiers .toml, tout simplement.

Pour proposer cette solution, son auteur s'est basé sur le framework serde, spécialisé dans la sérialisation/dé-sérialisation des objets. Vous remarquerez très fréquemment l'utilisation de Serialize et Deserialize qui sont des traits provenant de ce fameux framework. Ils sont dérivés (entendez ici implémentés automatiquement) sur les structures à sérialiser ou celles qui recevront le résultat d'une dé-sérialisation.

V - Décodage

Pour le décodage, toml-rs vous propose la fonction toml::de::from_str et, pour rester dans un cas d'utilisation plutôt simple, je me servirai d'un des exemples de la documentation. Je vous invite à prêter une attention particulière aux quelques commentaires ajoutés dans l'exemple.

1. #[macro_use]

2. extern crate serde_derive;

3. extern crate toml;

5. // Le scope racine de votre fichier toml. Contiendra les tables

6. // s'il y en a.

7. #[derive(Deserialize)]

8. struct Config {

9. title: String,

10. owner: Owner,

11. }

12. // Une table, non optionnelle, présente dans le scope racine.

13. #[derive(Deserialize)]

14. struct Owner {

15. name: String,

16. }

18. fn main() {

19. let config: Config = toml::from_str(r#"

20. title = 'TOML Example'

22. [owner]

23. name = 'Lisa'

24. "#).unwrap();

26. assert_eq!(config.title, "TOML Example");

27. assert_eq!(config.owner.name, "Lisa");

28. }

V-A - Les arguments optionnels

Comme on peut le constater, le fichier de configuration est représenté par la structure Config. Chaque champ de cette dernière peut être soit une variable contenue dans le scope racine, soit une table contenant elle-même d'autres champs (variables). Il est alors possible de rendre ces tables optionnelles.

En reprenant l'exemple précédent, si nous voulions rendre la table Owner optionnelle, il suffirait de la déclarer comme telle dans le code. Ce qui donnerait quelque chose comme ceci:

1. #[derive(Deserialize)]

2. // Le scope racine de votre fichier toml. Contiendra les tables

3. // s'il y en a.

4. struct Config {

5. title: String,

6. owner: Option<Owner>,

7. }

Suite à cette modification, rien ne nous empêcherait d'écrire le toml suivant:

1. fn main() {

2. let config: Config = toml::from_str(r#"

3. title = 'TOML Example'

4. "#).unwrap(); // Nous pouvons nous permettre de ne pas

5. // déclarer la table `[owner]`, puisque désormais optionnelle.

6. assert_eq!(config.title, "TOML Example");

7. // Cette assertion est également modifiée.

8. // `config.owner` étant wrappé dans un conteneur

9. // nous pouvons tester si la table existe ou non.

10. assert_eq!(config.owner, None);

11. }

J’insiste sur le fait que les champs peuvent également être optionnels. Nous aurions très bien pu déclarer Owner.name comme un champ optionnel, de la même manière que la table Owner elle-même.

1. #[derive(Deserialize)]

2. struct Owner {

3. name: Option<String>,

4. }

Mais ça n’aurait que très peu d’intérêt, en l’occurrence.

V-B - Décoder à partir d'un fichier

Vous avez sans doute remarqué que toml fait abstraction de la provenance des ressources que ses outils vont traiter (i.e. les fonctions dédiées au parsing n'acceptent rien d'autres que des chaînes de caractères et des octets). Les deux fonctions proposées sont :

1. &str, par le biais de toml::de::from_str ;

2. &[u8], par le biais de toml::de::from_slice.

Dans les deux cas, si vous souhaitez récupérer du toml depuis un fichier (ou un stream quelconque), il faudra se débrouiller.

1. let meat = {

2. let mut file_path: path::PathBuf = path::PathBuf::new();

3. // On admettra ici que votre fichier est à la racine du projet.

4. file_path.push(env::current_dir().unwrap().as_path());

5. file_path.push("my_file.toml");

6. let mut configuration_file: fs::File = fs::OpenOptions::new()

7. .read(true)

8. .open(file_path.as_path())

9. .expect("Cannot open the configuration file");

11. // tip: Si vous souhaitez récupérer le contenu de votre fichier

12. // sous forme d'octets, il suffit de remplacer la ligne 16 par celle-ci:

13. // `let mut raw_content: Vec<u8>: vec![];`

15. let mut stringified_content: String = String::new();

17. // Vous devrez également modifier la méthode utilisée ici par:

18. // `configuration_file.read_to_end(&mut raw_content)`

19. match configuration_file.read_to_string(&mut stringified_content) {

20. Ok(bytes) => println!("{} bytes has been appended to buffer.", bytes),

21. Err(error) => panic!(

22. "

23. The data in this stream is not valid UTF-8.\n

24. See error: '{}'

25. ",

26. error

27. ),

28. }

29. stringified_content

30. };

32. // Remplacez ici `from_str` par `from_slice`

33. // et modifiez votre paramètre en conséquence.

34. let config_content: Config = toml::from_str(meat.as_str())

35. .expect("Something went wrong");

Par ailleurs, vous pouvez consulter l'annexe pour y retrouver une fonction se chargeant d'effectuer ces traitements pour vous.

VI - Encodage

L'encodage se fait tout aussi simplement que le décodage grâce à toml::to_string. Si l'on reprend les structures précédentes, cela donnerait…

1. // Attention à bien dériver le trait `Serialize`.

2. #[derive(Debug, Serialize)]

3. struct Config {

4. title: String,

5. owner: Owner,

6. }

7. // Attention à bien dériver le trait `Serialize` ici aussi.

8. #[derive(Debug, Serialize)]

9. struct Owner {

10. name: String,

11. }

1. let meat = Config {

2. title: "Here's my configuration title!".to_owned(),

3. owner: Owner {

4. name: "Songbird".to_owned(),

5. },

6. };

8. let config_content: String = toml::to_string(&meat)

9. .expect("Something went wrong");

…c’est tout ! Sauf si vous voulez écrire le dump dans un de vos fichiers, encore une fois.

1. let meat = Config {

2. title: "Here's my configuration title!".to_owned(),

3. owner: Owner {

4. name: "Songbird".to_owned(),

5. },

6. };

8. let config_content: String = toml::to_string(&meat)

9. .expect("Something went wrong");

11. let mut file_path: path::PathBuf = path::PathBuf::new();

12. file_path.push(env::current_dir().unwrap().as_path());

13. file_path.push("a_file.toml");

15. let mut configuration_file: fs::File = fs::OpenOptions::new()

16. .write(true)

17. .create(true)

18. .open(file_path.as_path())

19. .expect("Cannot open the configuration file");

21. // On récupère ce que `toml` vient de produire.

22. let bytes: &[u8] = &config_content.into_bytes();

24. configuration_file

25. .write_all(bytes)

26. .expect("An error was occurred");

VII - Les tables imbriquées

Dans des scénarios plus « complexes », vous pourriez avoir besoin d'imbriquer des tables, comme le stipulent les spécifications du langage. Rien de plus simple !

1. extern crate toml;

2. #[macro_use]

3. extern crate serde_derive;

5. #[derive(Debug, Serialize)]

6. struct ConfigFile {

7. owner: Owner,

8. // Le fichier ne peut contenir qu'une seule table `[team]`.

9. team: Option<Team>,

10. }

12. #[derive(Debug, Serialize)]

13. struct Owner {

14. // Champ obligatoire.

15. name: String,

16. // Champ obligatoire.

17. mail: String,

18. }

20. #[derive(Debug, Serialize)]

21. struct Team {

22. // La table `[team]` peut disposer de

23. // plusieurs sous-tables `[[team.members]]`.

24. members: Vec<Member>,

25. }

27. #[derive(Debug, Serialize)]

28. struct Member {

29. // Champ obligatoire.

30. name: String,

31. // Champ obligatoire.

32. job: String,

33. // Champ optionnel.

34. mail: Option<String>,

35. }

37. let meat = ConfigFile {

38. owner: Owner {

39. name: "Songbird".to_owned(),

40. mail: "johndoe@johndoe.com".to_owned(),

41. },

42. team: Some(Team {

43. members: vec![

44. Member {

45. name: "Alice".to_owned(),

46. job: "Tech leader".to_owned(),

47. mail: Some("resp@abc.xyz".to_owned()),

48. },

49. Member {

50. name: "Bob".to_owned(),

51. job: "Developer".to_owned(),

52. mail: None,

53. },

54. Member {

55. name: "John".to_owned(),

56. job: "Community Manager".to_owned(),

57. mail: None,

58. },

59. ],

60. }),

61. };

Cette fois-ci, je vous épargne le code pour écrire tout ceci dans un fichier, passons au résultat :

1. [owner]

2. name = "Songbird"

3. mail = "johndoe@johnedoe.com"

4. [[team.members]]

5. name = "Alice"

6. job = "Tech leader"

7. mail = "resp@abc.xyz"

9. [[team.members]]

10. name = "Bob"

11. job = "Developer"

13. [[team.members]]

14. name = "John"

15. job = "Community Manager"

VII-A - La macro toml!

Toutefois, on notera rapidement quelque chose: l'écriture commence à être plutôt lourde. En réponse à cela, la bibliothèque dispose d'une macro modestement nommée toml!. Ce qui nous donnera, après modification:

1. #[macro_use]

2. extern crate toml;

3. #[macro_use]

4. extern crate serde_derive;

6. // Certains de ces imports sont à supprimer si

7. // vous n'effectuez aucune opération d'entrée/sortie.

8. use std::{convert, env, fs, io, io::prelude::*, path};

10. let meat = toml! {

11. [owner]

12. name = "Songbird"

13. mail = "johndoe@johnedoe.com"

14. [[team.members]]

15. name = "Alice"

16. job = "Tech leader"

17. mail = "resp@abc.xyz"

19. [[team.members]]

20. name = "Bob"

21. job = "Developer"

23. [[team.members]]

24. name = "John"

25. job = "Community Manager"

26. };

Le dump sera strictement le même. :)

Bien qu'il existe une manière plus simple de rédiger du toml, les structures précédemment déclarées ne deviennent pas inutiles. Elles vous permettront de vous assurer de l'intégrité de vos fichiers dans le cas d'une éventuelle modification effectuée par un utilisateur.

VIII - Annexe

J'ai écrit deux fonctions, plutôt basiques, permettant de rendre l'écriture (ou la lecture) des fichiers toml moins rébarbative. Grâce à std::convert::AsRef, elles supportent tous les types ayant implémenté le trait pour la structure std::path::Path.

Ces fonctions n'ont pas d'autres prétentions que de servir d'exemples ou d'outils « de départ » pour tester de petites choses de votre côté.

VIII-A - read_toml_file(path, buffer)

Lit le fichier path, stocke le contenu du fichier dans le tampon buffer et renvoie une instance de la structure censée représenter votre fichier toml. Concernant les erreurs vous ne pourrez rattraper que celles lancées par toml::from_str. C'est le point noir de cette fonction, vous ne pourrez vous en servir que pour empêcher l'exécution d'une partie, plus importante, de votre programme (par exemple dans le cas où vous ne souhaitez pas que l'utilisateur final se serve de votre programme, sans avoir créé un fichier de configuration au préalable). C'est à modifier en fonction des besoins.

1. fn read_toml_file<'a, 'de, P: ?Sized, T>(path: &'a P, buffer: &'de mut String) -> Result<T, Error>

2. where

3. P: convert::AsRef<path::Path>,

4. T: Deserialize<'de>,

5. {

6. let mut configuration_file: fs::File = fs::OpenOptions::new()

7. .read(true)

8. .open(path)

9. .expect("Cannot read the configuration file");

10. match configuration_file.read_to_string(buffer) {

11. Ok(bytes) => {

12. println!("{} bytes has been appended to buffer.", bytes);

13. toml::from_str(buffer.as_str())

14. }

15. Err(error) => panic!(

16. "

17. The data in this stream is not valid UTF-8.\n

18. See error: '{}'

19. ",

20. error

21. ),

22. }

23. }

Exemple

1. let mut file_path: path::PathBuf = path::PathBuf::new();

3. file_path.push(env::current_dir().unwrap().as_path());

4. file_path.push("my_file.toml");

5. let mut buffer = String::new();

6. let config_content: Config = read_toml_file(&file_path, &mut buffer)

7. .expect("Something went wrong");

8. println!("Your config object: {:#?}", config_content);

Résultat

1. 246 bytes has been appended to buffer.

2. Your config object: Config {

3. projects: [

4. ProjectConfig {

5. project_home: "my/home/",

6. project_root: "my_directory",

7. subroots: Some(

8. [

9. SubrootConfig {

10. path: "my/path/file"

11. },

12. SubrootConfig {

13. path: "my/path/file"

14. }

15. ]

16. )

17. },

18. ProjectConfig {

19. project_home: "another/home/",

20. project_root: "another_directory",

21. subroots: None

22. }

23. ]

24. }

Les structures ne sont pas identiques à celles présentées tout au long du billet, mais le principe est le même.

VIII-B - create_toml_file(path, content)

Écrit le contenu content dans le chemin path soumis. content est transféré à l'appel de cette fonction.

Rien d'extraordinaire pour celle-ci, elle aurait très bien pu s'appeler create_file puisqu'elle nous épargne simplement les lignes de préparation des accès et de l'écriture. Toutes les erreurs lancées par cette fonction sont gérables, en revanche.

1. fn create_toml_file<'a, P: ?Sized>(path: &'a P, content: String) -> io::Result<()>

2. where

3. P: convert::AsRef<path::Path>,

4. {

5. let mut toml_file: fs::File = fs::OpenOptions::new()

6. .write(true)

7. .create(true)

8. .open(path)?;

10. let bytes: &[u8] = &content.into_bytes();

12. toml_file.write_all(bytes)

13. }

Exemple

1. let meat: toml::Value = toml! {

2. [owner]

3. name = "Songbird"

4. mail = "johndoe@johnedoe.com"

5. [[team.members]]

6. name = "Alice"

7. job = "Tech leader"

8. mail = "resp@abc.xyz"

10. [[team.members]]

11. name = "Bob"

12. job = "Developer"

14. [[team.members]]

15. name = "John"

16. job = "Community Manager"

17. };

19. let config_content: String = toml::to_string(&meat)

20. .expect("Something went wrong");

21. let mut file_path: path::PathBuf = path::PathBuf::new();

23. file_path.push(env::current_dir().unwrap().as_path());

24. file_path.push("a_file.toml");

26. assert!(create_toml_file(&file_path, config_content).is_ok());

IX - Conclusion

Il me semble que nous en ayons terminé !

Globalement, la seule chose à retenir est d'utiliser systématiquement(3) la macro toml! pour écrire le squelette initial du fichier et déclarer les structures respectives à chaque table uniquement pour la lecture et la vérification des entrées. Amusez-vous bien ! :)

Les logos Rust et Cargo (aux formats matriciel et vectoriel) sont la propriété de Mozilla et sont distribués selon les termes de la licence Creative Commons Attribution (CC-BY).

X - Note de la Rédaction de Developpez.com

Nous tenons à remercier f-leb pour la relecture orthographique de ce tutoriel.

(1)Selon moi

(2)Les structures dont on souhaite encoder ou décoder les données.

(3)Sauf si vous avez une bonne raison de ne pas le faire.