craftinginterpreters

นี่คือ repo ที่ใช้สำหรับหนังสือ "Crafting Interpreters" ที่กำลังดำเนินการอยู่ ประกอบด้วยข้อความ Markdown ของหนังสือ การใช้งานล่ามทั้งสองอย่างเต็มรูปแบบ ตลอดจนระบบการสร้างเพื่อเชื่อมโยงทั้งสองเข้าด้วยกันในเว็บไซต์สุดท้าย

หากคุณพบข้อผิดพลาดหรือมีข้อเสนอแนะ โปรดแจ้งปัญหาที่นี่ ขอบคุณ!

มีส่วนร่วม

หนึ่งในสิ่งที่ดีที่สุดในการเขียนหนังสือออนไลน์และนำไปเผยแพร่ก่อนที่จะเขียนเสร็จก็คือคนเช่นคุณใจดีพอที่จะให้ข้อเสนอแนะ ชี้ให้เห็นการพิมพ์ผิด และพบข้อผิดพลาดอื่นๆ หรือข้อความที่ไม่ชัดเจน

หากคุณต้องการทำเช่นนั้น เยี่ยมมาก! คุณสามารถแจ้งข้อบกพร่องที่นี่ใน repo หรือส่งคำขอดึงข้อมูลได้หากคุณมีแนวโน้มเช่นนั้น หากคุณต้องการส่งคำขอดึงข้อมูล แต่ไม่ต้องการตั้งค่าระบบบิลด์ให้สร้าง HTML ใหม่ด้วย ไม่ต้องกังวลไป ฉันจะทำอย่างนั้นเมื่อฉันดึงมันเข้าไป

พอร์ตและการนำไปใช้งาน

อีกวิธีหนึ่งในการมีส่วนร่วมคือการแบ่งปันการใช้งาน Lox ของคุณเอง พอร์ตสำหรับภาษาอื่นมีประโยชน์อย่างยิ่ง เนื่องจากไม่ใช่ผู้อ่านทุกคนที่ชอบ Java และ C คุณสามารถเพิ่มพอร์ต Lox ของคุณหรือการใช้งานลงในวิกิได้:

• การใช้งาน Lox

สิ่งก่อสร้าง

ฉันเป็นสัตว์เลี้ยงลูกด้วยนมที่ขี้ลืมมาก และเกิดข้อผิดพลาดได้ง่าย ดังนั้นฉันจึงทำงานอัตโนมัติให้มากที่สุด

ข้อกำหนดเบื้องต้น

ฉันพัฒนาบนเครื่อง OS X แต่ระบบ POSIX ใดๆ ก็ควรใช้งานได้เช่นกัน หากต้องใช้ความพยายามเพิ่มเติมอีกเล็กน้อย คุณน่าจะสามารถใช้งานสิ่งนี้บน Windows ได้เช่นกัน แม้ว่าฉันจะช่วยเหลือคุณไม่ได้มากก็ตาม

งานส่วนใหญ่จัดทำโดยผู้ผลิต สคริปต์บิลด์ ตัวทดสอบ และยูทิลิตี้อื่น ๆ ล้วนเขียนด้วยภาษา Dart คำแนะนำในการติดตั้ง Dart อยู่ที่นี่ เมื่อคุณติดตั้ง Dart และบนเส้นทางของคุณแล้ว ให้รัน:

$ make get

การดำเนินการนี้จะดาวน์โหลดแพ็คเกจทั้งหมดที่ใช้โดยสคริปต์การสร้างและทดสอบ

ในการคอมไพล์ล่ามทั้งสอง คุณต้องมีคอมไพเลอร์ภาษา C บนพาธของคุณด้วย เช่นเดียวกับ javac

อาคาร

เมื่อคุณตั้งค่าเสร็จแล้ว ให้ลอง:

$ make

หากทุกอย่างทำงานได้ดี นั่นจะสร้างไซต์สำหรับหนังสือตลอดจนรวบรวมล่ามสองตัว clox และ jlox คุณสามารถเรียกใช้ล่ามตัวใดตัวหนึ่งได้จากรูทของ repo:

$ ./clox
$ ./jlox

การแฮ็กหนังสือ

Markdown และส่วนย่อยของซอร์สโค้ดถูกถักทอเข้าด้วยกันเป็น HTML สุดท้ายโดยใช้เครื่องมือสร้างไซต์คงที่ที่เขียนด้วยมือ ซึ่งเริ่มต้นจากสคริปต์ Python เล็กๆ ตัวเดียวสำหรับหนังสือเล่มแรกของฉัน และเติบโตจนกลายเป็นสิ่งที่ใกล้เคียงกับโปรแกรมจริง

HTML ที่สร้างขึ้นมีความมุ่งมั่นใน repo ภายใต้ site/ มันถูกสร้างขึ้นจากการผสมผสานระหว่าง Markdown สำหรับร้อยแก้ว ซึ่งอยู่ใน book/ และตัวอย่างโค้ดที่สานต่อจากการใช้งาน Java และ C ใน java/ และ c/ (ความคิดเห็นที่ดูตลกๆ ทั้งหมดในซอร์สโค้ดจะทำให้รู้ได้อย่างไรว่าตัวอย่างใดไปอยู่ที่ไหน)

สคริปต์ที่ทำสิ่งมหัศจรรย์ทั้งหมดคือ tool/bin/build.dart คุณสามารถเรียกใช้โดยตรงหรือเรียกใช้:

$ make book

ที่สร้างทั้งไซต์ในชุดเดียว หากคุณกำลังดำเนินการในส่วนนี้ คุณจะต้องเรียกใช้เซิร์ฟเวอร์การพัฒนา:

$ make serve

สิ่งนี้จะรันเซิร์ฟเวอร์ HTTP เล็กน้อยบน localhost ที่รูทที่ 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 โปรแกรม 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/ – การวิจัย บันทึก สิ่งที่ต้องทำ และหนังสือเบ็ดเตล็ดอื่นๆ ต่างๆ
• note/answers – ตัวอย่างคำตอบสำหรับการท้าทาย ไม่มีการโกง!
• site/ – ไซต์ที่สร้างขึ้นขั้นสุดท้าย เนื้อหาของไดเร็กทอรีนี้สะท้อนถึง craftingreaters.com โดยตรง เนื้อหาส่วนใหญ่ที่นี่สร้างโดย build.py แต่แบบอักษร รูปภาพ และ JS อยู่ที่นี่เท่านั้น ทุกอย่างมีความมุ่งมั่น แม้กระทั่งเนื้อหาที่สร้างขึ้น
• test/ – กรณีทดสอบสำหรับการใช้งาน Lox
• tool/ – แพ็คเกจ Dart ที่มีบิลด์ การทดสอบ และสคริปต์อื่นๆ