flexmark java

Este documento fornece uma visão geral abrangente do flexmark-java, uma implementação Java de alto desempenho do analisador CommonMark Markdown. Ele detalha seus recursos, incluindo velocidade, extensibilidade e rastreamento detalhado da posição da fonte, juntamente com instruções para início rápido, extensões disponíveis e migração do pegdown. O documento também cobre suas diretrizes contínuas de desenvolvimento e contribuição.

flexmark-java

flexmark-java é uma implementação Java do analisador CommonMark (especificação 0.28) usando o

blocos primeiro, embutidos após a arquitetura de análise do Markdown.

Seus pontos fortes são velocidade, flexibilidade, AST baseado em elemento de origem Markdown com detalhes do

posição de origem até caracteres individuais de lexemas que compõem o elemento e

extensibilidade.

A API permite controle granular do processo de análise e é otimizada para análise com um grande número de

número de extensões instaladas. O analisador e as extensões vêm com muitas opções de analisador

comportamento e variações de renderização de HTML. O objetivo final é fazer com que o analisador e o renderizador sejam capazes

para imitar outros analisadores com grande grau de precisão. Isto agora está parcialmente completo com o

implementação de emulação de processador Markdown

A motivação para este projeto foi a necessidade de substituir o analisador pegdown no meu Markdown Navigator

plugin para IDEs JetBrains. pegdown tem um ótimo conjunto de recursos, mas sua velocidade em geral é menor

do que o ideal e para entrada patológica trava ou praticamente trava durante a análise.

️A versão 0.60.0 tem alterações significativas devido à reorganização, renomeação, limpeza e

otimização de classes de implementação. As alterações estão detalhadas em

Versão-0.60.0-Mudanças.

mais recente

Requisitos

Para versões 0.62.2 ou inferiores, Java 8 ou superior, compatível com Java 9+. Para versões 0.64.0 ou

acima, Java 11 ou superior.

O projeto está no Maven: com.vladsch.flexmark

O núcleo não tem dependências além de org.jetbrains:annotations:24.0.1. Para extensões, consulte

descrição da extensão abaixo.

A API ainda está evoluindo para acomodar novas extensões e funcionalidades.

Início rápido

Para Maven, adicione flexmark-all como uma dependência que inclui o núcleo e todos os módulos ao

seguinte amostra:

Fonte:

Exemplo Básico.java

Construindo via Gradle

Construindo com Android Studio

Configurações adicionais devido a arquivos duplicados:

Mais informações podem ser encontradas na documentação:

Exemplos de uso doméstico do Wiki

Detalhes da extensão

Escrevendo Extensões

Auxiliar de migração Pegdown

A classe PegdownOptionsAdapter converte sinalizadores pegdown Extensions.* em opções flexmark e

lista de extensões. Pegdown Extensions.java está incluído por conveniência e novas opções não foram encontradas

no pegdown 1.6.0. Eles estão localizados no módulo flexmark-profile-pegdown, mas você pode pegar o

fonte deste repositório: PegdownOptionsAdapter.java, Extensions.java e faça o seu próprio

versão, modificada de acordo com as necessidades do seu projeto.

Você pode passar seus sinalizadores de extensão para PegdownOptionsAdapter.flexmarkOptions(int) estático ou você

pode instanciar PegdownOptionsAdapter e usar métodos de conveniência para definir, adicionar e remover

sinalizadores de extensão. PegdownOptionsAdapter.getFlexmarkOptions() retornará uma nova cópia de

DataHolder sempre com as opções refletindo sinalizadores de extensão pegdown.

A emulação padrão flexmark-java pegdown usa análise de bloco HTML menos estrita que interrompe um

Bloco HTML em uma linha em branco. Pegdown apenas interrompe um bloco HTML em uma linha em branco se todas as tags em

o bloco HTML está fechado.

Para se aproximar do comportamento original de análise de bloco HTML pegdown, use o método que leva um

Argumento booleano strictHtml:

Também está disponível um exemplo com um resolvedor de link personalizado, que inclui resolvedor de link para

alterando URLs ou atributos de links e um renderizador de nó personalizado se você precisar substituir o

link gerado HTML.

flexmark-java tem muito mais extensões e opções de configuração do que

pegdown além das extensões disponíveis no pegdown 1.6.0.

Extensões disponíveis via PegdownOptionsAdapter

Últimas adições e alterações

Grande reorganização e limpeza de código de implementação na versão 0.60.0, consulte

Versão-0.60.0-Mudanças graças ao excelente trabalho de

Alex Karezin você pode obter uma visão geral das dependências do módulo

com capacidade de detalhar pacotes e classes.

Mesclar API para mesclar vários documentos de descontos em um único

documento.

Extensão do renderizador Docx:

Manipulação limitada de nós de atributos

Módulo extensível de conversão de HTML para Markdown:

conversor flexmark-html2md. Amostra:

HtmlToMarkdownCustomizedSample.java

Compatibilidade do módulo Java9+

Referências Enumeradas Compostas

Extensão de referências enumeradas para criação

numeração legal para elementos e títulos.

Extensão de macros para permitir que conteúdo de markdown arbitrário seja

inseridos como elementos de bloco ou embutidos, permitindo que elementos de bloco sejam usados ​​onde apenas elementos embutidos

elementos são permitidos pela sintaxe.

Markdown com sabor do GitLab para análise e

renderizando extensões de marcação do GitLab.

Módulo OSGi cortesia de Dan Klco (GitHub @klcodanr)

Media Tags Extensão do transformador de link de mídia cortesia

Cornelia Schultz (GitHub @CorneliaXaos) transforma links

usando prefixos personalizados para tags HTML5 de áudio, incorporação, imagem e vídeo.

API Translation Helper para fazer descontos na tradução

documentos mais facilmente.

Advertência Para criar conteúdo lateral em estilo de bloco. Para

documentação completa, consulte a extensão de advertência, material para MkDocs

documentação.

Referência enumerada para criar enumerados

referências para figuras, tabelas e outros elementos de remarcação.

Atributos para analisar atributos do formato {name name=value name='value' name="value" #id .class-name} atributos.

Transformador de link incorporado do YouTube

graças a Vyacheslav N. Boyko (GitHub @bvn13) transforma links simples para vídeos do YouTube em

HTML de iframe de vídeo incorporado.

Conversor Docx usando a biblioteca docx4j. Como usar:

Exemplo do DocxConverter, como personalizar:

Personalizando a renderização Docx

O desenvolvimento deste módulo foi patrocinado por

Johner Institute GmbH.

Atualize a biblioteca para ser compatível com CommonMark (especificação 0.28) e adicione

ParserEmulationProfile.COMMONMARK027 e ParserEmulationProfile.COMMONMARK028 para permitir

selecionando opções de versão de especificação específica.

API de renderização de nó personalizada com capacidade de invocar a renderização padrão para um nó substituído,

permitindo renderizações de nós personalizados que tratam apenas de casos especiais e deixam o resto ser renderizado como

habitual. resolvedor de link personalizado

Problemas Gfm e

Extensões Gfm-Users para análise e renderização # 123 e

@nome de usuário respectivamente.

Opção de análise profunda de bloco HTML para melhor manipulação de tags de texto bruto que vêm depois de outras tags

e para compatibilidade de análise de bloco HTML pegdown.

Módulo flexmark-all que inclui: núcleo, todas as extensões, formatador, JIRA e YouTrack

conversores, módulo de perfil pegdown e conversão de HTML para Markdown.

Módulo de saída de PDF

Saída de PDF usando Open HTML To PDF

Tipográfico implementado

Extensão Macro XWiki

Jekyll Tags

HTML para redução

Plug-in gerador de página Maven Markdown

Módulo Markdown Formatter para gerar AST como markdown com

opções de formatação.

Tabelas para formatador Markdown

com largura de coluna e alinhamento de tabelas de remarcação:

Lançamentos, correções de bugs, melhorias e suporte

Eu uso flexmark-java como analisador do plugin Markdown Navigator para IDEs JetBrains. eu costumo

use a versão mais recente e não lançada para corrigir bugs ou obter melhorias. Então, se você encontrar um bug que seja

um obstáculo para o seu projeto ou veja um bug na página de problemas do github marcado como corrigido para o próximo lançamento que está afetando o seu projeto, por favor me avise e poderei ajudá-lo imediatamente

faça uma nova versão para resolver seu problema. Caso contrário, deixarei correções de bugs e melhorias

acumule pensando que ninguém é afetado pelo que já está consertado.

Os pontos de extensão na API são muitos e numerosos

Existem muitas opções de extensão na API com o uso pretendido. Um bom arranque suave é o

módulo flexmark-java-samples que contém amostras simples solicitadas

extensões. O próximo melhor lugar é a fonte de uma extensão existente que possui sintaxe semelhante

ao que você deseja adicionar.

Se sua extensão estiver alinhada com a API correta, a tarefa geralmente será muito curta e agradável. Se o seu

extensão usa a API de maneira não intencional ou não segue a limpeza esperada

protocolos, você pode achar que é uma batalha difícil com um ninho de ratos de manipulação de condições if/else e

consertar um bug levando apenas à criação de outro.

Geralmente, se forem necessárias mais do que algumas dezenas de linhas para adicionar uma extensão simples, então você

estão fazendo isso errado ou falta um ponto de extensão na API. Se você olhar para todos os

extensões implementadas, você verá que a maioria são algumas linhas de código diferentes do padrão

ditado pela API. Esse é o objetivo desta biblioteca: fornecer um núcleo extensível que faça

escrever extensões é muito fácil.

As extensões maiores são flexmark-ext-tables e flexmark-ext-spec-example, a carne de

ambos têm cerca de 200 linhas de código. Você pode usá-los como um guia para estimar o tamanho do seu

extensão.

Minha própria experiência ao adicionar extensões mostra que às vezes um novo tipo de extensão é melhor

abordado com um aprimoramento de API para tornar sua implementação perfeita ou corrigindo um bug que

não estava visível antes da extensão enfatizar a API da maneira certa. Seu pretendido

a extensão pode ser apenas aquela que exige tal abordagem.

Não hesite em abrir um problema se não conseguir encontrar a resposta

A conclusão é: se você deseja implementar uma extensão ou recurso, não hesite em

abra um problema e eu lhe darei dicas sobre a melhor maneira de fazer isso. Isso pode te economizar muito

de tempo, permitindo-me melhorar a API para atender às necessidades da sua extensão antes de você investir muito

esforço infrutífero nisso.

Peço que você perceba que sou cozinheiro-chefe e lavador de garrafas neste projeto, sem um

um pingo de habilidades de fusão mental vulcana. Peço que você descreva o que deseja implementar

porque não consigo ler sua mente. Por favor, faça algum trabalho de reconhecimento em torno da fonte

código e documentação porque não posso transferir o que sei para você, sem sua vontade

esforço.

Consultoria está disponível

Se você possui um aplicativo comercial e não deseja escrever a(s) extensão(ões) sozinho ou deseja

para reduzir o tempo e esforço de implementação de extensões e integração flexmark-java, sinta-se

livre para entrar em contato comigo. Estou disponível em regime de consultoria/contratação.

Emulação de processador Markdown

Apesar do nome, commonmark não é um superconjunto nem um subconjunto de outros sabores de descontos.

Em vez disso, propõe uma especificação de sintaxe padrão e inequívoca para o original, "núcleo"

Markdown, introduzindo assim efetivamente mais um sabor. Embora flexmark seja por padrão

compatível com a marca comum, seu analisador pode ser ajustado de várias maneiras. Os conjuntos de ajustes necessários para

emular os analisadores de markdown mais comumente usados ​​​​estão disponíveis no flexmark como

ParserEmulationProfiles.

Como o nome ParserEmulationProfile indica, é apenas o analisador que é ajustado ao

sabor de redução específico. A aplicação do perfil não adiciona recursos além daqueles disponíveis em

marca comum. Se você quiser usar o flexmark para emular completamente o comportamento de outro processador de markdown,

você precisa ajustar o analisador e configurar as extensões flexmark que fornecem o adicional

recursos disponíveis no analisador que você deseja emular.

Uma reescrita do analisador de lista para controlar melhor a emulação de outros processadores de remarcação conforme

A emulação dos processadores Markdown está concluída. Adição de

predefinições do processador para emular o comportamento específico do processamento de redução desses analisadores está em um

lista curta para fazer.

Algumas famílias de emulação fazem um trabalho melhor ao emular seu alvo do que outras. A maior parte

o esforço foi direcionado para emular como esses processadores analisam Markdown padrão e listam

análise relacionada especificamente. Para processadores que estendem o Markdown original, você precisará adicionar

aquelas extensões que já estão implementadas em flexmark-java para o construtor Parser/Renderer

opções.

As extensões serão modificadas para incluir suas próprias predefinições para emulação de processador específico, se

esse processador tem uma extensão equivalente implementada.

Se você encontrar uma discrepância, abra um problema para que possa ser resolvido.

As principais famílias de processadores são implementadas e alguns membros da família também:

perfis para encapsular detalhes de configuração para variantes dentro do

família foi adicionada em 0.11.0:

História e Motivação

flexmark-java é um fork do projeto commonmark-java, modificado para gerar um AST que

reflete todos os elementos da fonte original, rastreamento completo da posição da fonte para todos os elementos

na geração AST e JetBrains Open API PsiTree mais fácil.

A API foi alterada para permitir um controle mais granular do processo de análise e otimizada para

analisando com um grande número de extensões instaladas. O analisador e as extensões vêm com muitos

opções de ajustes para comportamento do analisador e variações de renderização de HTML. O objetivo final é ter o

analisador e renderizador podem imitar outros analisadores com grande grau de precisão.

A motivação para isso foi a necessidade de substituir o analisador pegdown no plugin Markdown Navigator.

pegdown tem um ótimo conjunto de recursos, mas sua velocidade em geral é inferior ao ideal e para

a entrada patológica trava ou praticamente trava durante a análise.

commonmark-java possui uma excelente arquitetura de análise que é fácil de entender e estender.

O objetivo era garantir que a adição de rastreamento de posição de origem no AST não alterasse a facilidade

de analisar e gerar o AST mais do que o absolutamente necessário.

As razões para escolher commonmark-java como analisador são: velocidade, facilidade de compreensão, facilidade de

extensão e velocidade. Agora que reformulei o núcleo e adicionei algumas extensões, estou extremamente

satisfeito com minha escolha.

Outro objetivo era melhorar a capacidade das extensões de modificar o comportamento do analisador para que qualquer

o dialeto de markdown poderia ser implementado através do mecanismo de extensão. Opções extensíveis

API foi adicionada para permitir a configuração de todas as opções em um só lugar. Uso de analisador, renderizador e extensões

essas opções de configuração, incluindo a desativação de alguns analisadores de blocos principais.

Este é um trabalho em andamento com muitas alterações de API. Nenhuma tentativa é feita para manter a API retroativa

compatibilidade com o projeto original e até que o conjunto de recursos esteja quase completo, nem mesmo para

versões anteriores deste projeto.

Comparação de recursos

(1)

entrada patológica flexmark-java de 100.000 [analisa em 68ms, 100.000] em 57ms, 100.000

análise aninhada [] em 55 ms

(2)

entrada patológica commonmark-java de 100.000 [analisa em 30ms, 100.000] em 30ms, 100.000

análise aninhada [] em 43 ms

(3)

pegdown entrada patológica de 17 [ analisa em 650 ms, 18 [ em 1300 ms

Progresso

Estou muito satisfeito com a decisão de mudar para o analisador baseado em commonmark-java para mim mesmo

projetos. Mesmo que eu tivesse que fazer uma grande cirurgia em suas entranhas para obter a posição de fonte completa

rastreamento e AST que corresponda aos elementos de origem, é um prazer trabalhar com ele e agora é um

prazer em estender. Se você não precisa do elemento de nível de origem AST ou do resto do que flexmark-java

adicionado e CommonMark é o seu analisador de redução de destino, então eu encorajo você a usar

commonmark-java, pois é uma excelente escolha para suas necessidades e seu desempenho não

sofrer pela sobrecarga de recursos que você não usará.

Referências

Mais recente, 28 de janeiro de 2017 flexmark-java 0.13.1, intellij-markdown do CE EAP 2017, commonmark-java

0.8.0:

Razões acima:

Como esses dois arquivos representam a entrada patológica para pegdown, não os executo mais como

parte do benchmark para evitar distorções nos resultados. Os resultados estão aqui para a posteridade.

Razões acima:

Contribuindo

Solicitações pull, problemas e comentários são bem-vindos? Para solicitações pull:

Licença

Copyright (c) 2015-2016 Atlassian e outros.

Direitos autorais (c) 2016-2023, Vladimir Schneider,

Licenciado BSD (2 cláusulas), consulte o arquivo LICENSE.txt.

exemplo:

Renderizador Mitsuba 3

Documentação	Vídeos tutoriais	Linux	Mac OS	Windows	PyPI

️

Aviso

️

Actualmente existe uma grande quantidade de trabalho indocumentado e instável em curso no

o ramo master . É altamente recomendável que você use nosso

último lançamento

até novo aviso.

Se você já deseja experimentar as próximas mudanças, dê uma olhada em

este guia de portabilidade.

Deve cobrir a maioria dos novos recursos e mudanças importantes que estão por vir.

Introdução

Mitsuba 3 é um sistema de renderização orientado para pesquisa para luz direta e inversa

simulação de transporte desenvolvida na EPFL na Suíça.

Consiste em uma biblioteca principal e um conjunto de plug-ins que implementam funcionalidades

variando de materiais e fontes de luz a algoritmos de renderização completos.

Mitsuba 3 é redirecionável : isso significa que as implementações subjacentes e

estruturas de dados podem ser transformadas para realizar várias tarefas diferentes. Para

Por exemplo, o mesmo código pode simular transporte RGB escalar (clássico de um raio por vez)

ou transporte espectral diferencial na GPU. Tudo isso se baseia

Dr.Jit, um compilador just-in-time (JIT) especializado desenvolvido especificamente para este projeto.

Principais recursos

• Plataforma cruzada : Mitsuba 3 foi testado em Linux ( x86_64 ), macOS

  ( aarch64 , x8664 ) e Windows ( x8664 ).

• Alto desempenho : o compilador Dr.Jit subjacente funde o código de renderização

  em kernels que alcançam desempenho de última geração usando

  um back-end LLVM direcionado à CPU e um back-end CUDA/OptiX

  visando GPUs NVIDIA com aceleração de hardware de rastreamento de raio.

• Python primeiro : Mitsuba 3 está profundamente integrado ao Python. Materiais,

  texturas e até mesmo algoritmos de renderização completos podem ser desenvolvidos em Python,

  que o sistema compila JIT (e opcionalmente diferencia) em tempo real.

  Isso permite a experimentação necessária para pesquisas em computação gráfica e

  outras disciplinas.

• Diferenciação : Mitsuba 3 é um renderizador diferenciável, o que significa que

  pode calcular derivadas de toda a simulação em relação à entrada

  parâmetros como pose de câmera, geometria, BSDFs, texturas e volumes. Isto

  implementa algoritmos de renderização diferenciáveis ​​recentes desenvolvidos na EPFL.

• Espectral e Polarização : Mitsuba 3 pode ser usado como monocromático

  renderizador, renderizador baseado em RGB ou renderizador espectral. Cada variante pode

  opcionalmente, considere os efeitos da polarização, se desejado.

Vídeos tutoriais, documentação

Gravamos vários vídeos no YouTube que fornecem uma introdução gentil

Mitsuba 3 e Dr.Jit. Além disso você pode encontrar notebooks Juypter completos

cobrindo uma variedade de aplicações, guias de instruções e documentação de referência

em readthedocs.

Instalação

Fornecemos rodas binárias pré-compiladas via PyPI. Instalar o Mitsuba desta forma é tão simples quanto executar

 pip instalar mitsuba

na linha de comando. O pacote Python inclui treze variantes por padrão:

• scalar_rgb

• scalar_spectral

• scalarspectralpolarized

• llvmadrgb

• llvmadmono

• llvmadmono_polarized

• llvmadspectral

• llvmadspectral_polarized

• cudaadrgb

• cudaadmono

• cudaadmono_polarized

• cudaadspectral

• cudaadspectral_polarized

Os dois primeiros realizam simulação clássica de um raio por vez usando um RGB

ou representação espectral de cores, enquanto os dois últimos podem ser usados ​​para representação inversa

renderização na CPU ou GPU. Para acessar variantes adicionais, você precisará

compilar uma versão personalizada do Dr.Jit usando CMake. Por favor veja o

documentação

para obter detalhes sobre isso.

Requisitos

• Python >= 3.8

• (opcional) Para computação na GPU: Nvidia driver >= 495.89

• (opcional) Para computação vetorizada/paralela na CPU: LLVM >= 11.1

Uso

Aqui está um exemplo simples de "Hello World" que mostra como é simples renderizar um

cena usando Mitsuba 3 do Python:

 # Importe a biblioteca usando o alias "mi"import mitsuba as mi# Defina a variante do renderermi.setvariant('scalarrgb')# Carregue uma scenecene = mi.loaddict(mi.cornellbox())# Renderize a cenaimg = mi. render(scene)# Grave a imagem renderizada em um arquivo EXRmi.Bitmap(img).write('cbox.exr')

Tutoriais e cadernos de exemplo cobrindo uma variedade de aplicações podem ser encontrados

na documentação.

Sobre

Este projeto foi criado por Wenzel Jakob.

Recursos e/ou melhorias significativas no código foram contribuídos por

Sébastien Speierer,

Nicolas Roussel,

Merlin Nimier-David,

Délio Vicini,

Tizian Zeltner,

Baptiste Nicolet,

Miguel Crespo,

Vicente Leroy e

Zi Yi Zhang.

Ao usar o Mitsuba 3 em projetos acadêmicos, cite:

 @software{Mitsuba3,title = {mitsuba 3 renderer},author = {Wenzel Jakob e Sébastien Speierer e Nicolas Roussel e Merlin Nimier-David e Delio Vicini e Tizian Zeltner e Baptiste Nicolet e Miguel Crespo e Vincent Leroy e Ziyi Zhang},nota = {https://mitsuba-renderer.org},versão = {3.1.1},ano = 2022}