гибкая отметка Java

В этом документе представлен подробный обзор flexmark-java, высокопроизводительной Java-реализации парсера CommonMark Markdown. В нем подробно описаны его функции, включая скорость, расширяемость и подробное отслеживание исходной позиции, а также инструкции по быстрому запуску, доступным расширениям и переходу с привязки. В документе также описаны руководящие принципы текущего развития и вклада.

Flexmark-Java

flexmark-java — это Java-реализация парсера CommonMark (спецификация 0.28), использующая

блоки сначала, встроенные после архитектуры синтаксического анализа Markdown.

Его сильными сторонами являются скорость, гибкость, AST на основе исходных элементов Markdown с подробной информацией о

исходную позицию вплоть до отдельных символов лексем, составляющих элемент и

расширяемость.

API обеспечивает детальный контроль процесса синтаксического анализа и оптимизирован для анализа больших объемов данных.

количество установленных расширений. Парсер и расширения имеют множество возможностей для парсера.

варианты поведения и рендеринга HTML. Конечная цель состоит в том, чтобы синтаксический анализатор и рендерер могли

имитировать другие парсеры с большой степенью точности. На данный момент это частично завершено.

реализация эмуляции процессора Markdown

Мотивацией для этого проекта была необходимость заменить парсер pegdown в моем Markdown Navigator.

плагин для IDE JetBrains. pegdown имеет отличный набор функций, но его скорость в целом меньше

чем идеально и при патологическом вводе либо зависает, либо практически зависает при разборе.

️Версия 0.60.0 содержит серьезные изменения, связанные с реорганизацией, переименованием, очисткой и

оптимизация классов реализации. Изменения подробно описаны в

Версия-0.60.0-Изменения.

последний

Требования

Для версий 0.62.2 или ниже: Java 8 или выше, совместимость с Java 9+. Для версий 0.64.0 или

выше, Java 11 или выше.

Проект находится на Maven: com.vladsch.flexmark.

Ядро не имеет других зависимостей, кроме org.jetbrains:annotations:24.0.1. Информацию о расширениях см.

описание расширения ниже.

API все еще развивается для внедрения новых расширений и функций.

Быстрый старт

Для Maven добавьте flexmark-all в качестве зависимости, которая включает в себя ядро ​​и все модули.

следующий образец:

Источник:

Базовый образец.java

Сборка через Gradle

Сборка с помощью Android Studio

Дополнительные настройки из-за дубликатов файлов:

Более подробную информацию можно найти в документации:

Примеры использования Wiki Home

Подробности расширения

Написание расширений

Помощник по миграции Pegdown

Класс PegdownOptionsAdapter преобразует флаги pegdown Extensions.* в параметры flexmark и

список расширений. Pegdown Extensions.java включен для удобства, новых опций не обнаружено.

в привязке 1.6.0. Они расположены в модуле flexmark-profile-pegdown, но вы можете получить

источник из этого репозитория: PegdownOptionsAdapter.java, Extensions.java и создайте свой собственный

версия, модифицированная в соответствии с потребностями вашего проекта.

Вы можете передать флаги расширения статическому PegdownOptionsAdapter.flexmarkOptions(int) или

может создавать экземпляр PegdownOptionsAdapter и использовать удобные методы для установки, добавления и удаления

флаги расширения. PegdownOptionsAdapter.getFlexmarkOptions() вернет новую копию

DataHolder каждый раз с параметрами, отражающими флаги расширения привязки.

Эмуляция привязки flexmark-java по умолчанию использует менее строгий анализ блоков HTML, что прерывает

HTML-блок в пустой строке. Pegdown прерывает блок HTML только на пустой строке, если все теги в

блок HTML закрыт.

Чтобы приблизиться к исходному поведению анализа блока HTML с привязкой, используйте метод, который принимает

логический аргумент strictHtml:

Также доступен образец настраиваемого преобразователя ссылок, который включает преобразователь ссылок для

изменение URL-адресов или атрибутов ссылок и настраиваемого средства визуализации узлов, если вам необходимо переопределить

сгенерированная ссылка HTML.

flexmark-java имеет гораздо больше расширений и опций конфигурации, чем

pegdown в дополнение к расширениям, доступным в pegdown 1.6.0.

Доступные расширения через PegdownOptionsAdapter

Последние дополнения и изменения

Основная реорганизация и очистка кода реализации в версии 0.60.0, см.

Версия-0.60.0-Изменения благодаря отличной работе

Алекс Карезин, вы можете получить обзор зависимостей модулей

с возможностью детализации пакетов и классов.

Merge API для объединения нескольких документов уценки в один

документ.

Расширение рендерера Docx:

Обработка узла ограниченных атрибутов

Расширяемый модуль конвертера HTML в Markdown:

flexmark-html2md-конвертер. Образец:

HtmlToMarkdownCustomizedSample.java

Совместимость модулей Java9+

Составные нумерованные ссылки

Расширение перечислимых ссылок для создания

допустимая нумерация элементов и заголовков.

Расширение макросов, позволяющее использовать произвольный контент с уценкой.

вставлены как блочные или строчные элементы, что позволяет использовать блочные элементы только в строках

элементы разрешены синтаксисом.

GitLab Flavored Markdown для парсинга и

рендеринг расширений уценки GitLab.

Модуль OSGi предоставлен Дэном Клко (GitHub @klcodanr)

Медиа-теги Расширение преобразователя медиа-ссылок любезно предоставлено

Корнелия Шульц (GitHub @CorneliaXaos) преобразует ссылки

использование пользовательских префиксов для тегов HTML5 Audio, Embed, Picture и Video.

API-интерфейс Translation Helper для перевода уценки

документы проще.

Предупреждение. Создавать побочный контент в блочном стиле. Для

полную документацию см. в расширении Admonition, материале для MkDocs.

документация.

Перечислимая ссылка для создания перечислимого

ссылки на рисунки, таблицы и другие элементы уценки.

Атрибуты для анализа атрибутов вида {name name=value name='value' name="value" #id .class-name} атрибутов.

Встроенный преобразователь ссылок YouTube

благодаря Вячеславу Н. Бойко (GitHub @bvn13) преобразует простые ссылки на видео на YouTube в

встроенное видео iframe HTML.

Конвертер Docx с использованием библиотеки docx4j. Как использовать:

Образец DocxConverter, как настроить:

Настройка рендеринга Docx

Разработка этого модуля спонсировалась

Джонер Институт ГмбХ.

Обновите библиотеку, чтобы она соответствовала CommonMark (спецификация 0.28), и добавьте

ParserEmulationProfile.COMMONMARK027 и ParserEmulationProfile.COMMONMARK028, чтобы разрешить

выбор конкретных опций версии спецификации.

Пользовательский API рендеринга узлов с возможностью вызова стандартного рендеринга для переопределенного узла.

разрешение пользовательских рендерингов узлов, которые обрабатывают только особые случаи, а остальные визуализируются как

обычный. пользовательский преобразователь ссылок

Gfm-проблемы и

Расширения Gfm-Users для анализа и рендеринга #123 и

@имя-пользователя соответственно.

Опция глубокого анализа блоков HTML для лучшей обработки необработанных текстовых тегов, следующих за другими тегами.

и для совместимости синтаксического анализа блоков HTML с привязкой.

Модуль flexmark-all, который включает в себя: ядро, все расширения, форматтер, JIRA и YouTrack.

конвертеры, модуль профиля привязки и преобразование HTML в Markdown.

Модуль вывода PDF-файлов

Вывод PDF с использованием Open HTML To PDF

Типографика реализована

Расширение макросов XWiki

Джекилл Теги

HTML в уценку

Плагин генератора страниц Maven Markdown

Модуль Markdown Formatter для вывода AST в виде уценки с помощью

параметры форматирования.

Таблицы для форматтера Markdown

с шириной столбца и выравниванием таблиц уценки:

Релизы, исправления ошибок, улучшения и поддержка

Я использую flexmark-java в качестве анализатора плагина Markdown Navigator для IDE JetBrains. Я склонен

используйте последнюю, неизданную версию, чтобы исправить ошибки или получить улучшения. Поэтому, если вы обнаружите ошибку, которая

остановите показ вашего проекта или увидите ошибку на странице проблем GitHub, отмеченную как исправленную для следующего выпуска, которая влияет на ваш проект, тогда, пожалуйста, дайте мне знать, и я смогу быстро

сделайте новый выпуск для решения вашей проблемы. В противном случае я дам исправления ошибок и улучшения.

накапливать, думая, что то, что уже исправлено, ни на кого не влияет.

Точек расширения в API очень много.

В API есть множество вариантов расширения с их целевым использованием. Хороший плавный пуск – это

модуль flexmark-java-samples, который содержит простые образцы по запросу

расширения. Следующее лучшее место — это источник существующего расширения с похожим синтаксисом.

к тому, что вы хотите добавить.

Если ваше расширение соответствует правильному API, задача обычно будет очень короткой и приятной. Если ваш

расширение использует API непреднамеренным образом или не выполняет ожидаемую обработку

протоколов, вам может показаться, что это тяжелая битва с крысиным гнездом обработки условий if/else и

исправление одной ошибки приводит только к созданию другой.

Как правило, если для добавления простого расширения требуется более нескольких десятков строк, то либо вы

вы делаете это неправильно, или в API отсутствует точка расширения. Если вы посмотрите на все

реализованных расширений, вы увидите, что большинство из них представляют собой несколько строк кода, отличных от шаблона.

диктуется API. В этом и состоит цель этой библиотеки: предоставить расширяемое ядро, позволяющее

писать расширения очень просто.

Более крупные расширения — это flexmark-ext-tables и flexmark-ext-spec-example, суть

оба занимают около 200 строк кода. Вы можете использовать их в качестве ориентира для оценки размера вашего

расширение.

Мой собственный опыт добавления расширений показывает, что иногда лучше использовать новый тип расширения.

решается с помощью улучшения API, чтобы сделать его реализацию беспрепятственной, или путем исправления ошибки, которая

не было видно до того, как расширение правильно нагрузило API. Ваш предполагаемый

расширение может быть именно тем, что требует такого подхода.

Не стесняйтесь открывать вопрос, если не можете найти ответ

Вывод таков: если вы хотите реализовать расширение или функцию, не стесняйтесь

откройте проблему, и я подскажу вам, как лучше всего ее решить. Это может сэкономить вам много

времени, позволив мне улучшить API для удовлетворения потребностей вашего расширения, прежде чем вы вложите много

бесплодные усилия в этом направлении.

Я прошу вас осознать, что я главный повар и мойщик бутылок в этом проекте, без

йота вулканских навыков слияния разумов. Я прошу вас описать, что вы хотите реализовать.

потому что я не могу читать твои мысли. Пожалуйста, проведите разведывательную работу вокруг источника.

код и документацию, потому что я не могу передать вам то, что знаю, без вашей воли.

усилие.

Консультация доступна

Если у вас есть коммерческое приложение, и вы не хотите писать расширения самостоятельно или хотите

чтобы сократить время и усилия по внедрению расширений и интеграции flexmark-java, почувствуйте

свободен связаться со мной. Я доступен на консультационной/контрактной основе.

Эмуляция процессора Markdown

Несмотря на свое название, commonmark не является ни надмножеством, ни подмножеством других разновидностей уценки.

Скорее, он предлагает стандартную, недвусмысленную спецификацию синтаксиса для исходного «ядра».

Markdown, тем самым эффективно представляя еще одну особенность. Хотя flexmark используется по умолчанию

соответствует стандарту commonmark, его парсер можно настраивать различными способами. Наборы настроек, необходимые для

эмулировать наиболее часто используемые парсеры уценки доступны во flexmark как

Профили ParserEmulation.

Как следует из названия ParserEmulationProfile, только синтаксический анализатор настраивается на

специфический вкус уценки. Применение профиля не добавляет функций, помимо тех, которые доступны в

общее клеймо. Если вы хотите использовать flexmark для полной эмуляции поведения другого процессора уценки,

вам необходимо настроить парсер и настроить расширения flexmark, которые предоставляют дополнительные

функции, доступные в парсере, который вы хотите имитировать.

Переписан парсер списка для лучшего управления эмуляцией других процессоров уценки согласно

Эмуляция процессоров Markdown завершена. Добавление

предустановки процессора для эмуляции определенного поведения обработки уценки этих парсеров находятся на

короткий список дел.

Некоторые семейства эмуляции лучше справляются с эмуляцией своей цели, чем другие. Большая часть

усилия были направлены на имитацию того, как эти процессоры анализируют стандартный Markdown и выводят список

связанный синтаксический анализ конкретно. Для процессоров, которые расширяют исходный Markdown, вам необходимо добавить

те расширения, которые уже реализованы в flexmark-java для компоновщика парсера/рендерера

параметры.

Расширения будут изменены и будут включать в себя собственные предустановки для эмуляции конкретного процессора, если

в этом процессоре реализовано эквивалентное расширение.

Если вы обнаружите несоответствие, пожалуйста, откройте проблему, чтобы ее можно было устранить.

Реализованы основные семейства процессоров, а также некоторые члены семейства:

профили для инкапсуляции деталей конфигурации для вариантов внутри

семья была добавлена ​​в 0.11.0:

История и мотивация

flexmark-java — это ответвление проекта commonmark-java, модифицированное для создания AST, который

отражает все элементы исходного источника, полное отслеживание позиции исходного кода для всех элементов

в AST и более простой генерации JetBrains Open API PsiTree.

API был изменен, чтобы обеспечить более детальный контроль над процессом синтаксического анализа, и оптимизирован для

парсинг при большом количестве установленных расширений. Парсер и расширения поставляются со многими

настройка параметров поведения парсера и вариантов рендеринга HTML. Конечная цель – получить

парсер и рендерер смогут имитировать другие парсеры с большой степенью точности.

Мотивацией для этого послужила необходимость замены парсера pegdown в плагине Markdown Navigator.

pegdown имеет отличный набор функций, но его скорость в целом далека от идеальной, и для

патологический ввод либо зависает, либо практически зависает во время синтаксического анализа.

commonmark-java имеет отличную архитектуру синтаксического анализа, которую легко понять и расширить.

Цель заключалась в том, чтобы гарантировать, что добавление отслеживания положения источника в AST не повлияет на простоту

анализа и генерации AST больше, чем это абсолютно необходимо.

Причинами выбора commonmark-java в качестве парсера являются: скорость, простота понимания, простота

расширение и скорость. Теперь, когда я переработал ядро ​​и добавил несколько расширений, я чрезвычайно

доволен своим выбором.

Другая цель заключалась в том, чтобы улучшить способность расширений изменять поведение парсера, чтобы любые

диалект уценки может быть реализован через механизм расширения. Расширяемые возможности

Был добавлен API, позволяющий настраивать все параметры в одном месте. Использование парсера, рендерера и расширений

эти параметры конфигурации, включая отключение некоторых анализаторов основных блоков.

Эта работа находится в стадии разработки и включает множество изменений API. Никаких попыток сохранить обратный API не предпринимается.

совместимости с исходным проектом и до тех пор, пока набор функций не будет в основном полным, даже не для

более ранние версии этого проекта.

Сравнение функций

(1)

flexmark-java патологический ввод 100 000 [анализ за 68 мс, 100 000] за 57 мс, 100 000

вложенный [ ] анализ за 55 мс

(2)

Commonmark-Java патологический ввод 100 000 [анализ за 30 мс, 100 000] за 30 мс, 100 000

вложенный [ ] анализ за 43 мс

(3)

привязка патологического ввода 17 [ анализируется за 650 мс, 18 [ за 1300 мс

Прогресс

Я очень доволен решением перейти на синтаксический анализатор на основе commonmark-java для собственного использования.

проекты. Несмотря на то, что мне пришлось сделать серьезную операцию на его внутренностях, чтобы получить полную исходную позицию.

отслеживания и AST, который соответствует исходным элементам, работать с ним одно удовольствие, и теперь он

с удовольствием продлю. Если вам не нужен элемент уровня исходного кода AST или остальная часть flexmark-java

добавлен, а CommonMark — ваш целевой анализатор уценки, тогда я рекомендую вам использовать

commonmark-java, поскольку это отличный выбор для ваших нужд, а его производительность не

страдать от накладных расходов на функции, которые вы не будете использовать.

Тесты

Последняя версия, 28 января 2017 г. flexmark-java 0.13.1, intellij-markdown из CE EAP 2017, commonmark-java

0.8.0:

Соотношения выше:

Поскольку эти два файла представляют собой патологические входные данные для привязки, я больше не запускаю их как

часть теста для предотвращения искажения результатов. Результаты здесь для потомков.

Соотношения выше:

Содействие

Запросы на включение, проблемы и комментарии приветствуются? Для запросов на извлечение:

Лицензия

Авторские права (c) 2015–2016 Atlassian и другие.

Copyright (c) 2016-2023, Владимир Шнайдер,

Лицензия BSD (2 пункта), см. файл LICENSE.txt.

пример:

Мицуба Рендерер 3

Документация	Обучающие видео	Линукс	MacOS	Окна	ПиПИ

️

Предупреждение

️

В настоящее время в мире ведется большой объем недокументированной и нестабильной работы.

master ветка. Мы настоятельно рекомендуем вам воспользоваться нашим

последний выпуск

до дальнейшего уведомления.

Если вы уже хотите опробовать предстоящие изменения, ознакомьтесь с

это руководство по портированию.

Он должен охватывать большинство новых функций и предстоящих кардинальных изменений.

Введение

Mitsuba 3 — это исследовательская система рендеринга прямого и обратного света.

транспортное моделирование, разработанное в EPFL в Швейцарии.

Он состоит из базовой библиотеки и набора плагинов, реализующих функциональность.

начиная от материалов и источников света и заканчивая полными алгоритмами рендеринга.

Mitsuba 3 является перенацеливаемой : это означает, что базовые реализации и

Структуры данных могут трансформироваться для выполнения различных задач. Для

Например, один и тот же код может моделировать скалярный (классический по одному лучу) транспорт RGB

или дифференциальный спектральный транспорт на графическом процессоре. Все это основано на

Dr.Jit — специализированный JIT -компилятор, разработанный специально для этого проекта.

Основные характеристики

• Кроссплатформенность : Mitsuba 3 была протестирована на Linux ( x86_64 ), macOS.

  ( aarch64 , x8664 ) и Windows ( x8664 ).

• Высокая производительность : базовый компилятор Dr.Jit объединяет код рендеринга.

  в ядра, которые достигают высочайшей производительности, используя

  серверная часть LLVM, ориентированная на ЦП, и серверная часть CUDA/OptiX

  ориентированы на графические процессоры NVIDIA с аппаратным ускорением трассировки лучей.

• Python прежде всего : Mitsuba 3 глубоко интегрирован с Python. Материалы,

  текстуры и даже полные алгоритмы рендеринга могут быть разработаны на Python,

  который система JIT-компилирует (и, при необходимости, дифференцирует) на лету.

  Это позволяет проводить эксперименты, необходимые для исследований в области компьютерной графики и

  другие дисциплины.

• Дифференциация : Mitsuba 3 — это дифференцируемый рендерер, то есть он

  может вычислять производные всей симуляции относительно входных данных

  такие параметры, как поза камеры, геометрия, BSDF, текстуры и объемы. Это

  реализует последние алгоритмы дифференцируемого рендеринга, разработанные в EPFL.

• Спектральный и поляризационный : Mitsuba 3 можно использовать как монохроматический.

  рендерер, рендерер на основе RGB или спектральный рендерер. Каждый вариант может

  при необходимости, при необходимости, учтите эффекты поляризации.

Обучающие видеоролики, документация

Мы записали несколько видеороликов на YouTube, которые дают краткое представление.

Мицуба 3 и Доктор Джит. Помимо этого вы можете найти полные блокноты Juypter.

охватывающий различные приложения, практические руководства и справочную документацию.

на прочтенной документации.

Установка

Мы предоставляем предварительно скомпилированные двоичные колеса через PyPI. Установить Mitsuba таким способом так же просто, как запустить

 pip установить Мицубу

в командной строке. Пакет Python по умолчанию включает тринадцать вариантов:

• scalar_rgb

• scalar_spectral

• scalarspectralpolarized

• llvmadrgb

• llvmadmono

• llvmadmono_polarized

• llvmadspectral

• llvmadspectral_polarized

• cudaadrgb

• cudaadmono

• cudaadmono_polarized

• cudaadspectral

• cudaadspectral_polarized

Первые два выполняют классическое моделирование по одному лучу с использованием RGB

или спектральное представление цвета, тогда как последние два могут использоваться для обратного

рендеринг на CPU или GPU. Чтобы получить доступ к дополнительным вариантам, вам необходимо

скомпилируйте собственную версию Dr.Jit с помощью CMake. Пожалуйста, ознакомьтесь с

документация

для получения подробной информации об этом.

Требования

• Python >= 3.8

• (необязательно) Для вычислений на графическом процессоре: Nvidia driver >= 495.89

• (необязательно) Для векторизованных/параллельных вычислений на ЦП: LLVM >= 11.1

Использование

Вот простой пример «Hello World», который показывает, насколько просто визуализировать

сцена с использованием Mitsuba 3 из Python:

 # Импортируйте библиотеку, используя псевдоним "mi"import mitsuba as mi# Установите вариант renderermi.setvariant('scalarrgb')# Загрузите сценуscene = mi.loaddict(mi.cornellbox())# Отрисуйте сценуimg = mi. render(scene)# Запишите визуализированное изображение в файл EXRmi.Bitmap(img).write('cbox.exr')

Учебные пособия и блокноты с примерами, охватывающие различные приложения, можно найти.

в документации.

О

Этот проект создал Венцель Якоб.

Значительные функции и/или улучшения кода были внесены

Себастьян Шпейерер,

Николя Руссель,

Мерлин Нимье-Дэвид,

Делио Вичини,

Тициан Зельтнер,

Батист Николе,

Мигель Креспо,

Винсент Лерой и

Цзыи Чжан.

При использовании Mitsuba 3 в академических проектах указывайте:

 @software{Mitsuba3,title = {рендерер Mitsuba 3},author = {Венцель Якоб и Себастьян Шпейерер и Николя Руссель и Мерлин Нимьер-Давид и Делио Вичини и Тициан Зельтнер и Батист Николе и Мигель Креспо и Винсент Лерой и Зийи Чжан},note = {https://mitsuba-renderer.org},версия = {3.1.1}, год = 2022}