craftinginterpreters

Il s'agit du dépôt utilisé pour le livre en cours "Crafting Interpreters". Il contient le texte Markdown du livre, les implémentations complètes des deux interprètes, ainsi que le système de construction permettant de combiner les deux dans le site final.

Si vous trouvez une erreur ou avez une suggestion, veuillez signaler un problème ici. Merci!

Contribuer

L'une des meilleures choses à propos de l'écriture d'un livre en ligne et de sa publication avant qu'il ne soit terminé est que des gens comme vous ont eu la gentillesse de me faire part de leurs commentaires, de signaler les fautes de frappe et de trouver d'autres erreurs ou du texte peu clair.

Si vous souhaitez faire ça, super ! Vous pouvez simplement déposer des bogues ici sur le dépôt ou envoyer une pull request si vous le souhaitez. Si vous souhaitez envoyer une pull request, mais que vous ne souhaitez pas également que le système de construction soit configuré pour régénérer le code HTML, ne vous inquiétez pas. Je ferai ça quand je l'aurai rentré.

Ports et implémentations

Une autre façon de vous impliquer est de partager votre propre implémentation de Lox. Les ports vers d'autres langages sont particulièrement utiles puisque tous les lecteurs n'aiment pas Java et C. N'hésitez pas à ajouter votre port ou implémentation Lox au wiki :

• Implémentations Lox

Trucs de construction

Je suis un mammifère terriblement oublieux et sujet aux erreurs, j'ai donc automatisé autant que possible.

Conditions préalables

Je développe sur une machine OS X, mais n'importe quel système POSIX devrait également fonctionner. Avec un petit effort supplémentaire, vous devriez également pouvoir faire fonctionner cela sous Windows, même si je ne peux pas beaucoup vous aider.

La majeure partie du travail est orchestrée par make. Les scripts de build, l'exécuteur de test et d'autres utilitaires sont tous écrits dans Dart. Les instructions pour installer Dart sont ici. Une fois Dart installé et sur votre chemin, exécutez :

$ make get

Cela télécharge tous les packages utilisés par les scripts de build et de test.

Afin de compiler les deux interpréteurs, vous avez également besoin d'un compilateur C sur votre chemin ainsi que javac .

Bâtiment

Une fois que vous avez cette configuration, essayez :

$ make

Si tout fonctionne, cela générera le site du livre ainsi que la compilation des deux interprètes clox et jlox. Vous pouvez exécuter l’un ou l’autre interpréteur directement à partir de la racine du dépôt :

$ ./clox
$ ./jlox

Piratage du livre

Le Markdown et les extraits de code source sont intégrés dans le HTML final à l'aide d'un générateur de site statique écrit à la main qui a commencé comme un petit script Python pour mon premier livre et est devenu en quelque sorte quelque chose se rapprochant d'un vrai programme.

Le HTML généré est validé dans le dépôt sous site/ . Il est construit à partir d'une combinaison de Markdown pour la prose, qui se trouve dans book/ , et d'extraits de code intégrés à partir des implémentations Java et C dans java/ et c/ . (Tous ces commentaires amusants dans le code source lui permettent de savoir quel extrait va où.)

Le script qui fait toute la magie est tool/bin/build.dart . Vous pouvez l'exécuter directement ou exécuter :

$ make book

Cela génère l'intégralité du site en un seul lot. Si vous travaillez dessus de manière incrémentielle, vous souhaiterez exécuter le serveur de développement :

$ make serve

Cela exécute un petit serveur HTTP sur localhost enraciné dans le répertoire site/ . Chaque fois que vous demandez une page, il régénère tous les fichiers dont les sources ont été modifiées, y compris les fichiers Markdown, les fichiers sources de l'interpréteur, les modèles et les ressources. Laissez-le simplement fonctionner, modifiez les fichiers localement et actualisez votre navigateur pour voir les modifications.

Construire les interprètes

Vous pouvez construire chaque interpréteur comme ceci :

$ make clox
$ make jlox

Ceci construit la version finale de chaque interprète telle qu'elle apparaît à la fin de sa partie dans le livre.

Vous pouvez également voir à quoi ressemblent les interprètes à la fin de chaque chapitre. (J'utilise ceci pour m'assurer qu'ils fonctionnent même au milieu du livre.) Ceci est piloté par un script, tool/bin/split_chapters.dart qui utilise les mêmes marqueurs de commentaires pour les extraits de code afin de déterminer quels morceaux de code sont présents dans chaque chapitre. Il ne prend que les extraits vus à la fin de chaque chapitre et produit une nouvelle copie de la source dans gen/ , un répertoire pour le code de chaque chapitre. (Il s'agit également d'un moyen plus simple d'afficher le code source, car tous les commentaires de marqueurs gênants ont été supprimés.)

Ensuite, chacun d’eux peut être construit séparément. Courir:

$ make c_chapters

Et dans le répertoire build/ , vous obtiendrez un exécutable pour chaque chapitre, comme chap14_chunks , etc. De même :

$ make java_chapters

Ceci compile le code Java dans des fichiers de classe dans build/gen/ dans un sous-répertoire pour chaque chapitre.

Essai

J'ai une suite complète de tests Lox que j'utilise pour m'assurer que les interprètes du livre font ce qu'ils sont censés faire. Les cas de test vivent dans test/ . Le programme Dart tool/bin/test.dart est un exécuteur de tests qui exécute chacun de ces fichiers de test sur un interpréteur Lox, analyse le résultat et valide que le test fait ce qu'il est censé faire.

Il existe différents interprètes sur lesquels vous pouvez exécuter les tests :

$ make test       # The final versions of clox and jlox.
$ make test_clox  # The final version of clox.
$ make test_jlox  # The final version of jlox.
$ make test_c     # Every chapter's version of clox.
$ make test_java  # Every chapter's version of jlox.
$ make test_all   # All of the above.

Tester votre implémentation

Vous êtes invités à utiliser la suite de tests et le lanceur de tests pour tester votre propre implémentation Lox. Le lanceur de test se trouve dans tool/bin/test.dart et peut recevoir un exécutable d'interpréteur personnalisé à exécuter à l'aide de --interpreter . Par exemple, si vous aviez un exécutable d'interpréteur sur my_code/boblox , vous pourriez le tester comme :

$ dart tool/bin/test.dart clox --interpreter my_code/boblox

Vous devez toujours lui indiquer quelle suite de tests exécuter car cela détermine les attentes des tests. Si votre interprète doit se comporter comme jlox, utilisez "jlox" comme nom de suite. S'il se comporte comme Clox, utilisez "clox". Si votre interprète n'est complet que jusqu'à la fin d'un des chapitres du livre, vous pouvez utiliser ce chapitre comme suite, comme "chap10_functions". Voir le Makefile pour les noms de tous les chapitres.

Si votre interprète a besoin d'autres arguments de ligne de commande, transmettez-les au programme d'exécution du test à l'aide --arguments et il les transmettra à votre interprète.

Disposition du référentiel

• asset/ – Fichiers Sass et modèles jinja2 utilisés pour générer le site.
• book/ - Fichiers Markdown pour le texte de chaque chapitre.
• build/ - Les fichiers intermédiaires et autres résultats de build (à l'exception du site lui-même) vont ici. Non engagé envers Git.
• c/ – Code source de clox, l'interpréteur écrit en C. Contient également un projet XCode, si c'est votre truc.
• gen/ – Les fichiers source Java générés par GenerateAst.java vont ici. Pas engagé.
• java/ – Code source de jlox, l'interpréteur écrit en Java.
• note/ – Diverses recherches, notes, TODO et autres divers.
• note/answers – Exemples de réponses aux défis. Pas de triche !
• site/ – Le site final généré. Le contenu de ce répertoire reflète directement craftinginterpreters.com. La plupart du contenu ici est généré par build.py, mais les polices, les images et le JS ne résident qu'ici. Tout est engagé, même le contenu généré.
• test/ – Cas de test pour les implémentations Lox.
• tool/ – Package Dart contenant la construction, le test et d’autres scripts.