craftinginterpreters

Este es el repositorio utilizado para el libro en progreso "Crafting Interpreters". Contiene el texto Markdown del libro, implementaciones completas de ambos intérpretes, así como el sistema de construcción para unir los dos en el sitio final.

Si encuentra un error o tiene una sugerencia, presente un problema aquí. ¡Gracias!

Contribuyendo

Una de las mejores cosas de escribir un libro en línea y publicarlo antes de terminarlo es que personas como usted han tenido la amabilidad de darme comentarios, señalar errores tipográficos y encontrar otros errores o texto poco claro.

Si quieres hacer eso, ¡genial! Puede simplemente presentar errores aquí en el repositorio o enviar una solicitud de extracción si así lo desea. Si desea enviar una solicitud de extracción, pero no desea configurar el sistema de compilación para regenerar el HTML también, no se preocupe. Lo haré cuando lo introduzca.

Puertos e implementaciones

Otra forma de participar es compartiendo su propia implementación de Lox. Los puertos a otros lenguajes son particularmente útiles ya que no a todos los lectores les gustan Java y C. Siéntase libre de agregar su puerto o implementación de Lox a la wiki:

• Implementaciones de Lox

Cosas de construcción

Soy un mamífero terriblemente olvidadizo y propenso a errores, así que automaticé todo lo que pude.

Requisitos previos

Desarrollo en una máquina OS X, pero cualquier sistema POSIX también debería funcionar. Con un poco de esfuerzo extra, deberías poder hacer que esto funcione también en Windows, aunque no puedo ayudarte mucho.

La mayor parte del trabajo está orquestado por marca. Los scripts de compilación, el ejecutor de pruebas y otras utilidades están escritos en Dart. Las instrucciones para instalar Dart están aquí. Una vez que haya instalado Dart y esté en su camino, ejecute:

$ make get

Esto descarga todos los paquetes utilizados por los scripts de compilación y prueba.

Para compilar los dos intérpretes, también necesita un compilador de C en su ruta, así como javac .

Edificio

Una vez que tengas esa configuración, intenta:

$ make

Si todo funciona, eso generará el sitio para el libro y también compilará los dos intérpretes clox y jlox. Puede ejecutar cualquiera de los intérpretes directamente desde la raíz del repositorio:

$ ./clox
$ ./jlox

Hackear el libro

El Markdown y los fragmentos de código fuente se entrelazan en el HTML final utilizando un generador de sitios estáticos escrito a mano que comenzó como un pequeño script de Python para mi primer libro y de alguna manera creció hasta convertirse en algo parecido a un programa real.

El HTML generado se confirma en el repositorio en site/ . Está construido a partir de una combinación de Markdown para prosa, que se encuentra en book/ , y fragmentos de código entrelazados a partir de las implementaciones de Java y C en java/ y c/ . (Todos esos comentarios divertidos en el código fuente son la forma en que sabe qué fragmento va a dónde).

El script que hace toda la magia es tool/bin/build.dart . Puedes ejecutarlo directamente o ejecutar:

$ make book

Eso genera todo el sitio en un solo lote. Si está trabajando en ello de forma incremental, querrá ejecutar el servidor de desarrollo:

$ make serve

Esto ejecuta un pequeño servidor HTTP en el host local con raíz en el directorio site/ . Cada vez que solicita una página, esta regenera cualquier archivo cuyas fuentes hayan sido modificadas, incluidos archivos Markdown, archivos fuente de intérprete, plantillas y activos. Simplemente deje que siga ejecutándose, edite archivos localmente y actualice su navegador para ver los cambios.

Construyendo los intérpretes

Puedes construir cada intérprete de esta manera:

$ make clox
$ make jlox

Esto construye la versión final de cada intérprete tal como aparece al final de su parte en el libro.

También puedes ver cómo lucen los intérpretes al final de cada capítulo. (Utilizo esto para asegurarme de que estén funcionando incluso en la mitad del libro). Esto está controlado por un script, tool/bin/split_chapters.dart que usa los mismos marcadores de comentarios para los fragmentos de código para determinar qué fragmentos de código son presente en cada capítulo. Toma solo los fragmentos que se han visto al final de cada capítulo y produce una nueva copia de la fuente en gen/ , un directorio para el código de cada capítulo. (Estas también son una forma más fácil de ver el código fuente, ya que se han eliminado todos los comentarios de los marcadores que distraen).

Luego, cada uno de ellos se puede construir por separado. Correr:

$ make c_chapters

Y en el directorio build/ , obtendrás un ejecutable para cada capítulo, como chap14_chunks , etc. Del mismo modo:

$ make java_chapters

Esto compila el código Java en archivos de clase en build/gen/ en un subdirectorio para cada capítulo.

Pruebas

Tengo un conjunto de pruebas Lox completo que utilizo para asegurarme de que los intérpretes del libro hagan lo que se supone que deben hacer. Los casos de prueba viven en test/ . La tool/bin/test.dart es un ejecutor de pruebas que ejecuta cada uno de esos archivos de prueba en un intérprete Lox, analiza el resultado y valida que la prueba haga lo que se espera que haga.

Hay varios intérpretes contra los que puede ejecutar las pruebas:

$ 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.

Probando su implementación

Le invitamos a utilizar el conjunto de pruebas y el ejecutor de pruebas para probar su propia implementación de Lox. El ejecutor de pruebas está en tool/bin/test.dart y se le puede proporcionar un ejecutable de intérprete personalizado para ejecutar usando --interpreter . Por ejemplo, si tuviera un intérprete ejecutable en my_code/boblox , podría probarlo así:

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

Aún necesita decirle qué conjunto de pruebas ejecutar porque eso determina las expectativas de la prueba. Si su intérprete debe comportarse como jlox, utilice "jlox" como nombre de la suite. Si se comporta como clox, utilice "clox". Si su intérprete solo está completo hasta el final de uno de los capítulos del libro, puede usar ese capítulo como conjunto, como "chap10_functions". Consulte el Makefile para conocer los nombres de todos los capítulos.

Si su intérprete necesita que se le pasen otros argumentos de línea de comando para usarlos, páselos al ejecutor de pruebas usando --arguments y los reenviará a su intérprete.

Diseño del repositorio

• asset/ : archivos Sass y plantillas jinja2 utilizados para generar el sitio.
• book/ - Archivos Markdown para el texto de cada capítulo.
• build/ : los archivos intermedios y otros resultados de la compilación (excepto el sitio en sí) van aquí. No comprometido con Git.
• c/ – Código fuente de clox, el intérprete escrito en C. También contiene un proyecto XCode, si eso es lo tuyo.
• gen/ – Los archivos fuente de Java generados por GenerateAst.java van aquí. No comprometido.
• java/ – Código fuente de jlox, el intérprete escrito en Java.
• note/ – Investigaciones diversas, notas, TODO y otras misceláneas.
• note/answers : ejemplos de respuestas para los desafíos. ¡Sin trampas!
• site/ – El sitio final generado. El contenido de este directorio refleja directamente craftinginterpreters.com. La mayor parte del contenido aquí es generado por build.py, pero las fuentes, imágenes y JS solo se encuentran aquí. Todo está comprometido, incluso el contenido generado.
• test/ – Casos de prueba para las implementaciones de Lox.
• tool/ : paquete Dart que contiene los scripts de compilación, prueba y otros.