md4c
1.0.0
تعني MD4C "Marmdown for C" وهذا بالضبط ما يدور حوله هذا المشروع.
باختصار ، Marmdown هي لغة الترميز هذا ملف README.md مكتوب في.
يمكن للموارد التالية أن تشرح المزيد إذا لم تكن على دراية به:
MD4C هو تنفيذ محلل القلب في C ، مع الميزات التالية:
الامتثال: بشكل عام ، يهدف MD4C إلى أن تكون متوافقًا مع أحدث إصدار من مواصفات Sombormark. حاليًا ، نحن متوافقون تمامًا مع CommonMark 0.31.
الامتدادات: يدعم MD4C بعض الامتدادات المطلوبة والمقبولة بشكل شائع. انظر أدناه.
الأداء: MD4C سريع للغاية.
الاكتئاب: يتم تنفيذ محلل MD4C في ملف مصدر واحد وملف رأس واحد. لا توجد تبعيات أخرى غير مكتبة C القياسية.
التضمين: من السهل إعادة استخدام MD4C Parser في مشاريع أخرى ، واجهات برمجة التطبيقات الخاصة بها واضحة للغاية: هناك في الواقع وظيفة واحدة فقط ، md_parse() .
Push Model: يقوم MD4C بتوصيف المستند الكامل ويدعو بعض وظائف رد الاتصال المقدمة من التطبيق لإبلاغه عن بداية/نهاية لكل كتلة ، وبداية/نهاية كل فترة ، ومع أي محتويات نصية.
قابلية النقل: يقوم MD4C ببناء ويعمل على Windows و OPEIX المتوافقة مع OPEIX. (يجب أن يكون الأمر بسيطًا في تشغيله أيضًا على معظم المنصات الأخرى ، على الأقل طالما توفر المنصة مكتبة قياسية C ، بما في ذلك إدارة ذاكرة الكومة.)
الترميز: يتوقع MD4C افتراضيًا ترميز UTF-8 لمستند الإدخال. ولكن يمكن تجميعها للتعرف على أحرف التحكم ASCII فقط (أي لتعطيل جميع التعليمات البرمجية الخاصة بـ Unicode) ، أو (على Windows) للتوقع UTF-16 (أي ما يسمى عادةً "Unicode"). انظر المزيد من التفاصيل أدناه.
الترخيص المسموح به: MD4C متاح بموجب ترخيص معهد ماساتشوستس للتكنولوجيا.
إذا كنت بحاجة فقط إلى تحليل مستند Markdown ، فأنت بحاجة إلى تضمين md4c.h و Link مع مكتبة MD4C ( -lmd4c ) ؛ أو بدلاً من ذلك ، أضف md4c.[hc] مباشرة إلى قاعدة التعليمات البرمجية الخاصة بك حيث يتم تنفيذ المحلل فقط في ملف مصدر C المفرد.
الوظيفة الرئيسية المقدمة هي md_parse() . يأخذ نصًا في بناء جملة Markdown ومؤشر إلى بنية توفر مؤشرات لعدة وظائف رد الاتصال.
نظرًا لأن md_parse() يعالج الإدخال ، فإنه يقوم باستدعاء عمليات الاسترجاعات (عند إدخال أو ترك أي كتلة أو تمويل مائل ؛ وعند إخراج أي محتوى نصي للوثيقة) ، مما يسمح للتطبيق بتحويله إلى تنسيق آخر أو تقديمه على الشاشة.
إذا كنت بحاجة إلى تحويل Markdown إلى HTML ، قم بتضمين md4c-html.h والرابط مع مكتبة MD4C-HTML ( -lmd4c-html ) ؛ أو بدلاً من ذلك ، أضف المصادر md4c.[hc] و md4c-html.[hc] entity.[hc]
لتحويل إدخال Markdown ، اتصل بالدالة md_html() . يستغرق إدخال Morddown ويستدعي وظيفة رد الاتصال المقدمة. يتم تغذية رد الاتصال مع أجزاء من إخراج HTML. تنفيذ رد الاتصال النموذجي فقط يلحق القطع في المخزن المؤقت أو يكتبها إلى ملف.
السلوك الافتراضي هو التعرف على بناء جملة التخفيض فقط المحددة من خلال مواصفات المميز المشترك.
ومع ذلك ، مع الأعلام المناسبة ، يمكن ضبط السلوك لتمكين بعض الامتدادات:
مع Flag MD_FLAG_COLLAPSEWHITESPACE ، يتم انهيار مساحة بيضاء غير تافهة في مساحة واحدة.
مع Flag MD_FLAG_TABLES ، يتم دعم الجداول على غرار Github.
مع Flag MD_FLAG_TASKLISTS ، يتم دعم قوائم المهام على غرار Github.
مع Flag MD_FLAG_STRIKETHROUGH ، يتم تمكين فترات الإضراب (نص محاط بعلامات TILDE ، على سبيل المثال ~foo bar~ ).
مع Flag MD_FLAG_PERMISSIVEURLAUTOLINKS يتم دعم AUTOLINKS AUTOLINKS (غير مرفقة في < و > ).
مع Flag MD_FLAG_PERMISSIVEEMAILAUTOLINKS ، يتم دعم Autolinks عبر البريد الإلكتروني (غير المرفقة في < و > ).
مع flag MD_FLAG_PERMISSIVEWWWAUTOLINKS www autolinks دون أي مخطط محدد (على سبيل المثال www.example.com ). MD4C ثم يفترض http: مخطط.
مع Flag MD_FLAG_LATEXMATHSPANS تمتد مساحات الرياضيات اللاتكس ( $...$ ) و LATEX عرض الرياضيات ( $$...$$ ). (لاحظ على الرغم من أن عارض HTML يخرجها حرفيًا في علامة مخصصة <x-equation> .)
باستخدام Flag MD_FLAG_WIKILINKS ، يتم دعم روابط WIKI-Style ( [[link label]] و [[target article|link label]] ). (لاحظ أن عارض HTML يخرجها في علامة مخصصة <x-wikilink> .)
مع Flag MD_FLAG_UNDERLINE ، يشير السطح ( _ ) إلى تسطير بدلاً من التركيز العادي أو التركيز القوي.
قد يتم تعطيل بعض الميزات المشتركة (هؤلاء الذين يرون بعض الأشخاص على أنها سوء معزول) مع الأعلام التالية:
مع Flag MD_FLAG_NOHTMLSPANS أو MD_FLAG_NOHTMLBLOCKS ، يتم تعطيل HTML المضمّن الخام أو الكتل HTML الخام على التوالي.
باستخدام Flag MD_FLAG_NOINDENTEDCODEBLOCKS ، يتم تعطيل كتل التعليمات البرمجية ذات المسافة البادئة.
تعلن المواصفات المشتركة أن أي تسلسل من نقاط رمز Unicode هو وثيقة مشتركة صالحة.
ولكن ، تحت فحص أوثق ، يلعب Unicode أي دور في عدد قليل من المواقف المحددة للغاية عند تحليل المستندات المتولد:
للكشف عن حدود الكلمات عند معالجة التركيز والتركيز القوي ، هناك حاجة إلى بعض تصنيف أحرف Unicode (سواء كانت مساحة بيضاء أو علامات ترقيم).
من أجل (غير حساسة للحالة) مطابقة ملصق مرجع الارتباط مع تعريف مرجع الارتباط المقابل ، يتم استخدام طي حالة Unicode.
لترجمة كيانات HTML (على سبيل المثال & ) ومراجع الأحرف الرقمية (على سبيل المثال # أو ಫ ) في مكافئات Unicode الخاصة بهم.
ومع ذلك ، لاحظ MD4C يترك هذه الترجمة على العارض/التطبيق ؛ نظرًا لأن العارض من المفترض أن يعرف حقًا ترميز الإخراج وما إذا كان يحتاج حقًا إلى أداء هذا النوع من الترجمة. (على سبيل المثال ، عندما يقوم العارض بإخراج HTML ، قد يترك الكيانات غير المترجمة وتؤجل العمل إلى متصفح الويب.)
يعتمد MD4C على هذه الخاصية للعلامة المشتركة والتنفيذ ، إلى حد كبير ، الترميز. يفترض معظم رمز MD4C فقط أن الترميز الذي تختاره متوافق مع ASCII. أي أن النقاط الدائرية أقل من 128 لها نفس القيم الرقمية مثل ASCII.
أي مدخلات لا يفهمها MD4C لا ينظر إليها ببساطة كجزء من نص المستند وإرسالها إلى وظائف رد الاتصال على العارض دون تغيير.
في الحالتين (الكشف عن حدود الكلمة ومطابقة مرجع الارتباط) حيث يتعين على MD4C أن يفهم Unicode كما هو محدد بواسطة وحدات الماكرو قبل المعالج التالي (كما هو محدد في الوقت الذي يتم فيه بناء MD4C):
إذا تم تعريف MCRO MCRO MD4C_USE_UTF8 ، فإن MD4C يفترض UTF-8 للكشف عن حدود الكلمة وللطابقة غير الحساسة للعلامات.
عندما لا يتم استخدام أي من وحدات الماكرو بشكل صريح ، فإن هذا هو السلوك الافتراضي.
على Windows ، إذا تم تعريف MCRO MCRO MD4C_USE_UTF16 ، يستخدم MD4C WCHAR بدلاً من char ويفترض ترميز UTF-16 في تلك الحالات. (UTF-16 هو ما يسميه مطورو Windows عادةً "Unicode" وما الذي يعمل مع Win32API بشكل عام.)
لاحظ أنه نظرًا لأن هذا الماكرو يؤثر أيضًا على الأنواع في md4c.h ، يجب عليك تحديد الماكرو على حد سواء عند بناء MD4C وكذلك عند تضمين md4c.h
لاحظ أيضًا أن هذا مدعوم فقط في المحلل ( md4c.[hc] ). لا يدعم عارض HTML هذا وسيتعين عليك كتابة العارض المخصص الخاص بك لاستخدام هذه الميزة.
إذا تم تعريف MCRO MD4C_USE_ASCII ، فإن MD4C لا يفترض شيئًا سوى إدخال ASCII.
هذا يعني بشكل فعال أن أحرف المساحة البيضاء أو علامات الترقيم غير ASCII لن يتم الاعتراف بها على هذا النحو وأن مطابقة مرجع الارتباط ستعمل بطريقة غير حساسة للحالة فقط لأحرف ASCII ( [a-zA-Z] ).
تم توثيق واجهة برمجة تطبيقات المحلل جيدًا في التعليقات في md4c.h وبالمثل ، تم وصف API MD4C-HTML.H رأس md4c-html.h .
هناك أيضًا مشروع ويكي الذي يوفر بعض الوثائق الأكثر شمولاً. ومع ذلك ، لاحظ أنه غير مكتمل وقد تكون بعض التفاصيل قديمة إلى حد ما.
س: كيف تقارن MD4C مع محلات تخفيضات أخرى؟
ج: تجمع بعض التطبيقات الأخرى بين محلل التنسيق ومولد HTML في رمز واحد متشابك مخفي خلف واجهة تسمح فقط بالتحويل من Markdown إلى HTML. غالبًا ما تكون غير صالحة للاستعمال إذا كنت ترغب في معالجة المدخلات بأي طريقة أخرى.
ثانياً ، معظم المحللين (إن لم يكن كلهم جميعًا ؛ على الأقل ضمن نطاق لغة C/C ++) هم محللون كاملون يشبهون DOM: إنهم يبنون تمثيل شجرة بناء الجملة المجردة (AST) لمستند Markdown بالكامل. يستغرق الأمر وقتًا ويؤدي إلى انبعاثات ذاكرة أكبر.
بناء AST جيد تمامًا طالما كنت في حاجة إليه. إذا لم تقم بذلك ، فهناك فرصة كبيرة للغاية لأن استخدام MD4C سيكون أسرع إلى حد كبير وأقل جوعًا من حيث استهلاك الذاكرة.
أخيرًا وليس آخرًا ، يتم تنفيذ بعض التحليلات المتولد بطريقة ساذجة. عندما يتم تغذيتها بنمط إدخال تم تصميمها بذكاء ، فقد تظهر أوقات تحليلية تربيعية (أو أسوأ). ما لا يزال بإمكان MD4C تحليل جزء صغير من الثانية قد يتحول إلى دقائق طويلة أو ربما ساعات معهم. وبالتالي ، عندما يتم استخدام مثل هذا المحلل الساذج لمعالجة مدخلات من مصدر غير موثوق به ، تصبح إمكانية إنكار هجمات الخدمة خطرًا حقيقيًا.
وذهب الكثير من جهودنا إلى توفير أوقات تحليل خطية بغض النظر عن نوع المدخلات المجنونة التي يتم تغذيتها. (إذا واجهت نمط إدخال يؤدي إلى أوقات تحليل خطي فرعي ، فالرجاء عدم التردد والإبلاغ عنه كخطأ.)
س: هل يقوم MD4C بإجراء التحقق من صحة الإدخال؟
ج: لا ، ونحن فخورون به. :-)
تنص مواصفات Sombormark على أن أي تسلسل من أحرف Unicode هو وثيقة تخفيض صالحة. (في الممارسة العملية ، هذا يعني دائمًا ترميز UTF-8.)
بمعنى آخر ، وفقًا للمواصفات ، لا يهم ما إذا كان بعض بناء بناء جملة مبررات تم كسره إلى حد ما أم لا. إذا تم كسرها ، فلن يتم التعرف عليها ويجب أن يراها المحللون كنص حرفي.
يأخذ MD4C هذه الخطوة إلى الأمام: ترى أي تسلسل من البايتات كمدخلات صالحة ، باتباع فلسفة Gigo بالكامل (Garbage in ، Garbage Out). أي أن أي تسلسل بايت UTF-8 غير المصور سوف ينتشر إلى رد الاتصال المعني كجزء من النص.
إذا كنت بحاجة إلى التحقق من صحة أن الإدخال هو ، على سبيل المثال ، مستند UTF-8 الذي تم تشكيله جيدًا ، عليك القيام بذلك بنفسك. أسهل طريقة كيفية القيام بذلك هي ببساطة التحقق من صحة الوثيقة بأكملها قبل نقلها إلى محلل MD4C.
MD4C مغطى بترخيص معهد ماساتشوستس للتكنولوجيا ، راجع LICENSE.md الملف.
الموانئ والروابط للغات الأخرى:
CommonMark-D: Port of MD4C to D Language.
Marmdown-Wasm: Port of MD4C to Webassembly.
Pymd4c: روابط Python لـ MD4C
البرامج باستخدام MD4C:
IMGUI_MD: عارض Markdown لـ Dear Imgui
Marmdown Monolith Assembler: أداة سطر الأوامر لبناء الكتب المستندة إلى المتصفح.
QOWNNOTES: مفكرة ملف النص العادي ومدير قائمة TODO مع دعم Marmdown وتكامل OwnCloud / NextCloud.
QT: إطار عمل Cross-Platform C ++ GUI.
Textosaurus: محرر النصوص عبر المنصات بناءً على QT و Scintilla.
8: لغة البرمجة المتسلسلة عبر المنصات.
