craftinginterpreters

Ini adalah repo yang digunakan untuk buku "Crafting Interpreters" yang sedang dalam proses. Ini berisi teks penurunan harga buku, implementasi penuh dari kedua penerjemah, serta sistem pembangunan untuk menyatukan keduanya ke dalam situs akhir.

Jika Anda menemukan kesalahan atau mempunyai saran, silakan ajukan masalah di sini. Terima kasih!

Berkontribusi

Salah satu hal terbaik tentang menulis buku online dan mempublikasikannya sebelum selesai adalah orang-orang seperti Anda telah berbaik hati memberi saya umpan balik, menunjukkan kesalahan ketik, dan menemukan kesalahan lain atau teks yang tidak jelas.

Jika Anda ingin melakukan itu, bagus! Anda bisa melaporkan bug di sini di repo, atau mengirim permintaan penarikan jika Anda menginginkannya. Jika Anda ingin mengirim permintaan tarik, tetapi tidak ingin menyiapkan sistem build untuk membuat ulang HTML juga, jangan khawatir. Aku akan melakukannya saat aku menariknya.

Port dan implementasinya

Cara lain untuk terlibat adalah dengan membagikan implementasi Lox Anda sendiri. Porta ke bahasa lain sangat berguna karena tidak semua pembaca menyukai Java dan C. Silakan menambahkan port atau implementasi Lox Anda ke wiki:

• Implementasi Lox

Barang Bangunan

Saya adalah mamalia yang sangat pelupa dan rawan kesalahan, jadi saya melakukan otomatisasi sebanyak yang saya bisa.

Prasyarat

Saya mengembangkan pada mesin OS X, tetapi sistem POSIX apa pun juga bisa berfungsi. Dengan sedikit usaha ekstra, Anda seharusnya bisa menjalankannya di Windows juga, meskipun saya tidak bisa banyak membantu Anda.

Sebagian besar pekerjaan diatur oleh merek. Skrip build, test runner, dan utilitas lainnya semuanya ditulis dalam Dart. Petunjuk untuk menginstal Dart ada di sini. Setelah Anda menginstal Dart dan berada di jalur Anda, jalankan:

$ make get

Ini mengunduh semua paket yang digunakan oleh skrip build dan pengujian.

Untuk mengkompilasi kedua interpreter tersebut, Anda juga memerlukan kompiler C di jalur Anda serta javac .

Bangunan

Setelah Anda mendapatkan pengaturan itu, coba:

$ make

Jika semuanya berfungsi, itu akan menghasilkan situs untuk buku tersebut serta mengkompilasi dua penerjemah clox dan jlox. Anda dapat menjalankan salah satu juru bahasa langsung dari akar repo:

$ ./clox
$ ./jlox

Meretas buku

Penurunan harga dan cuplikan kode sumber dirangkai menjadi HTML final menggunakan generator situs statis tulisan tangan yang dimulai sebagai skrip Python kecil untuk buku pertama saya dan entah bagaimana berkembang menjadi sesuatu yang mendekati program nyata.

HTML yang dihasilkan dikomit dalam repo di bawah site/ . Itu dibangun dari kombinasi Markdown untuk prosa, yang ada di book/ , dan potongan kode yang dirangkai dari implementasi Java dan C di java/ dan c/ . (Semua komentar yang terlihat lucu di kode sumber adalah bagaimana ia mengetahui cuplikan mana yang dibawa ke mana.)

Skrip yang melakukan semua keajaiban adalah tool/bin/build.dart . Anda dapat menjalankannya secara langsung, atau menjalankan:

$ make book

Itu menghasilkan seluruh situs dalam satu batch. Jika Anda mengerjakannya secara bertahap, Anda sebaiknya menjalankan server pengembangan:

$ make serve

Ini menjalankan server HTTP kecil di localhost yang di-root di site/ direktori. Setiap kali Anda meminta halaman, halaman tersebut akan membuat ulang file apa pun yang sumbernya telah diubah, termasuk file Markdown, file sumber juru bahasa, templat, dan aset. Biarkan saja itu terus berjalan, edit file secara lokal, dan segarkan browser Anda untuk melihat perubahannya.

Membangun penerjemah

Anda dapat membangun setiap penerjemah seperti ini:

$ make clox
$ make jlox

Ini membangun versi final dari masing-masing penafsir seperti yang muncul di akhir bagiannya dalam buku ini.

Anda juga dapat melihat seperti apa penafsirnya di akhir setiap bab. (Saya menggunakan ini untuk memastikan mereka berfungsi bahkan di tengah-tengah buku.) Ini didorong oleh skrip, tool/bin/split_chapters.dart yang menggunakan penanda komentar yang sama untuk cuplikan kode guna menentukan potongan kode mana yang hadir di setiap bab. Dibutuhkan hanya cuplikan yang telah dilihat di akhir setiap bab dan menghasilkan salinan sumber baru di gen/ , satu direktori untuk kode setiap bab. (Ini juga merupakan cara yang lebih mudah untuk melihat kode sumber karena semua komentar penanda yang mengganggu telah dihilangkan.)

Kemudian masing-masing dapat dibangun secara terpisah. Berlari:

$ make c_chapters

Dan di direktori build/ , Anda akan mendapatkan executable untuk setiap bab, seperti chap14_chunks , dll. Demikian pula:

$ make java_chapters

Ini mengkompilasi kode Java ke file kelas di build/gen/ dalam subdirektori untuk setiap bab.

Pengujian

Saya memiliki rangkaian tes Lox lengkap yang saya gunakan untuk memastikan penerjemah dalam buku melakukan apa yang seharusnya mereka lakukan. Kasus uji ada di test/ . tool/bin/test.dart adalah pelari pengujian yang menjalankan masing-masing file pengujian tersebut pada penerjemah Lox, mem-parsing hasilnya, dan memvalidasi bahwa pengujian tersebut melakukan apa yang diharapkan.

Ada berbagai penerjemah yang dapat Anda uji:

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

Menguji implementasi Anda

Anda dipersilakan untuk menggunakan test suite dan test runner untuk menguji implementasi Lox Anda sendiri. Pelari pengujian ada di tool/bin/test.dart dan dapat diberikan juru bahasa khusus yang dapat dijalankan untuk dijalankan menggunakan --interpreter . Misalnya, jika Anda memiliki juru bahasa yang dapat dieksekusi di my_code/boblox , Anda dapat mengujinya seperti:

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

Anda masih perlu memberi tahu rangkaian pengujian mana yang harus dijalankan karena hal tersebut menentukan ekspektasi pengujian. Jika penerjemah Anda berperilaku seperti jlox, gunakan "jlox" sebagai nama suite. Jika berperilaku seperti clox, gunakan "clox". Jika penerjemah Anda hanya menyelesaikan hingga akhir salah satu bab dalam buku, Anda dapat menggunakan bab tersebut sebagai rangkaiannya, seperti "chap10_functions". Lihat Makefile untuk nama semua bab.

Jika penerjemah Anda memerlukan argumen baris perintah lain untuk digunakan, teruskan argumen tersebut ke runner pengujian menggunakan --arguments dan argumen tersebut akan diteruskan ke penerjemah Anda.

Tata Letak Repositori

• asset/ – File Sass dan templat jinja2 digunakan untuk membuat situs.
• book/ - File penurunan harga untuk teks setiap bab.
• build/ - File perantara dan keluaran build lainnya (kecuali situs itu sendiri) buka di sini. Tidak berkomitmen pada Git.
• c/ – Kode sumber clox, penerjemah yang ditulis dalam C. Juga berisi proyek XCode, jika itu yang Anda inginkan.
• gen/ – File sumber Java yang dihasilkan oleh GenerateAst.java buka di sini. Tidak berkomitmen.
• java/ – Kode sumber jlox, penerjemah yang ditulis dalam Java.
• note/ – Berbagai penelitian, catatan, TODO, dan lain-lain.
• note/answers – Contoh jawaban untuk tantangan tersebut. Jangan curang!
• site/ – Situs akhir yang dihasilkan. Isi direktori ini secara langsung mencerminkan craftinginterpreters.com. Sebagian besar konten di sini dihasilkan oleh build.py, tetapi font, gambar, dan JS hanya ada di sini. Semuanya berkomitmen, bahkan konten yang dihasilkan.
• test/ – Uji kasus untuk implementasi Lox.
• tool/ – Paket dart yang berisi skrip build, test, dan lainnya.