md4c
1.0.0
MD4C significa "Markdown para C" y de eso se trata exactamente este proyecto.
En resumen, Markdown es el lenguaje de marcado en el que se escribe este archivo README.md .
Los siguientes recursos pueden explicar más si no está familiarizado con él:
MD4C es la implementación de Parser de Markdown en C, con las siguientes características:
Cumplimiento: en general, MD4C tiene como objetivo cumplir con la última versión de la especificación Commonmark. Actualmente, cumplimos totalmente con Commonmark 0.31.
Extensiones: MD4C admite algunas extensiones comúnmente solicitadas y aceptadas. Vea abajo.
Rendimiento: MD4C es muy rápido.
Compáctica: el analizador MD4C se implementa en un archivo de origen y un archivo de encabezado. No hay dependencias más que la biblioteca C estándar.
Incrustación: el analizador MD4C es fácil de reutilizar en otros proyectos, su API es muy sencilla: en realidad solo hay una función, md_parse() .
Modelo de empuje: MD4C analiza el documento completo y llama a pocas funciones de devolución de llamada proporcionadas por la aplicación para informarle sobre un inicio/final de cada bloque, un inicio/final de cada tramo y con cualquier contenido textual.
Portabilidad: MD4C construye y funciona en Windows y OSE que cumplen con POSIX. (Debería ser simple hacer que se ejecute también en la mayoría de las otras plataformas, al menos mientras la plataforma proporcione la biblioteca estándar C, incluida una administración de memoria de montón).
Codificación: MD4C por defecto espera que la codificación UTF-8 del documento de entrada. Pero se puede compilar para reconocer a los caracteres de control solo ASCI-(es decir, para deshabilitar todo el código específico de Unicode), o (en Windows) esperar que UTF-16 (es decir, lo que se llama Windows comúnmente solo "Unicode"). Vea más detalles a continuación.
Licencia permisiva: MD4C está disponible bajo la licencia MIT.
Si solo necesita analizar un documento de Markdown, debe incluir md4c.h y Link contra la Biblioteca MD4C ( -lmd4c ); o alternativamente agregue md4c.[hc] directamente a su base de código, ya que el analizador solo se implementa en el archivo de origen C único.
La función principal proporcionada es md_parse() . Se necesita un texto en la sintaxis de Markdown y un puntero a una estructura que proporciona punteros a varias funciones de devolución de llamada.
Como md_parse() procesa la entrada, llama a las devoluciones de llamada (al ingresar o dejar cualquier bloque o tramo de reducción; y al emitir cualquier contenido textual del documento), lo que permite que la aplicación lo convierta en otro formato o lo rinde en la pantalla.
Si necesita convertir Markdown en HTML, incluya md4c-html.h y enlace contra la biblioteca md4c-html ( -lmd4c-html ); o alternativamente agregue las fuentes md4c.[hc] , md4c-html.[hc] y entity.[hc] en su base de código.
Para convertir una entrada de Markdown, llame a la función md_html() . Toma la entrada de Markdown y llama a la función de devolución de llamada proporcionada. La devolución de llamada se alimenta con fragmentos de la salida HTML. La implementación típica de la devolución de llamada solo agrega los fragmentos en un búfer o los escribe en un archivo.
El comportamiento predeterminado es reconocer solo la sintaxis de Markdown definida por la especificación CommonMark.
Sin embargo, con las banderas apropiadas, el comportamiento se puede ajustar para habilitar algunas extensiones:
Con la bandera MD_FLAG_COLLAPSEWHITESPACE , un espacio blanco no trivial se colapsan en un solo espacio.
Con la bandera MD_FLAG_TABLES , se admiten tablas de estilo GitHub.
Con la bandera MD_FLAG_TASKLISTS , se admiten listas de tareas de estilo GitHub.
Con la bandera MD_FLAG_STRIKETHROUGH , los tramos de ataque están habilitados (texto encerrado en marcas de Tilde, por ejemplo ~foo bar~ ).
Con la bandera MD_FLAG_PERMISSIVEURLAUTOLINKS AUTOLINKS DE URL PERMISSIVOS (no se admiten en < ) >
Con la bandera MD_FLAG_PERMISSIVEEMAILAUTOLINKS , se admiten autolinks de correo electrónico permisivos (no encerrados en < > .
Con la bandera MD_FLAG_PERMISSIVEWWWAUTOLINKS Permisive WWW Autolinks sin ningún esquema especificado (por ejemplo, se admiten www.example.com ). MD4C luego asume http: esquema.
Con la bandera MD_FLAG_LATEXMATHSPANS LATEX MATH CAST ( $...$ ) y los tramos de matemáticas de pantalla de látex ( $$...$$ ) son compatibles. (Tenga en cuenta que el renderizador HTML los genera literalmente en una etiqueta personalizada <x-equation> .)
Con la bandera MD_FLAG_WIKILINKS , son compatibles con los enlaces de estilo wiki ( [[link label]] y [[target article|link label]] ). (Tenga en cuenta que el renderizador HTML los genera en una etiqueta personalizada <x-wikilink> .)
Con la bandera MD_FLAG_UNDERLINE , Subserscore ( _ ) denota un subrayado en lugar de un énfasis ordinario o un fuerte énfasis.
Pocas características de Commonmark (aquellas que algunas personas ven como características erróneas) pueden deshabilitarse con las siguientes banderas:
Con la bandera MD_FLAG_NOHTMLSPANS o MD_FLAG_NOHTMLBLOCKS , los bloques HTML o HTML en línea sin procesar respectivamente están deshabilitados.
Con la bandera MD_FLAG_NOINDENTEDCODEBLOCKS , los bloques de código sangrado están deshabilitados.
La especificación de CommonMark declara que cualquier secuencia de puntos de código Unicode es un documento válido de Commonmark.
Pero, bajo una inspección más cercana, Unicode juega cualquier papel en pocas situaciones muy específicas al analizar los documentos de Markdown:
Para la detección de límites de palabras al procesar el énfasis y el fuerte énfasis, se necesita cierta clasificación de caracteres Unicode (ya sea un espacio en blanco o una puntuación).
Para la coincidencia (insensible al caso) de una etiqueta de referencia de enlace con la definición de referencia del enlace correspondiente, se utiliza el plegamiento de casos unicode.
Para traducir las entidades HTML # & Ej ಫ
Sin embargo, la nota de MD4C deja esta traducción en el renderizador/aplicación; Como se supone que el renderizador conoce realmente la codificación de la salida y si realmente necesita realizar este tipo de traducción. (Por ejemplo, cuando el renderizador emite HTML, puede dejar que las entidades no se traduzcan y diferir el trabajo a un navegador web).
MD4C se basa en esta propiedad del CommonMark y la implementación es, en gran medida, codificando el agnóstico. La mayor parte del código MD4C solo supone que la codificación de su elección es compatible con ASCII. Es decir, que los puntos de código inferiores a 128 tienen los mismos valores numéricos que ASCII.
Cualquier entrada MD4C no entiende simplemente se ve como parte del texto del documento y se envía a las funciones de devolución de llamada del renderizador sin cambios.
Las dos situaciones (Detección de límite de palabras y la coincidencia de referencia de enlace) donde MD4C tiene que comprender Unicode se manejan como se especifica por las siguientes macros preprocesador (como se especifica en el momento en que se está construyendo MD4C):
Si se define el preprocesador Macro MD4C_USE_UTF8 , MD4C asume UTF-8 para la detección de límites de palabras y para la coincidencia insensible al caso de las etiquetas de enlace.
Cuando ninguna de estas macros se usa explícitamente, este es el comportamiento predeterminado.
En Windows, si se define el preprocesador Macro MD4C_USE_UTF16 , MD4C usa WCHAR en lugar de char y asume la codificación UTF-16 en esas situaciones. (UTF-16 es lo que los desarrolladores de Windows generalmente llaman solo "unicode" y con lo que Win32api generalmente funciona).
Tenga en cuenta que debido a que esta macro afecta también los tipos en md4c.h , debe definir la macro tanto al construir MD4C como cuando se incluye md4c.h
También tenga en cuenta que esto solo es compatible con el analizador ( md4c.[hc] ). El renderizador HTML no admite esto y tendrá que escribir su propio renderizador personalizado para usar esta función.
Si se define el preprocesador Macro MD4C_USE_ASCII , MD4C no asume nada más que una entrada ASCII.
Eso significa efectivamente que los caracteres en blanco o puntos de puntuación no ASCII no se reconocerán como tales y que la coincidencia de referencia de enlace funcionará de una manera insensible al caso solo para las letras ASCII ( [a-zA-Z] ).
La API del analizador está bastante bien documentado en los comentarios en el md4c.h Del mismo modo, la API Markdown a HTML se describe en su encabezado md4c-html.h .
También hay Wiki Project que proporciona una documentación más completa. Sin embargo, tenga en cuenta que está incompleto y algunos detalles pueden estar algo desactualizados.
P: ¿Cómo se compara MD4C con otros analizadores de Markdown?
R: Algunas otras implementaciones combinan el analizador de Markdown y el generador HTML en un solo código enredado oculto detrás de una interfaz que solo permite la conversión de Markdown a HTML. A menudo son inutilizables si desea procesar la entrada de alguna otra manera.
En segundo lugar, la mayoría de los analizadores (si no todos; al menos dentro del alcance del lenguaje C/C ++) son analizadores completos de DOM: construyen representación de árbol de sintaxis abstracta (AST) de todo el documento de Markdown. Eso lleva tiempo y conduce a una huella de memoria más grande.
Construir AST está completamente bien mientras lo necesite. Si no lo hace, existe una gran posibilidad de que el uso de MD4C sea sustancialmente más rápido y menos hambriento en términos de consumo de memoria.
Por último, pero no menos importante, algunos analizadores de Markdown se implementan de manera ingenua. Cuando se alimentan con un patrón de entrada inteligente, pueden exhibir tiempos de análisis cuadráticos (o incluso peores). Lo que MD4C aún puede analizar en una fracción de segundo puede convertirse en largos minutos o posiblemente horas con ellos. Por lo tanto, cuando se utiliza un analizador tan ingenuo para procesar una entrada de una fuente no confiable, la posibilidad de ataques de denegación de servicio se convierte en un peligro real.
Gran parte de nuestro esfuerzo se dedicó a proporcionar tiempos de análisis lineales, sin importar con qué tipo de entrada loca se alimente con el analizador MD4C. (Si se encuentra con un patrón de entrada que conduce a un tiempo de análisis sublineal, no lo dude y lo reporte como un error).
P: ¿MD4C realiza alguna validación de entrada?
R: No. Y estamos orgullosos de ello. :-)
La especificación de CommonMark establece que cualquier secuencia de caracteres Unicode es un documento de marcado válido. (En la práctica, esto más o menos siempre significa codificación UTF-8).
En otras palabras, según la especificación, no importa si alguna construcción de sintaxis de Markdown está rota o no. Si está roto, no se reconocerá y el analizador debería verlo como un texto literal.
MD4C lleva esto un paso más allá: ve cualquier secuencia de bytes como una entrada válida, siguiendo completamente la filosofía de GIGO (basura adentro, basura). Es decir, cualquier secuencia de bytes UTF-8 mal formada se propagará a la devolución de llamada respectiva como parte del texto.
Si necesita validar que la entrada es, por ejemplo, un documento UTF-8 bien formado, debe hacerlo por su cuenta. La forma más fácil de hacer esto es simplemente validar todo el documento antes de pasarlo al analizador MD4C.
MD4C está cubierto con la licencia MIT, consulte la LICENSE.md de archivo.
Puertos y enlaces a otros idiomas:
CommonMark-D: Puerto de MD4C a D Language.
Markdown-Wasm: Puerto de MD4C a WebAssembly.
PYMD4C: Python Bindings para MD4C
Software que usa MD4C:
IMGUI_MD: Renderizador de Markdown para querida imgui
Ensamblador de monolito de Markdown: una herramienta de línea de comandos para construir libros basados en navegador.
QOWNNOTES: un archivo de archivo de texto sin formato y un administrador de listas de TODO con soporte de Markdown y su integración OwnCloud / NextCloud.
QT: marco de GUI C ++ multiplataforma.
Textosaurus: editor de texto multiplataforma basado en QT y Scintilla.
8º: lenguaje de programación concatenativo multiplataforma.
