md4c
1.0.0
MD4C ย่อมาจาก "Markdown for C" และนั่นคือสิ่งที่โครงการนี้เกี่ยวกับ
ในระยะสั้น Markdown เป็นภาษามาร์กอัปไฟล์ README.md นี้เขียนขึ้น
ทรัพยากรต่อไปนี้สามารถอธิบายได้มากขึ้นหากคุณไม่คุ้นเคยกับมัน:
MD4C คือการติดตั้งตัวแยกวิเคราะห์ Markdown ใน C พร้อมคุณสมบัติต่อไปนี้:
การปฏิบัติตาม: โดยทั่วไป MD4C มีจุดมุ่งหมายที่จะปฏิบัติตามข้อกำหนด Commonmark เวอร์ชันล่าสุด ปัจจุบันเราปฏิบัติตาม Commonmark อย่างเต็มที่ 0.31
ส่วนขยาย: MD4C รองรับส่วนขยายที่ได้รับการร้องขอและยอมรับกันทั่วไป ดูด้านล่าง
ประสิทธิภาพ: MD4C เร็วมาก
Compactness: MD4C Parser ถูกนำไปใช้ในไฟล์ต้นฉบับหนึ่งไฟล์และไฟล์ส่วนหัวหนึ่งไฟล์ ไม่มีการพึ่งพาอื่นนอกเหนือจากห้องสมุด C มาตรฐาน
Embedding: MD4C Parser นั้นง่ายต่อการใช้ซ้ำในโครงการอื่น ๆ API นั้นตรงไปตรงมามาก: จริงๆแล้วมีเพียงฟังก์ชั่นเดียว md_parse()
Push Model: MD4C วิเคราะห์เอกสารที่สมบูรณ์และเรียกใช้ฟังก์ชั่นการโทรกลับสองสามรายการที่ให้ไว้โดยแอปพลิเคชันเพื่อแจ้งให้ทราบเกี่ยวกับการเริ่มต้น/สิ้นสุดของทุกบล็อกการเริ่มต้น/สิ้นสุดของทุกช่วงและกับเนื้อหาที่เป็นข้อความใด ๆ
การพกพา: MD4C สร้างและทำงานบน Windows และ OSE ที่สอดคล้องกับ POSIX (มันควรจะง่ายที่จะทำให้มันทำงานบนแพลตฟอร์มอื่น ๆ ส่วนใหญ่อย่างน้อยตราบใดที่แพลตฟอร์มมีไลบรารีมาตรฐาน C รวมถึงการจัดการหน่วยความจำกอง)
การเข้ารหัส: MD4C โดยค่าเริ่มต้นคาดว่าจะมีการเข้ารหัส UTF-8 ของเอกสารอินพุต แต่มันสามารถรวบรวมเพื่อรับรู้อักขระควบคุม ascii เท่านั้น (เช่นเพื่อปิดใช้งานรหัสเฉพาะ unicode ทั้งหมด) หรือ (บน windows) เพื่อคาดหวัง UTF-16 (เช่นสิ่งที่อยู่ใน windows ที่เรียกว่า "unicode") ดูรายละเอียดเพิ่มเติมด้านล่าง
ใบอนุญาตอนุญาต: MD4C มีอยู่ภายใต้ใบอนุญาต MIT
หากคุณต้องการแยกวิเคราะห์เอกสาร Markdown คุณต้องรวม md4c.h และลิงก์กับไลบรารี MD4C ( -lmd4c ); หรือเพิ่ม md4c.[hc] โดยตรงไปยังฐานรหัสของคุณเนื่องจากตัวแยกวิเคราะห์จะถูกนำไปใช้ในไฟล์ต้นฉบับ C เดียวเท่านั้น
ฟังก์ชั่นหลักที่ให้ไว้คือ md_parse() ต้องใช้ข้อความในไวยากรณ์ Markdown และตัวชี้ไปยังโครงสร้างที่ให้พอยน์เตอร์ไปยังฟังก์ชั่นการโทรกลับหลายฟังก์ชั่น
ในขณะที่ md_parse() ประมวลผลอินพุตจะเรียกการเรียกกลับ (เมื่อป้อนหรือออกจากบล็อก markdown ใด ๆ และเมื่อส่งเนื้อหาข้อความใด ๆ ของเอกสาร) ช่วยให้แอปพลิเคชันสามารถแปลงเป็นรูปแบบอื่นหรือแสดงบนหน้าจอ
หากคุณต้องการแปลง Markdown เป็น HTML ให้รวม md4c-html.h และลิงก์กับไลบรารี MD4C-HTML ( -lmd4c-html ); หรือเพิ่มแหล่งที่มา md4c.[hc] , md4c-html.[hc] และ entity.[hc] ลงในฐานรหัสของคุณ
ในการแปลงฟังก์ชั่นการทำเครื่องหมาย malldown ให้เรียกใช้ฟังก์ชัน md_html() ต้องใช้อินพุต markdown และเรียกใช้ฟังก์ชันการโทรกลับที่ให้ไว้ การโทรกลับถูกป้อนด้วยชิ้นส่วนของเอาท์พุท HTML การใช้งานการโทรกลับโดยทั่วไปจะผนวกชิ้นส่วนเข้ากับบัฟเฟอร์หรือเขียนลงในไฟล์
พฤติกรรมเริ่มต้นคือการรับรู้เฉพาะไวยากรณ์ของ markdown ที่กำหนดโดยข้อกำหนด Commonmark
อย่างไรก็ตามด้วยธงที่เหมาะสมพฤติกรรมสามารถปรับแต่งเพื่อเปิดใช้งานส่วนขยายบางอย่าง:
ด้วยธง MD_FLAG_COLLAPSEWHITESPACE ช่องว่างที่ไม่สำคัญจะถูกยุบลงในพื้นที่เดียว
ด้วย FLAG MD_FLAG_TABLES จะรองรับตารางสไตล์ GitHub
ด้วย FLAG MD_FLAG_TASKLISTS รายการงานสไตล์ GitHub ได้รับการสนับสนุน
ด้วย Flag MD_FLAG_STRIKETHROUGH ช่วงการนัดหยุดงานจะเปิดใช้งาน (ข้อความที่แนบมาในเครื่องหมาย tilde เช่น ~foo bar~ )
ด้วย Flag MD_FLAG_PERMISSIVEURLAUTOLINKS URL Autolinks ที่ได้รับอนุญาต (ไม่ได้รับการสนับสนุนใน < และ > )
ด้วย FLAG MD_FLAG_PERMISSIVEEMAILAUTOLINKS ให้การสนับสนุนอีเมลอัตโนมัติที่ได้รับอนุญาต (ไม่ได้รับการสนับสนุนใน < และ > )
ด้วย FLAG MD_FLAG_PERMISSIVEWWWAUTOLINKS Permissive WWW Autolinks โดยไม่ต้องใช้โครงการใด ๆ (เช่น www.example.com ) MD4C จะถือว่า http: Scheme
ด้วย FLAG MD_FLAG_LATEXMATHSPANS คณิตศาสตร์ LaTeX ( $...$ ) และ LaTex Display Math Spans ( $$...$$ ) ได้รับการสนับสนุน (โปรดทราบว่า HTML Renderer ส่งออกคำต่อคำในแท็กที่กำหนดเอง <x-equation> )
ด้วย FLAG MD_FLAG_WIKILINKS ลิงก์สไตล์วิคี ( [[link label]] และ [[target article|link label]] ) ได้รับการสนับสนุน (โปรดทราบว่า HTML Renderer ส่งออกในแท็กที่กำหนดเอง <x-wikilink> )
ด้วยธง MD_FLAG_UNDERLINE ขีดล่าง ( _ ) หมายถึงขีดเส้นใต้แทนการเน้นสามัญหรือเน้นที่แข็งแกร่ง
คุณสมบัติของ Commonmark (บางคนมองว่าเป็นคุณสมบัติที่ผิดพลาด) อาจถูกปิดใช้งานด้วยธงต่อไปนี้:
ด้วย Flag MD_FLAG_NOHTMLSPANS หรือ MD_FLAG_NOHTMLBLOCKS , HTML แบบอินไลน์ดิบหรือบล็อก HTML ดิบตามลำดับจะถูกปิดใช้งาน
ด้วย FLAG MD_FLAG_NOINDENTEDCODEBLOCKS บล็อกรหัสเยื้องจะถูกปิดใช้งาน
ข้อกำหนดของ Commonmark ประกาศว่าลำดับของคะแนนรหัส Unicode ใด ๆ เป็นเอกสาร Commonmark ที่ถูกต้อง
แต่ภายใต้การตรวจสอบอย่างใกล้ชิด UNICODE มีบทบาทใด ๆ ในสถานการณ์ที่เฉพาะเจาะจงมากเมื่อแยกวิเคราะห์เอกสารการทำเครื่องหมาย:
สำหรับการตรวจจับขอบเขตของคำเมื่อการประมวลผลเน้นและการเน้นที่แข็งแกร่งจำเป็นต้องมีการจำแนกประเภทของอักขระ Unicode (ไม่ว่าจะเป็นช่องว่างหรือเครื่องหมายวรรคตอน)
สำหรับการจับคู่ (ตัวพิมพ์เล็ก) ของฉลากอ้างอิงลิงก์กับคำจำกัดความการอ้างอิงลิงก์ที่สอดคล้องกันใช้การพับกรณี Unicode
สำหรับการแปลเอนทิตี HTML (เช่น & ) และการอ้างอิงอักขระตัวเลข (เช่น # หรือ ಫ ) ลงใน Unicode เทียบเท่า
อย่างไรก็ตามหมายเหตุ MD4C ออกจากการแปลนี้บน Renderer/Application; เนื่องจากผู้แสดงความคิดเห็นควรจะรู้ว่าการเข้ารหัสเอาท์พุทจริง ๆ และไม่ว่าจะต้องทำการแปลแบบนี้หรือไม่ (ตัวอย่างเช่นเมื่อผู้แสดงผลส่งออก HTML มันอาจทำให้เอนทิตีไม่ถูกแปลและเลื่อนงานไปยังเว็บเบราว์เซอร์)
MD4C ขึ้นอยู่กับคุณสมบัตินี้ของ Commonmark และการดำเนินการคือการเข้ารหัสระดับสูง รหัส MD4C ส่วนใหญ่จะถือว่าการเข้ารหัสที่คุณเลือกนั้นเข้ากันได้กับ ASCII เช่น codepoints ต่ำกว่า 128 มีค่าตัวเลขเช่นเดียวกับ ASCII
MD4C อินพุตใด ๆ ไม่เข้าใจจะถูกมองว่าเป็นส่วนหนึ่งของข้อความเอกสารและส่งไปยังฟังก์ชั่นการโทรกลับของ Renderer ไม่เปลี่ยนแปลง
สถานการณ์ทั้งสอง (การตรวจจับขอบเขตคำและการจับคู่การเชื่อมโยงลิงก์) โดยที่ MD4C ต้องเข้าใจว่า unicode ได้รับการจัดการตามที่ระบุโดยแมโครตัวประมวลผลล่วงหน้าต่อไปนี้ (ตามที่ระบุในเวลา MD4C กำลังถูกสร้างขึ้น):
หากมีการกำหนดตัวประมวลผลล่วงหน้า MD4C_USE_UTF8 MD4C จะถือว่า UTF-8 สำหรับการตรวจจับขอบเขตคำและสำหรับการจับคู่กรณีที่ไม่ได้รับการตอบสนองของป้ายกำกับลิงก์
เมื่อไม่มีการใช้แมโครเหล่านี้อย่างชัดเจนนี่เป็นพฤติกรรมเริ่มต้น
บน Windows หากมีการกำหนดตัวประมวลผลล่วงหน้า MD4C_USE_UTF16 MD4C ใช้ WCHAR แทน char และสมมติว่าการเข้ารหัส UTF-16 ในสถานการณ์เหล่านั้น (UTF-16 เป็นสิ่งที่นักพัฒนา Windows มักจะเรียกว่า "Unicode" และสิ่งที่ Win32API ใช้งานได้โดยทั่วไป)
โปรดทราบว่าเนื่องจากแมโครนี้มีผลต่อประเภทใน md4c.h คุณต้องกำหนดแมโครทั้งสองเมื่อสร้าง MD4C เช่นเดียวกับเมื่อรวม md4c.h
นอกจากนี้โปรดทราบว่าสิ่งนี้ได้รับการสนับสนุนเฉพาะในตัวแยกวิเคราะห์ ( md4c.[hc] ) HTML Renderer ไม่รองรับสิ่งนี้และคุณจะต้องเขียน Renderer ที่กำหนดเองของคุณเองเพื่อใช้คุณสมบัตินี้
หากมีการกำหนด MD4C_USE_ASCII MD4C MD4C นั้น MD4C จะไม่สมมติว่าไม่มีอะไรนอกจากอินพุต ASCII
นั่นหมายความว่าอย่างมีประสิทธิภาพว่าตัวอักษรช่องว่างที่ไม่ใช่ ASCII หรือเครื่องหมายวรรคตอนจะไม่ได้รับการยอมรับเช่นนี้และการจับคู่การอ้างอิงลิงก์นั้นจะทำงานได้ในวิธีที่ไม่ไวต่อตัวอักษรสำหรับตัวอักษร ASCII เท่านั้น ( [a-zA-Z] )
API ของตัวแยกวิเคราะห์นั้นค่อนข้างดีในความคิดเห็นใน md4c.h ในทำนองเดียวกัน MARKDOWN-TO-HTML API ได้อธิบายไว้ในส่วนหัว md4c-html.h
นอกจากนี้ยังมีโครงการ Wiki ที่ให้เอกสารที่ครอบคลุมมากขึ้น อย่างไรก็ตามโปรดทราบว่ามันไม่สมบูรณ์และรายละเอียดบางอย่างอาจล้าสมัยไปบ้าง
ถาม: MD4C เปรียบเทียบกับ parsers Markdown อื่น ๆ อย่างไร
ตอบ: การใช้งานอื่น ๆ บางอย่างรวมตัวแยกวิเคราะห์ Markdown และ HTML Generator ลงในรหัสที่พัวพันเดียวที่ซ่อนอยู่หลังอินเทอร์เฟซซึ่งอนุญาตให้แปลงจาก Markdown เป็น HTML พวกเขามักจะใช้ไม่ได้หากคุณต้องการประมวลผลอินพุตด้วยวิธีอื่น
ประการที่สอง parsers ส่วนใหญ่ (ถ้าไม่ใช่ทั้งหมดของพวกเขาอย่างน้อยภายในขอบเขตของภาษา C/C ++) เป็นตัวแยกวิเคราะห์แบบเต็มรูปแบบ: พวกเขาสร้างทรีไวยากรณ์นามธรรม (AST) ของเอกสารการทำเครื่องหมายทั้งหมด ต้องใช้เวลาและนำไปสู่รอยเท้าหน่วยความจำที่ใหญ่กว่า
การสร้าง AST นั้นใช้ได้อย่างสมบูรณ์ตราบใดที่คุณต้องการ หากคุณไม่ได้มีโอกาสสูงมากที่การใช้ MD4C จะเร็วขึ้นอย่างมากและหิวน้อยลงในแง่ของการใช้หน่วยความจำ
สุดท้าย แต่ไม่ท้ายสุดการแยกวิเคราะห์ markdown บางตัวถูกนำไปใช้อย่างไร้เดียงสา เมื่อป้อนด้วยรูปแบบอินพุตที่สร้างขึ้นอย่างชาญฉลาดพวกเขาอาจแสดงเวลาการแยกวิเคราะห์กำลังสอง (หรือแย่กว่านั้น) สิ่งที่ MD4C ยังสามารถแยกวิเคราะห์ได้ในเศษเสี้ยววินาทีอาจเปลี่ยนเป็นนาทีที่ยาวนานหรืออาจเป็นชั่วโมงกับพวกเขา ดังนั้นเมื่อใช้ตัวแยกวิเคราะห์ที่ไร้เดียงสาเช่นนี้ในการประมวลผลอินพุตจากแหล่งที่ไม่น่าเชื่อถือความเป็นไปได้ของการโจมตีการปฏิเสธการให้บริการจะกลายเป็นอันตรายที่แท้จริง
ความพยายามมากมายของเราได้เข้าร่วมการแยกวิเคราะห์เชิงเส้นไม่ว่าจะเป็นตัวแยกวิเคราะห์ MD4C ที่บ้าคลั่งแบบไหน (หากคุณพบรูปแบบการป้อนข้อมูลซึ่งนำไปสู่เวลาแยกย่อยเชิงเส้นโปรดอย่าลังเลและรายงานว่าเป็นข้อผิดพลาด)
ถาม: MD4C ทำการตรวจสอบอินพุตหรือไม่?
ตอบ: ไม่และเราภูมิใจกับมัน -
ข้อมูลจำเพาะ Commonmark ระบุว่าลำดับของอักขระ Unicode ใด ๆ เป็นเอกสารการทำเครื่องหมายที่ถูกต้อง (ในทางปฏิบัติสิ่งนี้มากขึ้นหรือน้อยลงหมายถึงการเข้ารหัส UTF-8 เสมอ)
กล่าวอีกนัยหนึ่งตามข้อกำหนดมันไม่สำคัญว่าการก่อสร้างไวยากรณ์ของ markdown บางอย่างจะถูกทำลายหรือไม่ ถ้ามันแตกจะไม่ได้รับการยอมรับและตัวแยกวิเคราะห์ควรเห็นว่าเป็นข้อความคำต่อคำ
MD4C ก้าวไปอีกขั้นตอนนี้: มันเห็นลำดับของไบต์เป็นอินพุตที่ถูกต้องตามปรัชญา Gigo (ขยะในขยะออกไป) เช่นลำดับ UTF-8 ไบต์ที่ไม่ได้เกิดขึ้นจะเผยแพร่ไปยังการเรียกกลับที่เกี่ยวข้องเป็นส่วนหนึ่งของข้อความ
หากคุณต้องการตรวจสอบว่าอินพุตนั้นเป็นเอกสาร UTF-8 ที่มีรูปร่างดีคุณต้องทำด้วยตัวเอง วิธีที่ง่ายที่สุดในการทำเช่นนี้คือการตรวจสอบเอกสารทั้งหมดก่อนที่จะส่งผ่านไปยังตัวแยกวิเคราะห์ MD4C
MD4C ได้รับการคุ้มครองด้วยใบอนุญาต MIT ดูไฟล์ LICENSE.md
พอร์ตและการเชื่อมโยงกับภาษาอื่น ๆ :
Commonmark-D: พอร์ต MD4C ถึง D ภาษา
Markdown-Wasm: พอร์ตของ MD4C ไปยัง WebAssembly
pymd4c: การผูก python สำหรับ md4c
ซอฟต์แวร์ที่ใช้ MD4C:
imgui_md: markdown renderer สำหรับ dear imgui
Markdown Monolith Assembler: เครื่องมือบรรทัดคำสั่งสำหรับการสร้างหนังสือที่ใช้เบราว์เซอร์
Qownnotes: Notepad ไฟล์ข้อความธรรมดาและ ToDo-List Manager พร้อมการสนับสนุน Markdown และการรวม OwnCloud / NextCloud
QT: Cross-Platform C ++ Framework Framework
Textosaurus: ตัวแก้ไขข้อความข้ามแพลตฟอร์มตาม QT และ Scintilla
8th: ภาษาการเขียนโปรแกรม cross-platform concatenative
