craftinginterpreters

Это репозиторий, используемый для незавершенной книги «Crafting Interpreters». Он содержит текст книги в формате Markdown, полные реализации обоих интерпретаторов, а также систему сборки, позволяющую объединить их в окончательный сайт.

Если вы обнаружили ошибку или у вас есть предложение, пожалуйста, сообщите о проблеме здесь. Спасибо!

Содействие

Одна из самых лучших особенностей написания книги в Интернете и ее размещения до того, как она будет готова, — это то, что такие люди, как вы, были достаточно любезны, чтобы оставить мне отзыв, указать на опечатки и найти другие ошибки или неясный текст.

Если вы хотите это сделать, отлично! Вы можете просто сообщить об ошибках здесь, в репозитории, или отправить запрос на включение, если хотите. Если вы хотите отправить запрос на включение, но не хотите, чтобы система сборки также настраивала регенерацию HTML, не беспокойтесь об этом. Я сделаю это, когда вытащу его.

Порты и реализации

Другой способ принять участие — поделиться своей собственной реализацией Lox. Порты на другие языки особенно полезны, поскольку не каждому читателю нравятся Java и C. Не стесняйтесь добавлять свой порт или реализацию Lox в вики:

• Реализации Lox

Строительные материалы

Я ужасно забывчивое и склонное к ошибкам млекопитающее, поэтому автоматизировал все, что мог.

Предварительные условия

Я разрабатываю на машине OS X, но любая система POSIX тоже должна работать. Приложив немного дополнительных усилий, вы сможете заставить это работать и в Windows, хотя я мало чем могу вам помочь.

Большую часть работы организует make. Скрипты сборки, средство запуска тестов и другие утилиты написаны на Dart. Инструкции по установке Dart находятся здесь. После того, как Dart установлен и находится на вашем пути, запустите:

$ make get

При этом загружаются все пакеты, используемые сценариями сборки и тестирования.

Чтобы скомпилировать два интерпретатора, вам также понадобится компилятор C на вашем пути, а также javac .

Здание

После того, как вы настроили эту настройку, попробуйте:

$ make

Если все работает, будет создан сайт для книги, а также скомпилированы два интерпретатора clox и jlox. Вы можете запустить любой интерпретатор прямо из корня репо:

$ ./clox
$ ./jlox

Взлом книги

Markdown и фрагменты исходного кода объединяются в окончательный HTML-код с помощью написанного от руки генератора статических сайтов, который начинался как один крошечный скрипт Python для моей первой книги и каким-то образом превратился во что-то, напоминающее настоящую программу.

Сгенерированный HTML сохраняется в репозитории site/ . Он построен на основе комбинации Markdown для прозы, которая находится в book/ , и фрагментов кода, вплетенных из реализаций Java и C в java/ и c/ . (Все эти забавно выглядящие комментарии в исходном коде позволяют узнать, какой фрагмент куда идет.)

Сценарий, который творит всю магию, — tool/bin/build.dart . Вы можете запустить это напрямую или запустить:

$ make book

Это генерирует весь сайт за один пакет. Если вы работаете над этим постепенно, вам нужно запустить сервер разработки:

$ make serve

Это запускает небольшой HTTP-сервер на локальном хосте, расположенный в каталоге site/ . Каждый раз, когда вы запрашиваете страницу, она заново создает все файлы, источники которых были изменены, включая файлы Markdown, исходные файлы интерпретатора, шаблоны и ресурсы. Просто позвольте этому продолжать работать, редактируйте файлы локально и обновите браузер, чтобы увидеть изменения.

Создание переводчиков

Вы можете построить каждый интерпретатор следующим образом:

$ make clox
$ make jlox

При этом создается окончательная версия каждого интерпретатора в том виде, в каком она представлена ​​в конце соответствующей части книги.

Вы также можете увидеть, как выглядят переводчики, в конце каждой главы. (Я использую это, чтобы убедиться, что они работают даже в середине книги.) Это осуществляется с помощью tool/bin/split_chapters.dart , который использует одни и те же маркеры комментариев для фрагментов кода, чтобы определить, какие фрагменты кода являются присутствует в каждой главе. Он берет только те фрагменты, которые были просмотрены в конце каждой главы, и создает новую копию исходного кода в gen/ , по одному каталогу для кода каждой главы. (Это также более простой способ просмотра исходного кода, поскольку из них удалены все отвлекающие комментарии-маркеры.)

Затем каждый из них можно построить отдельно. Бегать:

$ make c_chapters

А в каталоге build/ вы получите исполняемый файл для каждой главы, например chap14_chunks и т. д. Аналогично:

$ make java_chapters

При этом код Java компилируется в файлы классов в build/gen/ в подкаталоге для каждой главы.

Тестирование

У меня есть полный набор тестов Lox, который я использую, чтобы убедиться, что переводчики в книге делают то, что они должны делать. Тестовые примеры находятся в test/ . Программный tool/bin/test.dart — это средство запуска тестов, которое запускает каждый из этих тестовых файлов в интерпретаторе Lox, анализирует результат и проверяет, что тест выполняет то, что от него ожидается.

Существуют различные интерпретаторы, с которыми вы можете запускать тесты:

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

Тестирование вашей реализации

Вы можете использовать набор тестов и программу запуска тестов для тестирования собственной реализации Lox. Средство запуска тестов находится по tool/bin/test.dart , и ему можно предоставить собственный исполняемый файл интерпретатора для запуска с помощью --interpreter . Например, если у вас есть исполняемый файл интерпретатора в my_code/boblox , вы можете протестировать его следующим образом:

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

Вам все равно придется указать ему, какой набор тестов запускать, поскольку это определяет ожидания от тестов. Если ваш интерпретатор должен вести себя как jlox, используйте в качестве имени пакета «jlox». Если он ведет себя как clox, используйте «clox». Если ваш интерпретатор завершен только до конца одной из глав книги, вы можете использовать эту главу как комплект, например «chap10_functions». Названия всех глав смотрите в Makefile.

Если вашему интерпретатору нужны другие аргументы командной строки, переданные для использования, передайте их средству запуска тестов с помощью --arguments , и он перешлет их вашему интерпретатору.

Макет репозитория

• asset/ — файлы Sass и шаблоны jinja2, используемые для создания сайта.
• book/ — файлы Markdown для текста каждой главы.
• build/ — сюда помещаются промежуточные файлы и другие выходные данные сборки (кроме самого сайта). Не привязан к Git.
• c/ — исходный код clox, интерпретатора, написанного на C. Также содержит проект XCode, если вас это интересует.
• gen/ — здесь находятся исходные файлы Java, созданные с помощью GenerateAst.java. Не совершено.
• java/ — Исходный код jlox, интерпретатора, написанного на Java.
• note/ — Различные исследования, заметки, TODO и другая разная информация.
• note/answers — примеры ответов на задания. Никакого обмана!
• site/ — Окончательно сгенерированный сайт. Содержимое этого каталога напрямую отражает сайт Craftinginterpreters.com. Большая часть контента здесь создается с помощью build.py, но шрифты, изображения и JS живут только здесь. Все зафиксировано, даже сгенерированный контент.
• test/ — тестовые примеры для реализаций Lox.
• tool/ — пакет Dart, содержащий скрипты сборки, тестирования и другие.