md4c
1.0.0
O MD4C significa "Markdown for C" e é exatamente disso que se trata este projeto.
Em resumo, o Markdown é o idioma de marcação que este arquivo README.md está escrito.
Os seguintes recursos podem explicar mais se você não estiver familiarizado com isso:
O MD4C é a implementação do analisador de Markdown em C, com os seguintes recursos:
Conformidade: Geralmente, o MD4C pretende estar em conformidade com a versão mais recente do Commonmark Specification. Atualmente, somos totalmente compatíveis com o Commonmark 0.31.
Extensões: o MD4C suporta algumas extensões comumente solicitadas e aceitas. Veja abaixo.
Desempenho: MD4C é muito rápido.
Compactação: o analisador MD4C é implementado em um arquivo de origem e um arquivo de cabeçalho. Não há outras dependências além da biblioteca C Standard.
Incorporação: o analisador MD4C é fácil de reutilizar em outros projetos, sua API é muito direta: na verdade, existe apenas uma função, md_parse() .
Push Model: MD4C analisa o documento completo e chama poucas funções de retorno de chamada fornecidas pelo aplicativo para informá -lo sobre um início/final de cada bloco, um início/final de cada período e com qualquer conteúdo textual.
Portabilidade: o MD4C constrói e trabalha em Windows e oses compatíveis com POSIX. (Deve ser simples fazê -lo funcionar também na maioria das outras plataformas, pelo menos enquanto a plataforma fornecer biblioteca padrão C, incluindo um gerenciamento de memória de heap.)
Codificação: MD4C Por padrão, espera que a codificação UTF-8 do documento de entrada. Mas pode ser compilado para reconhecer os caracteres de controle ascii (ou seja, para desativar todo o código específico do Unicode) ou (no Windows) espera que o UTF-16 (ou seja, o que está no Windows comumente chamado de "unicode"). Veja mais detalhes abaixo.
Licença permissiva: o MD4C está disponível sob a licença do MIT.
Se você precisar apenas analisar um documento de marcação, você precisa incluir md4c.h e link na biblioteca MD4C ( -lmd4c ); ou, alternativamente, adicione md4c.[hc] diretamente à sua base de código, pois o analisador é implementado apenas no arquivo de origem C único.
A função principal fornecida é md_parse() . É necessário um texto na sintaxe do Markdown e um ponteiro para uma estrutura que fornece ponteiros para várias funções de retorno de chamada.
À medida que md_parse() processa a entrada, ele chama os retornos de chamada (ao entrar ou deixar qualquer bloco de marcação ou extensão; e ao emitir qualquer conteúdo textual do documento), permitindo que o aplicativo o converta em outro formato ou o renderize na tela.
Se você precisar converter o Markdown em HTML, inclua md4c-html.h e link na biblioteca md4c-html ( -lmd4c-html ); ou, alternativamente, adicione as fontes md4c.[hc] , md4c-html.[hc] e entity.[hc] na sua base de código.
Para converter uma entrada de marcação, ligue para md_html() função. Ele pega a entrada de marcação e chama a função de retorno de chamada fornecida. O retorno de chamada é alimentado com pedaços da saída HTML. A implementação típica de retorno de chamada apenas anexa os pedaços em um buffer ou os grava em um arquivo.
O comportamento padrão é reconhecer apenas a sintaxe de marcação definida pela especificação Commonmark.
No entanto, com bandeiras apropriadas, o comportamento pode ser ajustado para permitir algumas extensões:
Com o sinalizador MD_FLAG_COLLAPSEWHITESPACE , um espaço de branco não trivial é colapso em um único espaço.
Com a bandeira MD_FLAG_TABLES , as tabelas no estilo Github são suportadas.
Com o sinalizador MD_FLAG_TASKLISTS , as listas de tarefas no estilo GitHub são suportadas.
Com o sinalizador MD_FLAG_STRIKETHROUGH , os vãos de greve são ativados (texto fechado em marcas tilde, por exemplo, ~foo bar~ ).
Com o sinalizador MD_FLAG_PERMISSIVEURLAUTOLINKS Autolinks > URL permissivos (não fechados em < ) são suportados.
Com o sinalizador MD_FLAG_PERMISSIVEEMAILAUTOLINKS , os autolinks permissivos de email (não fechados em < > são suportados.
Com o sinalizador MD_FLAG_PERMISSIVEWWWAUTOLINKS permissivo www Autolinks sem qualquer esquema especificado (por exemplo, www.example.com ). MD4C então assume http: Scheme.
Com a bandeira MD_FLAG_LATEXMATHSPANS LATEX MATH SPANS ( $...$ ) e a tela de matemática do LATEX ( $$...$$ ) são suportados. (Observe que o renderizador HTML os produz literalmente em uma tag personalizada <x-equation> .)
Com o sinalizador MD_FLAG_WIKILINKS , os links no estilo wiki ( [[link label]] e [[target article|link label]] ] são suportados. (Observe que o renderizador HTML os produz em uma tag personalizada <x-wikilink> .)
Com o sinalizador MD_FLAG_UNDERLINE , o sublinhado ( _ ) indica um sublinhado em vez de uma ênfase comum ou forte ênfase.
Poucos recursos da Commonmark (aqueles que algumas pessoas vêem como mal-humoros) podem ser desativados com as seguintes bandeiras:
Com o sinalizador MD_FLAG_NOHTMLSPANS ou MD_FLAG_NOHTMLBLOCKS , html em linha bruta ou blocos html brutos estão desativados.
Com o sinalizador MD_FLAG_NOINDENTEDCODEBLOCKS , os blocos de código recuados estão desativados.
A especificação Commonmark declara que qualquer sequência de pontos de código Unicode é um documento comum de marca comum.
Mas, sob uma inspeção mais detalhada, o Unicode desempenha qualquer papel em poucas situações muito específicas ao analisar documentos de marcação:
Para a detecção dos limites das palavras ao processar a ênfase e a forte ênfase, é necessária alguma classificação de caracteres unicode (seja um espaço em branco ou uma pontuação).
Para correspondência (insensível a casos) de um rótulo de referência de link com a definição de referência de link correspondente, o dobramento do caso Unicode é usado.
Para traduzir entidades HTML ( & exemplo, referências de caracteres numéricas (por exemplo # ou ಫ ) em seus equivalentes unicode.
No entanto, o MD4C deixa esta tradução no renderizador/aplicativo; Como o renderizador deve realmente saber a codificação de saída e se realmente precisa executar esse tipo de tradução. (Por exemplo, quando o renderizador produzir html, pode deixar as entidades sem tradução e adiar o trabalho a um navegador da web.)
O MD4C conta com essa propriedade da marca comum e a implementação é, em grande parte, codificação-agnóstica. A maior parte do código MD4C assume apenas que a codificação de sua escolha é compatível com o ASCII. Ou seja, os pontos de código abaixo de 128 têm os mesmos valores numéricos que as ASCII.
Qualquer entrada MD4C não entende simplesmente é vista como parte do texto do documento e enviada para as funções de retorno de chamada do renderizador inalteradas.
As duas situações (detecção de limites e correspondência de referência de links), onde o MD4C precisa entender o Unicode é tratado conforme especificado pelas seguintes macros pré -processador (conforme especificado no momento em que o MD4C está sendo construído):
Se o pré-processador macro MD4C_USE_UTF8 for definido, o MD4C assumirá o UTF-8 para a detecção de limites da palavra e para a correspondência insensível ao caso dos rótulos de link.
Quando nenhuma dessas macros é explicitamente usada, esse é o comportamento padrão.
No Windows, se o pré-processador macro MD4C_USE_UTF16 for definido, o MD4C usa WCHAR em vez de char e assume a codificação UTF-16 nessas situações. (UTF-16 é o que os desenvolvedores do Windows geralmente chamam apenas de "Unicode" e com o que o Win32API geralmente funciona.)
Observe que, como essa macro afeta também os tipos no md4c.h , você deve definir a macro ao criar MD4C, bem como ao incluir md4c.h
Observe também que isso é suportado apenas no analisador ( md4c.[hc] ). O renderizador HTML não suporta isso e você terá que escrever seu próprio renderizador personalizado para usar esse recurso.
Se o pré -processador macro MD4C_USE_ASCII for definido, o MD4C assume nada além de uma entrada ASCII.
Isso significa efetivamente que os caracteres não-ASCII WhiteSpace ou Pontation não serão reconhecidos como tal e que a correspondência de referência de link funcionará de uma maneira insensível ao caso apenas para letras ASCII ( [a-zA-Z] ).
A API do analisador está muito bem documentada nos comentários no md4c.h Da mesma forma, a API Markdown-to-HTML é descrita em seu cabeçalho md4c-html.h .
Há também o Wiki do projeto que fornece uma documentação mais abrangente. No entanto, observe que está incompleto e alguns detalhes podem estar um pouco desatualizados.
P: Como o MD4C se compara a outros analisadores de marcação?
R: Algumas outras implementações combinam o analisador de marcação e o gerador HTML em um único código emaranhado escondido por trás de uma interface que apenas permite a conversão do Markdown em HTML. Eles geralmente são inutilizáveis se você quiser processar a entrada de qualquer outra maneira.
Segundo, a maioria dos analisadores (se não todos eles; pelo menos dentro do escopo da linguagem C/C ++) são analisadores completos do tipo DOM: eles constroem a representação abstrata da árvore de sintaxe (AST) de todo o documento de marcação. Isso leva tempo e leva a uma pegada de memória maior.
Construir AST é completamente bom, desde que você precise. Caso contrário, há uma chance muito alta de que o uso do MD4C seja substancialmente mais rápido e com menos fome em termos de consumo de memória.
Por último, mas não menos importante, alguns analisadores de marcação são implementados de maneira ingênua. Quando alimentados com um padrão de entrada de forma inteligente, eles podem exibir tempos de análise quadrática (ou pior ainda). O que o MD4C ainda pode analisar em uma fração do segundo pode se transformar em longos minutos ou possivelmente horas com eles. Portanto, quando um analisador tão ingênuo é usado para processar uma entrada de uma fonte não confiável, a possibilidade de ataques de negação de serviço se torna um perigo real.
Muito do nosso esforço foi necessário para fornecer tempos de análise linear, independentemente do tipo de contribuição louca que o analisador MD4C é alimentado. (Se você encontrar um padrão de entrada que leve a um tempo de análise sub-linear, não hesite e denuncie-o como um bug.)
P: O MD4C realiza alguma validação de entrada?
A: Não. E estamos orgulhosos disso. :-)
A Specificação Commonmark afirma que qualquer sequência de caracteres Unicode é um documento de marcação válido. (Na prática, isso mais ou menos sempre significa codificação UTF-8.)
Em outras palavras, de acordo com a especificação, não importa se alguma construção de sintaxe de marcação está de alguma forma quebrada ou não. Se estiver quebrado, não será reconhecido e o analisador deve vê -lo exatamente como um texto literal.
O MD4C leva isso um passo adiante: vê qualquer sequência de bytes como uma entrada válida, seguindo completamente a filosofia gigo (lixo, lixo fora). Ou seja, qualquer sequência de bytes UTF-8 mal formada será propagada para o respectivo retorno de chamada como parte do texto.
Se você precisar validar que a entrada é, digamos, um documento UTF-8 bem formado, você deve fazê-lo por conta própria. A maneira mais fácil de fazer isso é simplesmente validar todo o documento antes de passá -lo para o analisador MD4C.
O MD4C é coberto com licença do MIT, consulte o arquivo LICENSE.md .
Portas e ligações a outros idiomas:
Commonmark-D: Porta do MD4C para D Language.
Markdown-wasm: Porta do MD4C para WebAssembly.
Pymd4c: ligações de python para md4c
Software usando MD4C:
imgui_md: renderizador de markdown para caro imgui
Monolith Monolith Monolith: uma ferramenta de linha de comando para construir livros baseados no navegador.
QownNotes: um arquivo de texto em texto simples e gerente de listar com suporte de rekdown e integração OwnCloud / NextCloud.
QT: estrutura C ++ GUI da plataforma cruzada.
Textosaurus: editor de texto de plataforma cruzada com base no QT e Scintilla.
8: linguagem de programação concatenativa de plataforma cruzada.
