md4c
1.0.0
MD4C steht für "Markdown for C" und genau darum geht es in diesem Projekt.
Kurz gesagt, Markdown ist die Markup -Sprache, in der diese README.md -Datei geschrieben ist.
Die folgenden Ressourcen können mehr erklären, wenn Sie damit nicht vertraut sind:
MD4C ist eine Markdown -Parser -Implementierung in C mit den folgenden Funktionen:
Compliance: Im Allgemeinen zielt MD4C darauf ab, der neuesten Version der Commonmark -Spezifikation zu konform zu sein. Derzeit sind wir vollständig für Commonmark 0,31 konform.
Erweiterungen: MD4C unterstützt einige häufig angeforderte und akzeptierte Erweiterungen. Siehe unten.
Leistung: MD4C ist sehr schnell.
Kompaktheit: MD4C -Parser wird in einer Quelldatei und einer Header -Datei implementiert. Es gibt keine anderen Abhängigkeiten als die Standard -C -Bibliothek.
Einbettung: Der MD4C -Parser ist in anderen Projekten leicht wiederzuverwenden. Die API ist sehr einfach: Es gibt eigentlich nur eine Funktion, md_parse() .
Push -Modell: MD4C analysiert das vollständige Dokument und ruft nur wenige Rückruffunktionen auf, die von der Anwendung bereitgestellt werden, um es über einen Start/Ende jedes Blocks, ein Start/Ende jeder Zeitspanne und mit jedem Textinhalt zu informieren.
Portabilität: MD4C baut und funktioniert unter Windows und POSIX-konformen Osen. (Es sollte einfach sein, dass es auch auf den meisten anderen Plattformen ausgeführt wird, mindestens so lange, wie die Plattform C -Standardbibliothek bietet, einschließlich einer Heap -Speicherverwaltung.)
Codierung: MD4C standardmäßig erwartet die UTF-8-Codierung des Eingabendokuments. Es kann jedoch kompiliert werden, um Asciii-Control-Zeichen zu erkennen (dh, um alle unicodespezifischen Code zu deaktivieren) oder (unter Windows), um UTF-16 zu erwarten (dh das, was auf Windows ist, die allgemein als "Unicode" bezeichnet werden). Weitere Informationen finden Sie unten.
Zulässige Lizenz: MD4C ist im Rahmen der MIT -Lizenz verfügbar.
Wenn Sie nur ein Markdown -Dokument analysieren müssen, müssen Sie md4c.h und Link gegen die MD4C -Bibliothek ( -lmd4c ) einschließen. oder alternativ md4c.[hc] direkt zu Ihrer Codebasis, da der Parser nur in der einzelnen C -Quelldatei implementiert ist.
Die wichtigste Funktion ist md_parse() . Es nimmt einen Text in die Markdown -Syntax und einen Zeiger auf eine Struktur, die Zeiger auf mehrere Rückruffunktionen liefert.
Wenn md_parse() die Eingabe verarbeitet, ruft es die Rückrufe (beim Eingeben oder Verlassen eines Markdown -Blocks oder einer Span; und bei Ausgabe eines Textinhalts des Dokuments) auf, sodass die Anwendung sie in ein anderes Format umwandeln oder auf den Bildschirm rendern.
Wenn Sie den Markdown in HTML konvertieren müssen, enthalten Sie md4c-html.h und Link gegen die MD4C-HTML-Bibliothek ( -lmd4c-html ); oder alternativ die Quellen md4c.[hc] , md4c-html.[hc] und entity.[hc] in Ihre Codebasis hinzufügen.
Um eine Markdown -Eingabe zu konvertieren, rufen Sie die Funktion md_html() auf. Es nimmt die Markdown -Eingabe und ruft die bereitgestellte Rückruffunktion auf. Der Rückruf wird mit Stücken der HTML -Ausgabe gefüttert. Die typische Rückrufimplementierung fügt die Brocken nur in einen Puffer an oder schreibt sie in eine Datei.
Das Standardverhalten besteht darin, nur die durch die Commonmark -Spezifikation definierte Markdown -Syntax zu erkennen.
Mit geeigneten Flaggen kann das Verhalten jedoch eingestellt werden, um einige Erweiterungen zu ermöglichen:
Mit der Flag MD_FLAG_COLLAPSEWHITESPACE wird ein nicht triviales Weißespace in einen einzelnen Raum zusammengebrochen.
Mit den Flag MD_FLAG_TABLES werden Tabellen im GitHub-Stil unterstützt.
Mit den Flag MD_FLAG_TASKLISTS werden die Aufgabenlisten im GitHub-Stil unterstützt.
Mit der Flag MD_FLAG_STRIKETHROUGH sind die Through-Through-Spans aktiviert (Text in Tilde-Markierungen, z ~foo bar~ ).
Mit der Flag MD_FLAG_PERMISSIVEURLAUTOLINKS werden zulässige URL -Autolinks (nicht in < eingeschlossen > unterstützt.
Mit der Flag MD_FLAG_PERMISSIVEEMAILAUTOLINKS werden zulässige E-Mail-Autolinks (nicht in < eingeschlossen > unterstützt.
Mit dem Flag MD_FLAG_PERMISSIVEWWWAUTOLINKS der ohne festgelegte Schema (z. B. www.example.com ) zulässige WWW -Autolinks zu erteilen ist (z. B. www.example.com). MD4C nimmt dann http: Schema an.
Mit der Flag MD_FLAG_LATEXMATHSPANS LATEX Math Spans ( $...$ ) und Latex -Display -Mathematikspannen ( $$...$$ ) werden unterstützt. (Beachten Sie jedoch, dass der HTML-Renderer sie wörtlich in einem benutzerdefinierten Tag <x-equation> ausgibt.)
Mit der Flag MD_FLAG_WIKILINKS werden Links im Wiki-Stil ( [[link label]] und [[target article|link label]] ) unterstützt. (Beachten Sie, dass der HTML-Renderer sie in einem benutzerdefinierten Tag <x-wikilink> ausgibt.)
Mit der Flag MD_FLAG_UNDERLINE bezeichnet Underscore ( _ ) eine Unterstreichung anstelle eines gewöhnlichen Schwerpunkts oder einer starken Betonung.
Nur wenige Merkmale von Commonmark (die einige Menschen als Fehlfehler ansehen) können mit den folgenden Flaggen deaktiviert werden:
Mit der Flag MD_FLAG_NOHTMLSPANS oder MD_FLAG_NOHTMLBLOCKS sind RAW -Inline -HTML- oder RAW -HTML -Blöcke deaktiviert.
Mit den Flag MD_FLAG_NOINDENTEDCODEBLOCKS sind eingerückte Codeblöcke deaktiviert.
Die Commonmark -Spezifikation erklärt, dass jede Sequenz von Unicode -Codepunkten ein gültiges Commonmark -Dokument ist.
Unicode spielt jedoch unter einer genaueren Inspektion in wenigen sehr spezifischen Situationen bei der Parsen von Markdown -Dokumenten eine Rolle:
Zur Erkennung von Wortgrenzen bei der Verarbeitung von Schwerpunkt und starker Betonung ist eine Klassifizierung von Unicode -Zeichen (ob es sich um eine Whitespace oder eine Interpunktion handelt).
Für (Fall-unempfindliche) Übereinstimmung einer Link-Referenzbezeichnung mit der entsprechenden Link-Referenz-Definition wird die Unicode-Fallfaltung verwendet.
Zur Übersetzung von HTML -Entitäten (z & ) und numerischen Zeichenreferenzen (zB # oder ಫ ) in ihre Unicode -Äquivalente.
Beachten Sie jedoch, dass MD4C diese Übersetzung auf dem Renderer/der Anwendung verlässt. Da der Renderer wirklich wissen soll, dass die Output -Codierung die Ausgangscodierung erfolgt und ob es wirklich diese Art von Übersetzung ausführen muss. (Wenn der Renderer beispielsweise HTML ausgibt, kann die Entitäten nicht einsetzt werden und die Arbeit in einen Webbrowser verschieben.)
MD4C stützt sich auf diese Eigenschaft des Commonmarks, und die Umsetzung ist in hohem Maße kodierende Agnostiker. Der größte Teil des MD4C -Codes geht nur davon aus, dass die Codierung Ihrer Wahl mit ASCII kompatibel ist. Dh die CodePoints unter 128 haben die gleichen numerischen Werte wie ASCII.
Jeder Eingabe -MD4C versteht nicht einfach als Teil des Dokumenttextes und wird unverändert an die Rückruffunktionen des Renderers gesendet.
Die beiden Situationen (Wortgrenzerkennung und Link -Referenz -Matching), in denen MD4C Unicode verstehen muss, werden gemäß den folgenden Präprozessor -Makros behandelt (wie zum Zeitpunkt des Erstellens von MD4C angegeben):
Wenn Precessor-Makro MD4C_USE_UTF8 definiert ist, übernimmt MD4C UTF-8 für die Wortgrenzerkennung und für die von Fall unempfindliche Anpassung von Link-Labels.
Wenn keiner dieser Makros explizit verwendet wird, ist dies das Standardverhalten.
Unter Windows verwendet MD4C unter Windows, wenn Precessor-Makro MD4C_USE_UTF16 definiert ist, WCHAR anstelle von char und setzt die UTF-16-Codierung in diesen Situationen an. (UTF-16 ist das, was Windows-Entwickler normalerweise nur "Unicode" nennen und mit dem Win32API im Allgemeinen funktioniert.)
Beachten Sie, dass Sie das Makro sowohl beim Aufbau von md4c.h als auch bei der Einbeziehung md4c.h
Beachten Sie auch, dass dies nur im Parser unterstützt wird ( md4c.[hc] ). Der HTML -Renderer unterstützt dies nicht und Sie müssen Ihren eigenen benutzerdefinierten Renderer schreiben, um diese Funktion zu verwenden.
Wenn Precessor -Makro MD4C_USE_ASCII definiert ist, setzt MD4C nur einen ASCII -Eingang an.
Dies bedeutet effektiv, dass nicht-ASCII-Whitespace- oder Interpunktionszeichen nicht als solche erkannt werden und dass die Verknüpfung der Verknüpfung der Referenzvereinigung nur für ASCII-Buchstaben ( [a-zA-Z] ) funktioniert.
Die API des Parsers ist in den Kommentaren im md4c.h In ähnlicher Weise wird die Markdown-to-HTML-API in ihrem Header md4c-html.h beschrieben.
Es gibt auch Project Wiki, das eine umfassendere Dokumentation bietet. Beachten Sie jedoch, dass es unvollständig ist und einige Details möglicherweise etwas veraltet sein.
F: Wie vergleicht sich MD4C mit anderen Markdown -Parern?
A: Einige andere Implementierungen kombinieren Markdown -Parser- und HTML -Generator zu einem einzigen verstrichenen Code, der hinter einer Schnittstelle versteckt ist, die nur die Konvertierung von Markdown in HTML ermöglicht. Sie sind oft unbrauchbar, wenn Sie die Eingabe auf andere Weise verarbeiten möchten.
Zweitens sind die meisten Parser (wenn nicht alle von ihnen; zumindest innerhalb des Geltungsbereichs der C/C ++-Sprache) vollständige DOM-ähnliche Parser: Sie konstruieren abstrakte Syntaxbaum (AST) Darstellung des gesamten Markdown-Dokuments. Das braucht Zeit und führt zu einem größeren Memory -Fußabdruck.
Das Bauen von AST ist völlig in Ordnung, solange Sie es brauchen. Wenn Sie dies nicht tun, besteht eine sehr hohe Wahrscheinlichkeit, dass die Verwendung von MD4C in Bezug auf den Speicherverbrauch wesentlich schneller und weniger hungrig ist.
Last but not least werden einige Markdown -Parser auf naive Weise implementiert. Wenn sie mit einem intelligent gestalteten Eingangsmuster gefüttert werden, können sie quadratische (oder noch schlechtere) Parsingzeiten aufweisen. Was MD4C noch in einem Bruchteil von Sekunde analysieren kann, kann mit ihnen in lange Minuten oder möglicherweise Stunden werden. Wenn ein solcher naiver Parser verwendet wird, um eine Eingabe von einer nicht vertrauenswürdigen Quelle zu verarbeiten, wird die Möglichkeit einer Denial-of-Service-Angriffe zu einer echten Gefahr.
Ein Großteil unserer Anstrengungen lieferte lineare Parsenszeiten, egal mit welchem verrückten Eingang MD4C -Parser gefüttert wird. (Wenn Sie auf ein Eingabemuster stoßen, das zu einer sublinearischen Parsenzeit führt, zögern Sie bitte nicht und melden Sie es als Fehler.)
F: Firiere MD4C eine Eingabevalidierung?
A: Nein. Und wir sind stolz darauf. :-)
Die Spezifikation von Commonmark besagt, dass eine Abfolge von Unicode -Zeichen ein gültiges Markdown -Dokument ist. (In der Praxis bedeutet dies mehr oder weniger immer UTF-8-Codierung.)
Mit anderen Worten, nach der Spezifikation spielt es keine Rolle, ob eine Markdown -Syntaxkonstruktion in irgendeiner Weise gebrochen ist oder nicht. Wenn es kaputt ist, wird es nicht erkannt und der Parser sollte es nur als wörtlicher Text sehen.
MD4C geht noch einen Schritt weiter: Es sieht jede Abfolge von Bytes als gültige Eingabe an, nachdem die Gigo -Philosophie (Müll in, Müll aus) vollständig nachgefolgt ist. Die dh eine schlecht geformte UTF-8-Byte-Sequenz wird sich als Teil des Textes zum jeweiligen Rückruf ausbreiten.
Wenn Sie validieren müssen, dass die Eingabe beispielsweise ein gut geformtes UTF-8-Dokument ist, müssen Sie dies selbst tun. Der einfachste Weg, dies zu tun, besteht darin, das gesamte Dokument einfach zu validieren, bevor es an den MD4C -Parser weitergegeben wird.
MD4C ist mit der MIT -Lizenz bedeckt, siehe LICENSE.md .
Ports und Bindungen an andere Sprachen:
Commonmark-D: Port von MD4C zu D-Sprache.
Markdown-WASM: Port of MD4C zur WebAssembly.
PYMD4C: Python -Bindungen für MD4C
Software mit MD4C:
Imgui_md: Markdown -Renderer für liebe Imgui
Markdown Monolith Assembler: Ein Befehlszeilen-Tool zum Erstellen von Büchern auf Browserbasis.
Qownnotes: Ein Notepad und Todo-List-Manager der Klartext-Datei mit Markdown-Support und Integration von OwnCloud / Nextcloud.
QT: plattformübergreifend C ++ GUI-Framework.
Textosaurus: plattformübergreifender Texteditor basierend auf QT und Szintilla.
8.: plattformübergreifende, verkettende Programmiersprache.
