md4c
1.0.0
MD4C signifie "Markdown pour C" et c'est exactement ce que parle ce projet.
En bref, Markdown est la langue de balisage dans laquelle le fichier README.md est rédigé.
Les ressources suivantes peuvent expliquer davantage si vous ne le savez pas:
MD4C est la mise en œuvre de l'analyse de marque en C, avec les fonctionnalités suivantes:
Conformité: Généralement, MD4C vise à se conformer à la dernière version de Commonmark Specification. Actuellement, nous sommes entièrement conformes à Commonmark 0,31.
Extensions: MD4C prend en charge certaines extensions couramment demandées et acceptées. Voir ci-dessous.
Performance: MD4C est très rapide.
Compacité: l'analyseur MD4C est implémenté dans un fichier source et un fichier d'en-tête. Il n'y a pas de dépendances autres que la bibliothèque C standard.
Incorporer: MD4C Parser est facile à réutiliser dans d'autres projets, son API est très simple: il n'y a en fait qu'une seule fonction, md_parse() .
Modèle push: MD4C analyse le document complet et appelle quelques fonctions de rappel fournies par l'application pour l'informer d'un début / fin de chaque bloc, d'un début / fin de chaque portée et avec tout contenu textuel.
Portabilité: MD4C construit et travaille sur Windows et OSO compatible POSIX. (Il devrait être simple de le faire fonctionner également sur la plupart des autres plates-formes, au moins tant que la plate-forme fournit une bibliothèque standard C, y compris une gestion de la mémoire de tas.)
Encodage: MD4C par défaut prévoit le codage UTF-8 du document d'entrée. Mais il peut être compilé pour reconnaître les caractères de contrôle ASCII uniquement (c'est-à-dire pour désactiver tout le code spécifique à l'Unicode), ou (sur Windows) s'attendre à UTF-16 (c'est-à-dire ce qui est sur Windows communément appelé "Unicode"). Voir plus de détails ci-dessous.
Licence permissive: MD4C est disponible sous la licence MIT.
Si vous avez besoin d'analyser un document Markdown, vous devez inclure md4c.h et lien contre la bibliothèque MD4C ( -lmd4c ); ou alternativement ajouter md4c.[hc] directement à votre base de code car l'analyseur n'est implémenté que dans le fichier source C unique.
La fonction principale fournie est md_parse() . Il prend un texte dans la syntaxe Markdown et un pointeur vers une structure qui fournit des pointeurs vers plusieurs fonctions de rappel.
Comme md_parse() traite l'entrée, il appelle les rappels (lors de la saisie ou de la sortie d'un bloc ou d'une portée de marque; et lors de la sortie de tout contenu textuel du document), permettant à l'application de la convertir en un autre format ou de le rendre sur l'écran.
Si vous devez convertir Markdown en HTML, incluez md4c-html.h et lien contre la bibliothèque MD4C-HTML ( -lmd4c-html ); ou également ajouter les sources md4c.[hc] , md4c-html.[hc] et entity.[hc] dans votre base de code.
Pour convertir une entrée Markdown, appelez la fonction md_html() . Il prend l'entrée Markdown et appelle la fonction de rappel fournie. Le rappel est nourri avec des morceaux de la sortie HTML. L'implémentation de rappel typique ajoute simplement les morceaux dans un tampon ou les écrit dans un fichier.
Le comportement par défaut consiste à reconnaître uniquement la syntaxe de Markdown définie par la spécification Commonmark.
Cependant, avec des drapeaux appropriés, le comportement peut être réglé pour permettre certaines extensions:
Avec le drapeau MD_FLAG_COLLAPSEWHITESPACE , un espace blanc non trivial est effondré dans un seul espace.
Avec l'indicateur MD_FLAG_TABLES , les tables de style GitHub sont prises en charge.
Avec l'indicateur MD_FLAG_TASKLISTS , les listes de tâches de style GitHub sont prises en charge.
Avec le drapeau MD_FLAG_STRIKETHROUGH , les portées de frappe sont activées (texte enfermé dans des marques Tilde, par exemple ~foo bar~ ).
Avec le drapeau MD_FLAG_PERMISSIVEURLAUTOLINKS , URL AutoLinks (non enfermé dans < > est pris en charge.
Avec le drapeau MD_FLAG_PERMISSIVEEMAILAUTOLINKS , les auto-links e-mail permissifs (non enfermés dans < > sont pris en charge.
Avec le drapeau MD_FLAG_PERMISSIVEWWWAUTOLINKS Permissive WWW AutoLinks sans aucun schéma spécifié (par exemple www.example.com ) sont pris en charge. MD4C suppose ensuite http: Schéma.
Avec le drapeau MD_FLAG_LATEXMATHSPANS LATHEX MATH SPANS ( $...$ ) et les étendues de mathématiques affichages de latex ( $$...$$ ) sont prises en charge. (Notez cependant que le HTML Renderer les diffuse textuellement dans une balise personnalisée <x-equation> .)
Avec l'indicateur MD_FLAG_WIKILINKS , les liens de style Wiki-( [[link label]] et [[target article|link label]] ] sont pris en charge. (Notez que le rendu HTML les sort dans une balise personnalisée <x-wikilink> .)
Avec le drapeau MD_FLAG_UNDERLINE , le soulignement ( _ ) désigne un soulignement au lieu d'un accent ordinaire ou d'un fort accent.
Peu de caractéristiques de Commonmark (celles de certaines personnes considèrent comme des malfaisances) peuvent être désactivées avec les drapeaux suivants:
Avec l'indicateur MD_FLAG_NOHTMLSPANS ou MD_FLAG_NOHTMLBLOCKS , les blocs HTML ou HTML RAW Inline HTML ou bruts sont désactivés.
Avec l'indicateur MD_FLAG_NOINDENTEDCODEBLOCKS , les blocs de code en retrait sont désactivés.
La spécification CommonMark déclare que toute séquence de points de code Unicode est un document de marque commune valide.
Mais, dans une inspection plus approfondie, Unicode joue tout rôle dans quelques situations très spécifiques lors de l'analyse des documents Markdown:
Pour la détection des limites des mots lors du traitement de l'accent et de l'accent mis, une certaine classification des caractères Unicode (qu'il s'agisse d'un espace ou d'une ponctuation) est nécessaire.
Pour la correspondance (insensible à la casse) d'une étiquette de référence de liaison avec la définition de référence de liaison correspondante, le pliage de cas Unicode est utilisé.
Pour traduire des entités HTML (par exemple & ) et des références de caractères numériques (par exemple # ou ಫ ) dans leurs équivalents Unicode.
Cependant, la note MD4C laisse cette traduction sur le rendu / application; Comme le rendu est censé savoir vraiment le codage de sortie et s'il doit vraiment effectuer ce type de traduction. (Par exemple, lorsque le rendu produit HTML, il peut laisser les entités non traduites et différer le travail à un navigateur Web.)
MD4C s'appuie sur cette propriété de la marque commune et la mise en œuvre est, dans une large mesure, encodante-agtique. La plupart du code MD4C suppose seulement que le codage de votre choix est compatible avec ASCII. C'est-à-dire que les points de code inférieurs à 128 ont les mêmes valeurs numériques que ASCII.
Toute entrée MD4C ne comprend pas est simplement considérée comme faisant partie du texte du document et envoyée aux fonctions de rappel du rendu inchangé.
Les deux situations (détection des limites des mots et correspondance de référence des liens) où MD4C doit comprendre que Unicode est géré comme spécifié par les macros de préprocesseur suivant (comme spécifié au moment où MD4C est en cours de construction):
Si le préprocesseur MACRO MD4C_USE_UTF8 est défini, MD4C suppose UTF-8 pour la détection des limites du mot et pour l'appariement insensible au cas des étiquettes de liaison.
Lorsqu'aucune de ces macros n'est explicitement utilisée, c'est le comportement par défaut.
Sur Windows, si le préprocesseur MACRO MD4C_USE_UTF16 est défini, MD4C utilise WCHAR au lieu de char et suppose le codage UTF-16 dans ces situations. (UTF-16 est ce que les développeurs Windows appellent généralement "Unicode" et avec quoi Win32API fonctionne généralement.)
Notez que parce que cette macro affecte également les types de md4c.h , vous devez définir la macro à la fois lors de la construction de MD4C ainsi que lorsque vous y compris md4c.h
Notez également que cela n'est pris en charge que dans l'analyseur ( md4c.[hc] ). Le HTML Renderer ne prend pas en charge cela et vous devrez rédiger votre propre rendu personnalisé pour utiliser cette fonctionnalité.
Si le préprocesseur MACRO MD4C_USE_ASCII est défini, MD4C ne prend rien d'autre qu'une entrée ASCII.
Cela signifie effectivement que les caractères blancs d'espace ou de ponctuation non ASCII ne seront pas reconnus comme tels et que la correspondance de référence des liens fonctionnera de manière insensible au cas uniquement pour les lettres ASCII ( [a-zA-Z] ).
L'API de l'analyseur est assez bien documentée dans les commentaires du md4c.h De même, l'API Markdown-to-HTML est décrite dans son en-tête md4c-html.h .
Il y a aussi un Wiki de projet qui fournit une documentation plus complète. Cependant, notez qu'il est incomplet et certains détails peuvent être quelque peu dépassés.
Q: Comment MD4C se compare-t-il aux autres analyseurs de Markdown?
R: Certaines autres implémentations combinent Markdown Parser et Generator HTML en un seul code enchevêtré caché derrière une interface qui permet simplement la conversion de Markdown à HTML. Ils sont souvent inutilisables si vous souhaitez traiter l'entrée d'une autre manière.
Deuxièmement, la plupart des analyseurs (sinon tous; au moins dans le cadre de la langue C / C ++) sont des analyseurs complets de type DOM: ils construisent une représentation de la syntaxe abstraite (AST) de l'ensemble du document Markdown. Cela prend du temps et cela conduit à une plus grande empreinte mémoire.
Construire AST est tout à fait très bien tant que vous en avez besoin. Si vous ne le faites pas, il y a de très grandes chances que l'utilisation de MD4C soit sensiblement plus rapide et moins faim en termes de consommation de mémoire.
Enfin et surtout, certains analyseurs de démarque sont mis en œuvre de manière naïve. Lorsqu'ils sont nourris avec un modèle d'entrée intelligemment conçu, ils peuvent présenter des temps d'analyse quadratiques (ou encore pires). Ce que MD4C peut encore analyser une fraction de seconde peut se transformer en longues minutes ou peut-être des heures avec eux. Par conséquent, lorsqu'un tel analyseur naïf est utilisé pour traiter une entrée d'une source non fiable, la possibilité d'attaques de déni de service devient un véritable danger.
Beaucoup de nos efforts ont été consacrés à la fourniture de temps d'analyse linéaire, quel que soit le type d'entrée folle, l'analyseur MD4C est nourri. (Si vous rencontrez un modèle d'entrée qui conduit à un temps d'analyse sous-linéaire, n'hésitez pas et ne le signalez pas comme un bogue.)
Q: MD4C effectue-t-il une validation d'entrée?
R: Non. Et nous en sommes fiers. :-)
La spécification Commonmark indique que toute séquence de caractères Unicode est un document de démarrage valide. (En pratique, cela signifie plus ou moins toujours le codage UTF-8.)
En d'autres termes, selon les spécifications, peu importe que certaines constructions de syntaxes Markdown soient en quelque sorte brisées ou non. S'il est cassé, il ne sera pas reconnu et l'analyseur devrait le voir comme un texte textuel.
MD4C va plus loin: il considère toute séquence d'octets comme une entrée valide, suivant complètement la philosophie Gigo (ordures à l'ordonnance). C'est-à-dire que toute séquence d'octets UTF-8 mal formée se propagera au rappel respectif dans le cadre du texte.
Si vous devez valider que l'entrée est, par exemple, un document UTF-8 bien formé, vous devez le faire par vous-même. Le moyen le plus simple de le faire est de simplement valider l'ensemble du document avant de le passer à l'analyseur MD4C.
MD4C est couvert par la licence MIT, voir le fichier LICENSE.md .
Ports et liaisons à d'autres langues:
Commonmark-d: Port de MD4C à D langage.
Markdown-WASM: Port de MD4C à WebAssembly.
Pymd4c: liaisons Python pour md4c
Logiciel utilisant MD4C:
IMGUI_MD: Rendu Markdown pour cher imgui
Assembleur Markdown Monolith: un outil de ligne de commande pour construire des livres basés sur un navigateur.
QOWNNOTES: Un bloc-notes de fichier en texte brut et un gestionnaire de liste ToDo avec Markdown Support et OwnCloud / NextCloud Intégration.
QT: Cadre GUI C ++ multiplateforme.
Texrosaurus: éditeur de texte multiplateforme basé sur Qt et Sciltilla.
8e: langage de programmation concaténatif multiplateforme.
