md4c
1.0.0
MD4C означает «Markdown for C», и это именно то, о чем этот проект.
Короче говоря, Markdown - это язык разметки, в котором написан файл README.md .
Следующие ресурсы могут объяснить больше, если вы не знакомы с ним:
MD4C - это реализация синтаксического анализатора Markdown в C, со следующими функциями:
Соответствие: Как правило, MD4C стремится соответствовать последней версии спецификации Commonmark. В настоящее время мы полностью соответствуем Commonmark 0,31.
Расширения: MD4C поддерживает некоторые общепринятые и принятые расширения. См. ниже.
Производительность: MD4C очень быстро.
Компактность: анализатор MD4C реализован в одном исходном файле и в одном файле заголовка. Нет никаких зависимостей, кроме стандартной библиотеки C.
Внедрение: анализатор MD4C легко использовать в других проектах, его API очень прост: на самом деле есть только одна функция, md_parse() .
Push Model: MD4C анализирует полный документ и вызывает несколько функций обратного вызова, предоставленных приложением, чтобы сообщить его о начале/конце каждого блока, запуска/конец каждого пролета и с любым текстовым содержимым.
Портативность: MD4C строит и работает на Windows и POSIX-совместимость OSES. (Должно быть просто запустить его также на большинстве других платформ, по крайней мере, до тех пор, пока платформа предоставляет стандартную библиотеку C, включая управление памятью кучи.)
Кодирование: MD4C по умолчанию ожидает кодирования UTF-8 входного документа. Но его можно собрать для распознавания контрольных символов только ASCII (то есть отключения всего кода, специфичного для юникода), или (в Windows), чтобы ожидать UTF-16 (то есть то, что в Windows обычно называется «Unicode»). Смотрите более подробную информацию ниже.
Разрешительная лицензия: MD4C доступна по лицензии MIT.
Если вам нужно просто анализировать документ Markdown, вам необходимо включить md4c.h и ссылку с библиотекой MD4C ( -lmd4c ); Или альтернативно добавьте md4c.[hc]
Основной предоставленной функцией является md_parse() . Он требует текста в синтаксисе разметки и указатель на структуру, которая дает указатели на несколько функций обратного вызова.
Поскольку md_parse() обрабатывает вход, он вызывает обратные вызовы (при вводе или оставлении любого блока разметки или пролета; и при выводе любого текстового содержимого документа), что позволяет приложению преобразовать его в другой формат или отображать на экране.
Если вам нужно преобразовать разметку в HTML, включите md4c-html.h и ссылку с библиотекой MD4C-HTML ( -lmd4c-html ); Или альтернативно добавьте источники md4c.[hc] , md4c-html.[hc] entity.[hc]
Чтобы преобразовать вход разметки, вызовите функцию md_html() . Он принимает вход разметки и вызывает предоставленную функцию обратного вызова. Обратный вызов питается кусочками вывода HTML. Типичная реализация обратного вызова просто добавляет кусочки в буфер или записывает их в файл.
Поведение по умолчанию состоит в том, чтобы распознавать только синтаксис разметки, определяемый спецификацией Commonmark.
Однако при соответствующих флагах поведение можно настроить, чтобы включить некоторые расширения:
С флагом MD_FLAG_COLLAPSEWHITESPACE нетривиальное пробелы обрушивается в одно пространство.
С флагом MD_FLAG_TABLES поддерживаются таблицы в стиле Github.
С флагом MD_FLAG_TASKLISTS поддерживаются списки задач в стиле Github.
С флагом MD_FLAG_STRIKETHROUGH , пролеты ударов включены (текст, заключенный в отметки Тильде, например ~foo bar~ ).
С флагом MD_FLAG_PERMISSIVEURLAUTOLINKS подтверждаются разрешающие URL -аутолиней (не прилагаемые в < и > ).
С флагом MD_FLAG_PERMISSIVEEMAILAUTOLINKS , поддерживаются разрешительные ауторинкции электронной почты (не прилагаются в < и > ).
С флагом MD_FLAG_PERMISSIVEWWWAUTOLINKS подтверждаются разрешающие www Autolinks без какой -либо указанной схемы (например, www.example.com ). MD4C затем предполагает http: схема.
С флагом MD_FLAG_LATEXMATHSPANS LATEX MATH SPAN ( $...$ ) и Latex Display Math Spans ( $$...$$ ) поддерживаются. (Обратите внимание, что рендерерат HTML выводит их дословно в пользовательской теге <x-equation> .)
С флагом MD_FLAG_WIKILINKS , поддержаны ссылки в стиле вики ( [[link label]] и [[target article|link label]] (Обратите внимание, что рендеринг HTML выводит их в пользовательском теге <x-wikilink> .)
С флагом MD_FLAG_UNDERLINE подчеркивается ( _ ) обозначает подчеркивание вместо обычного акцента или сильного акцента.
Немногие особенности Commonmark (некоторые люди считают неправильные функции) могут быть отключены со следующими флагами:
С флагом MD_FLAG_NOHTMLSPANS или MD_FLAG_NOHTMLBLOCKS , необработанные html или необработанные HTML -блоки соответственно отключены.
С флагом MD_FLAG_NOINDENTEDCODEBLOCKS , отключены блоки кодов с отступом.
Спецификация Commonmark заявляет, что любая последовательность кодовых точек Unicode является допустимым документом Commonmark.
Но при более тщательной проверке Unicode играет какую -либо роль в нескольких очень специфических ситуациях, когда анализ документов отметки:
Для обнаружения границ слов при обработке акцента и сильного акцента необходима некоторая классификация символов Unicode (независимо от того, является ли это пробелом или пунктуацией).
Для (нечувствительного) сопоставления ссылочной метки ссылки с соответствующим определением ссылки на ссылку используется складывание корпуса Unicode.
Для перевода HTML -сущностей (например & ) и числовых ссылок на символ (например # ಫ ) в их эквиваленты Unicode.
Однако примечание MD4C оставляет этот перевод на рендерере/приложении; как предполагается, что рендерера действительно знает кодировку вывода и действительно ли он должен выполнить этот вид перевода. (Например, когда рендерер выводит HTML, он может оставить объекты неперечисленными и отложить работу в веб -браузер.)
MD4C полагается на это свойство Commonmark, и внедрение в значительной степени связана с кодированием. Большая часть кода MD4C только предполагает, что кодирование вашего выбора совместимо с ASCII. То есть, что кодепоинации ниже 128 имеют те же числовые значения, что и ASCII.
Любой ввод MD4C не понимает, просто рассматривается как часть текста документа и отправляется без изменений в функции обратного вызова рендерера.
Две ситуации (обнаружение границ слов и сопоставление ссылок), где MD4C должен понимать Unicode, обрабатываются в соответствии с указанными следующими препроцессорными макросами (как указано в то время, когда строится MD4C):
Если предварительный макрос MD4C_USE_UTF8 определен, MD4C предполагает UTF-8 для обнаружения границы слова и для нечувствительного к случаю сопоставления метков ссылок.
Когда ни один из этих макросов не используется явно, это поведение по умолчанию.
В Windows, если определяется препроцессорный макрос MD4C_USE_UTF16 , MD4C использует WCHAR вместо char и предполагает кодирование UTF-16 в этих ситуациях. (UTF-16-это то, что разработчики Windows обычно называют просто «Unicode», и с чем обычно работает Win32api.)
Обратите внимание, что, поскольку этот макрос влияет также на типы в md4c.h , вы должны определить макрос при создании MD4C, так и при включении md4c.h
Также обратите внимание, что это поддерживается только в анализаторе ( md4c.[hc] ). HTML Renderer не поддерживает это, и вам придется написать свой собственный пользовательский рендеринг для использования этой функции.
Если препроцессорный макрос MD4C_USE_ASCII определен, MD4C не предполагает ничего, кроме ввода ASCII.
Это эффективно означает, что неасциатические или пунктуальные символы не будут признаны как таковые, и что сопоставление ссылок на ссылки будет работать нежелательным образом только для букв ASCII ( [a-zA-Z] ).
API анализатора довольно хорошо задокументирован в комментариях в md4c.h Точно так же API Markdown-HTML описан в его заголовке md4c-html.h .
Существует также проект Wiki, который предоставляет более полную документацию. Однако обратите внимание, что это неполно, и некоторые детали могут быть несколько устаревшими.
В: Как MD4C сравнивается с другими анализаторами маркировки?
О: Некоторые другие реализации объединяют анализатор маркировки и генератор HTML в один запутанный код, скрытый за интерфейсом, который просто позволяет преобразовать от маркировки в HTML. Они часто непригодны для использования, если вы хотите обработать ввод каким -либо другим способом.
Во-вторых, большинство анализаторов (если не все из них;, по крайней мере, в рамках языка C/C ++) являются полными DOM-аналогичными анализаторами: они строят абстрактное синтаксисное дерево (AST) обо всем документе на уценке. Это требует времени, и это приводит к большему следу памяти.
Строительство AST совершенно нормально, пока вам это нужно. Если вы этого не сделаете, есть очень высокая вероятность того, что использование MD4C будет существенно быстрее и менее голодным с точки зрения потребления памяти.
И последнее, но не менее важное: некоторые анализаторы маркировки реализуются наивным образом. Когда они питались умно продуманным входным шаблоном, они могут демонстрировать квадратичные (или даже худшие) время анализа. То, что MD4C все еще может проанализировать за часть секунды, может превратиться в долгие минуты или, возможно, часы с ними. Следовательно, когда такой наивный анализатор используется для обработки ввода из ненадежного источника, возможность атак отказа в службе становятся реальной опасностью.
Большая часть наших усилий пошла на то, чтобы обеспечить линейное время разбора, независимо от того, каким сумасшедшим входным анализатором MD4C кормит. (Если вы сталкиваетесь с входной шаблоном, которая приводит к суб-линейному времени анализа, пожалуйста, не стесняйтесь и сообщите об этом как ошибку.)
В: MD4C выполняет какую -либо входную проверку?
A: Нет. И мы гордимся этим. :-)
Спецификация Commonmark гласит, что любая последовательность символов Unicode является допустимым документом Markdown. (На практике это более или менее всегда означает кодирование UTF-8.)
Другими словами, в соответствии с спецификацией, не имеет значения, является ли некоторая конструкция синтаксиса маркировки в некотором роде сломана или нет. Если он сломается, это не будет распознано, и анализатор должен увидеть его как дословный текст.
MD4C делает этот шаг дальше: он видит любую последовательность байтов как действительный вход, полностью следуя философии Жиго (мусор, мусор). То есть любая плохо сформированная последовательность UTF-8 байтов будет распространяться на соответствующий обратный вызов как часть текста.
Если вам нужно подтвердить, что вход, скажем, хорошо сформированный документ UTF-8, вы должны сделать это самостоятельно. Самый простой способ сделать это - просто проверить весь документ, прежде чем передавать его в анализатор MD4C.
MD4C покрывается лицензией MIT, см. File LICENSE.md .
Порты и привязки с другими языками:
Commonmark-D: порт MD4C-D Язык.
Markdown-Wasm: порт MD4C для Webassembly.
PYMD4C: привязки Python для MD4C
Программное обеспечение с использованием MD4C:
imgui_md: рендерер Markdown для дорогой imgui
Markdown Monolith Assembler: инструмент командной строки для строительства книг на основе браузеров.
Qownnotes: простые текстовые блокноты и менеджер Todo-List с поддержкой Markdown и интеграцией OwnCloud / NextCloud.
QT: кроссплатформенный графический интерфейс C ++.
Textosaurus: кроссплатформенный текстовый редактор на основе QT и Scintilla.
8th: кроссплатформенный язык конкатенативного программирования.
