md4c
1.0.0
MD4C adalah singkatan dari "Markdown for C" dan itulah tepatnya proyek ini.
Singkatnya, Markdown adalah bahasa markup file README.md ini ditulis.
Sumber daya berikut dapat menjelaskan lebih lanjut jika Anda tidak terbiasa dengan itu:
MD4C adalah implementasi parser markdown di C, dengan fitur -fitur berikut:
Kepatuhan: Umumnya, MD4C bertujuan untuk mematuhi spesifikasi CommonMark versi terbaru. Saat ini, kami sepenuhnya sesuai dengan Commonmark 0,31.
Ekstensi: MD4C mendukung beberapa ekstensi yang umum diminta dan diterima. Lihat di bawah.
Kinerja: MD4C sangat cepat.
Compactness: MD4C Parser diimplementasikan dalam satu file sumber dan satu file header. Tidak ada dependensi selain pustaka C standar.
Embedding: MD4C Parser mudah digunakan kembali dalam proyek lain, API -nya sangat mudah: sebenarnya hanya ada satu fungsi, md_parse() .
Model Push: MD4C Parse dokumen lengkap dan panggilan beberapa fungsi panggilan balik yang disediakan oleh aplikasi untuk menginformasikannya tentang awal/akhir dari setiap blok, start/akhir dari setiap rentang, dan dengan konten tekstual apa pun.
Portabilitas: MD4C membangun dan bekerja di OS Windows dan POSIX yang sesuai. ;
Pengkodean: MD4C Secara default mengharapkan pengkodean UTF-8 dari dokumen input. Tetapi dapat dikompilasi untuk mengenali karakter kontrol ASCII saja (yaitu untuk menonaktifkan semua kode spesifik unicode), atau (pada windows) untuk mengharapkan UTF-16 (yaitu apa yang ada di windows yang biasa disebut hanya "unicode"). Lihat detail lebih lanjut di bawah ini.
Lisensi permisif: MD4C tersedia di bawah lisensi MIT.
Jika Anda hanya perlu menguraikan dokumen penurunan harga, Anda perlu menyertakan md4c.h dan tautan terhadap MD4C Library ( -lmd4c ); atau alternatifnya tambahkan md4c.[hc] langsung ke basis kode Anda karena parser hanya diimplementasikan dalam file sumber C tunggal.
Fungsi utama yang disediakan adalah md_parse() . Dibutuhkan teks dalam sintaks penurunan markdown dan pointer ke struktur yang memberikan petunjuk ke beberapa fungsi callback.
Saat md_parse() memproses input, ia memanggil panggilan balik (saat memasuki atau meninggalkan blok atau rentang penurunan harga; dan ketika mengeluarkan konten tekstual dari dokumen), yang memungkinkan aplikasi untuk mengubahnya menjadi format lain atau membuatnya ke layar.
Jika Anda perlu mengonversi markdown ke HTML, sertakan md4c-html.h dan tautan terhadap pustaka MD4C-HTML ( -lmd4c-html ); atau alternatifnya tambahkan sumber md4c.[hc] , md4c-html.[hc] dan entity.[hc] ke dalam basis kode Anda.
Untuk mengonversi input penurunan harga, hubungi fungsi md_html() . Dibutuhkan input penurunan harga dan memanggil fungsi panggilan balik yang disediakan. Callback diumpankan dengan potongan output HTML. Implementasi panggilan balik yang khas hanya menambahkan potongan ke dalam buffer atau menulisnya ke file.
Perilaku default adalah mengenali hanya sintaks penurunan markdown yang ditentukan oleh spesifikasi Commonmark.
Namun, dengan bendera yang sesuai, perilaku tersebut dapat disetel untuk memungkinkan beberapa ekstensi:
Dengan bendera MD_FLAG_COLLAPSEWHITESPACE , spasi non-sepele runtuh menjadi satu ruang.
Dengan bendera MD_FLAG_TABLES , tabel bergaya gitub didukung.
Dengan bendera MD_FLAG_TASKLISTS , daftar tugas bergaya gitub didukung.
Dengan bendera MD_FLAG_STRIKETHROUGH , rentang mogok diaktifkan (teks terlampir dalam tanda tilde, misalnya ~foo bar~ ).
Dengan bendera MD_FLAG_PERMISSIVEURLAUTOLINKS URL Autolinks Permisif (tidak tertutup dalam < > didukung.
Dengan bendera MD_FLAG_PERMISSIVEEMAILAUTOLINKS , Autolinks e-mail permisif (tidak tertutup dalam < > didukung.
Dengan bendera MD_FLAG_PERMISSIVEWWWAUTOLINKS Permisif www Autolinks tanpa skema apa pun yang ditentukan (misalnya www.example.com ) didukung. MD4C kemudian mengasumsikan http: skema.
Dengan bendera MD_FLAG_LATEXMATHSPANS LATEX Math Spans ( $...$ ) dan Latex Display Math Span ( $$...$$ ) didukung. <x-equation>
Dengan bendera MD_FLAG_WIKILINKS , tautan bergaya wiki ( [[link label]] dan [[target article|link label]] ) didukung. <x-wikilink>
Dengan bendera MD_FLAG_UNDERLINE , menggarisbawahi ( _ ) menunjukkan garis bawah alih -alih penekanan biasa atau penekanan yang kuat.
Beberapa fitur Commonmark (yang beberapa orang melihat sebagai kesalahan-fitur) dapat dinonaktifkan dengan bendera berikut:
Dengan bendera MD_FLAG_NOHTMLSPANS atau MD_FLAG_NOHTMLBLOCKS , html inline mentah atau blok html mentah masing -masing dinonaktifkan.
Dengan bendera MD_FLAG_NOINDENTEDCODEBLOCKS , blok kode indentasi dinonaktifkan.
Spesifikasi CommonMark menyatakan bahwa urutan titik kode unicode adalah dokumen Commonmark yang valid.
Tapi, di bawah pemeriksaan lebih dekat, Unicode memainkan peran apa pun dalam beberapa situasi yang sangat spesifik ketika mem -parsing dokumen penurunan harga:
Untuk mendeteksi batas kata saat memproses penekanan dan penekanan yang kuat, beberapa klasifikasi karakter unicode (apakah itu wajar atau tanda baca) diperlukan.
Untuk pencocokan (case-tidak sensitif) dari label referensi tautan dengan definisi referensi tautan yang sesuai, lipat case unicode digunakan.
Untuk menerjemahkan entitas html (mis & ) dan referensi karakter numerik (mis. # atau ಫ ) menjadi setara unicode mereka.
Namun catatan MD4C meninggalkan terjemahan ini pada renderer/aplikasi; karena renderer seharusnya benar -benar mengetahui pengkodean output dan apakah itu benar -benar perlu melakukan terjemahan semacam ini. (Misalnya, ketika renderer menghasilkan html, itu mungkin membuat entitas tidak diterjemahkan dan menunda pekerjaan ke browser web.)
MD4C bergantung pada properti Commonmark ini dan implementasinya, sebagian besar, encoding-agnostik. Sebagian besar kode MD4C hanya mengasumsikan bahwa pengkodean pilihan Anda kompatibel dengan ASCII. Yaitu bahwa codepoints di bawah 128 memiliki nilai numerik yang sama dengan ASCII.
Input apa pun MD4C tidak mengerti hanya dilihat sebagai bagian dari teks dokumen dan dikirim ke fungsi panggilan balik renderer yang tidak berubah.
Dua situasi (deteksi batas kata dan pencocokan referensi tautan) di mana MD4C harus memahami Unicode ditangani sebagaimana ditentukan oleh makro preprosesor berikut (sebagaimana ditentukan pada saat MD4C sedang dibangun):
Jika preprocessor makro MD4C_USE_UTF8 didefinisikan, MD4C mengasumsikan UTF-8 untuk deteksi batas kata dan untuk pencocokan case-sensitif label tautan.
Ketika tidak ada makro ini yang digunakan secara eksplisit, ini adalah perilaku default.
Di Windows, jika preprocessor makro MD4C_USE_UTF16 didefinisikan, MD4C menggunakan WCHAR alih-alih char dan mengasumsikan pengkodean UTF-16 dalam situasi tersebut. (UTF-16 adalah apa yang biasanya disebut pengembang Windows hanya "unicode" dan apa yang umumnya bekerja dengan Win32api.)
Perhatikan bahwa karena makro ini mempengaruhi juga jenis -jenis di md4c.h , Anda harus mendefinisikan makro baik saat membangun MD4C maupun saat memasukkan md4c.h
Perhatikan juga ini hanya didukung dalam parser ( md4c.[hc] ). Renderer HTML tidak mendukung ini dan Anda harus menulis renderer khusus Anda sendiri untuk menggunakan fitur ini.
Jika preprocessor makro MD4C_USE_ASCII didefinisikan, MD4C mengasumsikan apa pun selain input ASCII.
Itu secara efektif berarti bahwa karakter non-ASCII atau karakter tanda baca tidak akan diakui seperti itu dan bahwa pencocokan referensi tautan akan berfungsi dengan cara yang tidak sensitif hanya untuk huruf ASCII ( [a-zA-Z] ).
API parser didokumentasikan dengan cukup baik dalam komentar di md4c.h Demikian pula, API markdown-to-HTML dijelaskan dalam header md4c-html.h .
Ada juga Wiki Project yang menyediakan beberapa dokumentasi yang lebih komprehensif. Namun perhatikan itu tidak lengkap dan beberapa detail mungkin agak usang.
T: Bagaimana MD4C dibandingkan dengan parser penurunan harga lainnya?
A: Beberapa implementasi lain menggabungkan penurunan harga parser dan generator HTML menjadi satu kode terjerat yang tersembunyi di balik antarmuka yang hanya memungkinkan konversi dari markdown ke HTML. Mereka sering tidak dapat digunakan jika Anda ingin memproses input dengan cara lain.
Kedua, sebagian besar parser (jika tidak semuanya; setidaknya dalam ruang lingkup bahasa C/C ++) adalah parser seperti DOM penuh: mereka membangun representasi Tree Sintaks Abstrak (AST) dari seluruh dokumen Markdown. Itu membutuhkan waktu dan itu mengarah ke jejak memori yang lebih besar.
Membangun AST benar -benar baik selama Anda membutuhkannya. Jika tidak, ada kemungkinan sangat tinggi bahwa menggunakan MD4C akan jauh lebih cepat dan kurang lapar dalam hal konsumsi memori.
Terakhir namun tidak kalah pentingnya, beberapa parser penurunan harga diimplementasikan dengan cara yang naif. Ketika diberi makan dengan pola input yang dibuat dengan cerdas, mereka mungkin menunjukkan waktu penguraian kuadratik (atau bahkan lebih buruk). Apa yang MD4C masih bisa menguraikan dalam sepersekian detik dapat berubah menjadi beberapa menit atau mungkin berjam -jam dengan mereka. Oleh karena itu, ketika parser naif seperti itu digunakan untuk memproses input dari sumber yang tidak dipercaya, kemungkinan serangan penolakan layanan menjadi bahaya nyata.
Banyak upaya kami untuk memberikan waktu parsing linier, tidak peduli apa pun input gila MD4C parser yang diumpankan. (Jika Anda menemukan pola input yang mengarah ke waktu penguraian sub-linear, jangan ragu dan laporkan sebagai bug.)
T: Apakah MD4C melakukan validasi input?
A: Tidak. Dan kami bangga akan hal itu. :-)
Spesifikasi CommonMark menyatakan bahwa urutan karakter unicode adalah dokumen penurunan harga yang valid. (Dalam praktiknya, ini lebih atau kurang selalu berarti penyandian UTF-8.)
Dengan kata lain, menurut spesifikasi, tidak masalah apakah beberapa konstruksi sintaks penurunan harga dalam beberapa hal rusak atau tidak. Jika rusak, itu tidak akan dikenali dan parser harus melihatnya seperti teks kata demi kata.
MD4C mengambil langkah ini lebih jauh: ia melihat urutan byte sebagai input yang valid, mengikuti sepenuhnya filosofi Gigo (sampah di, sampah keluar). Yaitu urutan UTF-8 byte yang tidak terbentuk akan merambat ke panggilan balik masing-masing sebagai bagian dari teks.
Jika Anda perlu memvalidasi bahwa inputnya adalah, katakanlah, dokumen UTF-8 yang terbentuk dengan baik, Anda harus melakukannya sendiri. Cara termudah bagaimana melakukan ini adalah dengan sekadar memvalidasi seluruh dokumen sebelum menyerahkannya ke parser MD4C.
MD4C ditutupi dengan lisensi MIT, lihat LICENSE.md file.md.
Port dan binding ke bahasa lain:
CommonMark-D: Port MD4C ke D Bahasa.
Markdown-WASM: Port MD4C ke WebAssembly.
PYMD4C: Binding Python untuk MD4C
Perangkat Lunak Menggunakan MD4C:
IMGUI_MD: Penjaga Markdown untuk Imgui tersayang
Markdown Monolith Assembler: Alat baris perintah untuk membangun buku berbasis browser.
Qownnotes: Notepad file teks biasa dan manajer daftar todo dengan Dukungan Markdown dan Integrasi OwnCloud / NextCloud.
QT: Kerangka kerja GUI Cross-Platform C ++.
Textosaurus: Editor teks lintas platform berdasarkan QT dan Scintilla.
8: Bahasa pemrograman concatenative lintas platform.
