craftinginterpreters

Este é o repositório usado para o livro em andamento "Crafting Interpreters". Ele contém o texto Markdown do livro, implementações completas de ambos os intérpretes, bem como o sistema de construção para unir os dois no site final.

Se você encontrar um erro ou tiver uma sugestão, registre um problema aqui. Obrigado!

Contribuindo

Uma das melhores coisas de escrever um livro on-line e divulgá-lo antes de terminar é que pessoas como você foram gentis o suficiente para me dar feedback, apontar erros de digitação e encontrar outros erros ou textos pouco claros.

Se você gostaria de fazer isso, ótimo! Você pode simplesmente registrar bugs aqui no repositório ou enviar uma solicitação pull, se desejar. Se você deseja enviar uma solicitação pull, mas não deseja que o sistema de compilação seja configurado para regenerar o HTML também, não se preocupe. Farei isso quando puxar.

Portas e implementações

Outra forma de se envolver é compartilhando sua própria implementação do Lox. Portas para outras linguagens são particularmente úteis, pois nem todo leitor gosta de Java e C. Sinta-se à vontade para adicionar sua porta ou implementação Lox ao wiki:

• Implementações Lox

Construindo coisas

Sou um mamífero terrivelmente esquecido e sujeito a erros, então automatizei o máximo que pude.

Pré-requisitos

Desenvolvo em uma máquina OS X, mas qualquer sistema POSIX também deve funcionar. Com um pouco de esforço extra, você também conseguirá fazer isso funcionar no Windows, embora eu não possa ajudá-lo muito.

A maior parte do trabalho é orquestrada pela marca. Os scripts de construção, o executor de testes e outros utilitários são todos escritos em Dart. As instruções para instalar o Dart estão aqui. Depois de instalar o Dart e colocá-lo em seu caminho, execute:

$ make get

Isso baixa todos os pacotes usados ​​pelos scripts de construção e teste.

Para compilar os dois intérpretes, você também precisa de um compilador C em seu caminho, bem como javac .

Prédio

Depois de fazer essa configuração, tente:

$ make

Se tudo estiver funcionando, isso irá gerar o site do livro e também compilar os dois intérpretes clox e jlox. Você pode executar qualquer um dos interpretadores diretamente da raiz do repositório:

$ ./clox
$ ./jlox

Hackeando o livro

O Markdown e trechos de código-fonte são integrados no HTML final usando um gerador de site estático escrito à mão que começou como um único pequeno script Python para meu primeiro livro e de alguma forma se transformou em algo que se aproxima de um programa real.

O HTML gerado é confirmado no repositório em site/ . Ele é construído a partir de uma combinação de Markdown para prosa, que reside em book/ , e trechos de código que são tecidos a partir das implementações Java e C em java/ e c/ . (Todos esses comentários engraçados no código-fonte mostram como ele sabe qual trecho vai para onde.)

O script que faz toda a mágica é tool/bin/build.dart . Você pode executar isso diretamente ou executar:

$ make book

Isso gera o site inteiro em um lote. Se você estiver trabalhando nisso de forma incremental, você desejará executar o servidor de desenvolvimento:

$ make serve

Isso executa um pequeno servidor HTTP em localhost com raiz no diretório site/ . Sempre que você solicita uma página, ela regenera todos os arquivos cujas fontes foram alteradas, incluindo arquivos Markdown, arquivos de origem do interpretador, modelos e ativos. Deixe-o continuar em execução, edite os arquivos localmente e atualize seu navegador para ver as alterações.

Construindo os intérpretes

Você pode construir cada intérprete assim:

$ make clox
$ make jlox

Isso constrói a versão final de cada intérprete conforme aparece no final de sua parte no livro.

Você também pode ver a aparência dos intérpretes no final de cada capítulo. (Eu uso isso para ter certeza de que eles estão funcionando mesmo no meio do livro.) Isso é conduzido por um script, tool/bin/split_chapters.dart que usa os mesmos marcadores de comentários para os trechos de código para determinar quais pedaços de código são presente em cada capítulo. Ele pega apenas os trechos que foram vistos no final de cada capítulo e produz uma nova cópia do código-fonte em gen/ , um diretório para o código de cada capítulo. (Essa também é uma maneira mais fácil de visualizar o código-fonte, pois todos os comentários do marcador que distraem foram removidos.)

Então, cada um deles pode ser construído separadamente. Correr:

$ make c_chapters

E no diretório build/ , você obterá um executável para cada capítulo, como chap14_chunks , etc.

$ make java_chapters

Isso compila o código Java em arquivos de classe em build/gen/ em um subdiretório para cada capítulo.

Teste

Eu tenho um conjunto completo de testes Lox que uso para garantir que os intérpretes do livro façam o que devem fazer. Os casos de teste residem em test/ . O programa Dart tool/bin/test.dart é um executor de testes que executa cada um desses arquivos de teste em um interpretador Lox, analisa o resultado e valida se o teste faz o que é esperado.

Existem vários intérpretes nos quais você pode executar os testes:

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

Testando sua implementação

Você está convidado a usar o conjunto de testes e o executor de testes para testar sua própria implementação do Lox. O executor de teste está em tool/bin/test.dart e pode receber um executável de interpretador personalizado para ser executado usando --interpreter . Por exemplo, se você tivesse um interpretador executável em my_code/boblox , você poderia testá-lo como:

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

Você ainda precisa informar qual conjunto de testes executar porque isso determina as expectativas do teste. Se o seu intérprete se comportar como jlox, use "jlox" como nome do conjunto. Se se comportar como clox, use "clox". Se o seu intérprete só estiver completo até o final de um dos capítulos do livro, você poderá usar esse capítulo como suíte, como "chap10_functions". Veja o Makefile para os nomes de todos os capítulos.

Se o seu intérprete precisar de outros argumentos de linha de comando para uso, passe-os para o executor de teste usando --arguments e ele os encaminhará para o seu intérprete.

Layout do repositório

• asset/ – Arquivos Sass e modelos jinja2 usados ​​para gerar o site.
• book/ - Arquivos Markdown para o texto de cada capítulo.
• build/ - Arquivos intermediários e outras saídas de compilação (exceto o próprio site) vão aqui. Não comprometido com o Git.
• c/ – Código fonte do clox, o interpretador escrito em C. Também contém um projeto XCode, se preferir.
• gen/ – Os arquivos de origem Java gerados por GenerateAst.java vão aqui. Não comprometido.
• java/ – Código fonte do jlox, o interpretador escrito em Java.
• note/ – Várias pesquisas, notas, TODOs e outras miscelâneas.
• note/answers – Exemplos de respostas para os desafios. Sem trapaça!
• site/ – O site final gerado. O conteúdo deste diretório reflete diretamente craftinginterpreters.com. A maior parte do conteúdo aqui é gerada por build.py, mas fontes, imagens e JS só residem aqui. Tudo está comprometido, até o conteúdo gerado.
• test/ – Casos de teste para as implementações Lox.
• tool/ – pacote Dart contendo a construção, teste e outros scripts.