flexmark java下載 - flexmark java原始碼下載

flexmark java

JAVA源碼

1.0.0

下載

Flexmark-java

flexmark-java是CommonMark（規範 0.28）解析器的 Java 實現，使用區塊優先、內聯後 Markdown 解析架構。

它的優點是速度、靈活性、基於 Markdown 來源元素的 AST，其中來源位置的詳細資訊可以細化到構成元素的詞位的各個字元以及可擴展性。

該 API 允許對解析過程進行精細控制，並針對解析大量已安裝的擴充功能進行了最佳化。解析器和擴充功能為解析器行為和 HTML 渲染變更提供了大量選項。最終目標是讓解析器和渲染器能夠非常精確地模仿其他解析器。透過 Markdown 處理器模擬的實現，現在已部分完成

這個專案的動機是需要取代 JetBrains IDE 的 Markdown Navigator 外掛程式中的 pegdown 解析器。 pegdown 有一個很棒的功能集，但它的速度總體上不太理想，並且對於病態輸入，在解析過程中要么掛起，要么幾乎掛起。

由於實作類別的重新組織、重新命名、清理和最佳化，版本 0.60.0發生了重大變化。更改的詳細資訊請參閱 Version-0.60.0-Changes。

要求

適用於版本 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新增為依賴項，其中包括以下範例的核心和所有模組：

 <依賴關係>
    <groupId>com.vladsch.flexmark</groupId>
    <artifactId>flexmark-all</artifactId>
    <版本>0.64.8</版本>
</依賴>

來源：BasicSample.java

包 com.vladsch.flexmark.samples;導入 com.vladsch.flexmark.util.ast.Node;導入 com.vladsch.flexmark.html.HtmlRenderer;導入 com.vladsch.flexmark.parser.Parser;導入 com.vladsch.flexmark .util.data.MutableDataSet;public class BasicSample { public static void main(String[] args) { MutableDataSet options = new MutableDataSet(); }        // 取消註解以設定可選擴充 //options.set(Parser.EXTENSIONS, Arrays.asList(TablesExtension.create(), StrikethroughExtension.create()));        // 取消註解以將軟中斷轉換為硬中斷 //options.set(HtmlRenderer.SOFT_BREAK, "<br />n");        Parser parser = Parser.builder(options).build();        HtmlRenderer 渲染器 = HtmlRenderer.builder(options).build();        // 您可以重複使用解析器和渲染器實例 Node document = parser.parse("This is *Sparta*");        String html = renderer.render(document);  // "<p>這是<em>斯巴達</em></p>n" System.out.println(html);
    }
}

透過 Gradle 構建

實施 'com.vladsch.flexmark:flexmark-all:0.64.8'

使用 Android Studio 進行建置

由於重複文件而導致的附加設定：

包裝選項{
    排除“META-INF/LICENSE-LGPL-2.1.txt”
    排除“META-INF/LICENSE-LGPL-3.txt”
    排除“META-INF/LICENSE-W3C-TEST”
    排除“META-INF/DEPENDENCIES”}

更多資訊可以在文件中找到：
Wiki Home 使用範例擴充詳細資訊撰寫擴充

Pegdown 遷移助手

PegdownOptionsAdapter類別將 pegdown Extensions.*標誌轉換為 Flexmark 選項和擴充清單。包含 Pegdown Extensions.java是為了方便和 pegdown 1.6.0 中未找到的新選項。這些位於flexmark-profile-pegdown模組中，但您可以從此儲存庫中取得原始程式碼：PegdownOptionsAdapter.java、Extensions.java 並製作您自己的版本，並根據您的專案需求進行修改。

您可以將擴充標誌傳遞給靜態PegdownOptionsAdapter.flexmarkOptions(int) ，也可以實例化PegdownOptionsAdapter並使用便捷方法來設定、新增和刪除擴充標誌。 PegdownOptionsAdapter.getFlexmarkOptions()每次都會傳回DataHolder的新副本，其中的選項反映 pegdown 擴充標誌。

導入 com.vladsch.flexmark.html.HtmlRenderer;導入 com.vladsch.flexmark.parser.Parser;導入 com.vladsch.flexmark.profile.pegdown.Extensions;導入 com.vladsch.flexmark.profile.pegdown.PegdownOptionsAdapter; .vladsch.flexmark.util.data.DataHolder;公共類別PegdownOptions { 最終私有靜態DataHolder OPTIONS = PegdownOptionsAdapter.flexmarkOptions( Extensions.ALL
    ）；    靜態最終解析器 PARSER = Parser.builder(OPTIONS).build();    靜態最終 HtmlRenderer RENDERER = HtmlRenderer.builder(OPTIONS).build();    // 使用 PARSER 進行解析並使用 RENDERER 進行渲染，並具有 pegdown 相容性}

預設的 flexmark-java pegdown 模擬使用不太嚴格的 HTML 區塊解析，它會中斷空行上的 HTML 區塊。如果 HTML 區塊中的所有標記都已關閉，則 Pegdown 僅會在空白行中斷 HTML 區塊。

為了更接近原始的 pegdown HTML 區塊解析行為，請使用採用boolean strictHtml參數的方法：

導入 com.vladsch.flexmark.html.HtmlRenderer;導入 com.vladsch.flexmark.parser.Parser;導入 com.vladsch.flexmark.profile.pegdown.Extensions;導入 com.vladsch.flexmark.profile.pegdown.PegdownOptionsAdapter; .vladsch.flexmark.util.data.DataHolder;公共類別PegdownOptions { 最終私有靜態DataHolder OPTIONS = PegdownOptionsAdapter.flexmarkOptions(true, Extensions.ALL
    ）；    靜態最終解析器 PARSER = Parser.builder(OPTIONS).build();    靜態最終 HtmlRenderer RENDERER = HtmlRenderer.builder(OPTIONS).build();    // 使用 PARSER 進行解析並使用 RENDERER 進行渲染，並具有 pegdown 相容性}

還提供了帶有自訂連結解析器的範例，其中包括用於更改 URL 或連結屬性的連結解析器以及自訂節點渲染器（如果您需要覆蓋生成的連結 HTML）。

除了 pegdown 1.6.0 中提供的擴充功能之外，flexmark-java 還比 pegdown 更多的擴充和設定選項。透過 PegdownOptionsAdapter 提供的可用擴展

輸入	輸出
day\|time\|spent :---\|:---:\|--: nov. 2. tue\|10:00\|4h 40m nov. 3. thu\|11:00\|4h nov. 7. mon\|10:20\|4h 20m total:\|\| 13h	\| day \| time \| spent \| \|:------------\|:-----:\|--------:\| \| nov. 2. tue \| 10:00 \| 4h 40m \| \| nov. 3. thu \| 11:00 \| 4h \| \| nov. 7. mon \| 10:20 \| 4h 20m \| \| total: \|\| 13h \|

版本、錯誤修復、增強和支持

我使用 flexmark-java 作為 JetBrains IDE 的 Markdown Navigator 插件的解析器。我傾向於使用最新的、未發布的版本來修復錯誤或獲得改進。因此，如果您發現一個對您的項目造成阻礙的錯誤，或者在 github 問題頁面中看到一個標記fixed for next release錯誤正在影響您的項目，那麼請告訴我，我也許能夠及時發布新版本來解決你的問題。否則，我會讓錯誤修復和增強功能不斷積累，認為沒有人會受到已修復內容的影響。

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 風格的超集也不是子集。相反，它為原始「核心」Markdown 提出了一個標準的、明確的語法規範，從而有效地引入了另一種風格。雖然 Flexmark 預設情況下相容於 CommonMark，但它的解析器可以透過各種方式進行調整。模擬最常用的 Markdown 解析器所需的調整集可在 Flexmark 中作為ParserEmulationProfiles取得。

正如名稱ParserEmulationProfile所暗示的那樣，只有解析器會根據特定的 Markdown 風格進行調整。應用程式設定檔不會新增超出 commonmark 中可用功能的功能。如果您想使用 Flexmark 完全模擬另一個 Markdown 處理器的行為，則必須調整解析器並配置 Flexmark 擴展，以提供您想要模擬的解析器中可用的附加功能。

根據 Markdown 處理器仿真，重寫列表解析器以更好地控制其他 Markdown 處理器的仿真已完成。新增處理器預設來模擬這些解析器的特定降價處理行為是一個簡短的待辦事項清單。

有些模擬家族在模擬目標方面比其他家族做得更好。大部分工作都是針對模擬這些處理器如何解析標準 Markdown 並具體列出相關解析。對於擴充原始 Markdown 的處理器，您需要將那些已在 flexmark-java 中實作的擴充功能新增到解析器/渲染器建構器選項中。

如果該處理器實現了等效的擴展，則擴展將被修改為包括其自己針對特定處理器模擬的預設。

如果您發現差異，請提出問題以便解決。

主要處理器系列已實現，一些系列成員還：

傑基爾
CommonMark 用於最新實施的規範，目前為 CommonMark（規範 0.28）

聯盟/CommonMark
CommonMark（規範 0.27）用於特定版本相容性
CommonMark（規範 0.28）用於特定版本相容性
GitHub 評論

Markdown.pl

PHP Markdown 額外
GitHub Docs（舊的 GitHub markdown 解析器）

克拉姆當
固定縮排

多重降價
釘住

0.11.0 中新增了用於封裝系列內變體的配置詳細資訊的設定檔：

CommonMark（系列預設）： ParserEmulationProfile.COMMONMARK
固定縮排（系列預設值）： ParserEmulationProfile.FIXED_INDENT
GitHub 評論（僅 CommonMark）： ParserEmulationProfile.COMMONMARK
舊 GitHub 文件： ParserEmulationProfile.GITHUB_DOC
Kramdown（系列預設值）： ParserEmulationProfile.KRAMDOWN
Markdown.pl（系列預設）： ParserEmulationProfile.MARKDOWN
MultiMarkdown： ParserEmulationProfile.MULTI_MARKDOWN
Pegdown，帶有 pegdown 擴展，在flexmark-profile-pegdown使用PegdownOptionsAdapter
Pegdown，不帶 pegdown 擴充ParserEmulationProfile.PEGDOWN
Pegdown HTML 區塊解析規則，不帶 pegdown 擴充ParserEmulationProfile.PEGDOWN_STRICT

歷史和動機

flexmark-java是 commonmark-java 專案的一個分支，經過修改可產生反映原始來源中所有元素的 AST、對 AST 中所有元素的完整來源位置追蹤以及更輕鬆的 JetBrains Open API PsiTree 產生。

API 進行了更改，以允許對解析過程進行更精細的控制，並針對大量已安裝的擴充功能進行解析進行了最佳化。解析器和擴充功能附帶了許多針對解析器行為和 HTML 渲染變化的調整選項。最終目標是讓解析器和渲染器能夠非常精確地模仿其他解析器。

這樣做的動機是需要取代 Markdown Navigator 外掛程式中的 pegdown 解析器。 pegdown 有一個很棒的功能集，但它的速度總體上不太理想，並且對於病態輸入，在解析過程中要么掛起，要么幾乎掛起。

commonmark-java擁有優秀的解析架構，易於理解與擴展。目標是確保在 AST 中添加來源位置追蹤不會超過絕對必要地改變解析和生成 AST 的簡易性。

選擇commonmark-java作為解析器的原因是：速度、易於理解、易於擴展和速度。現在我已經重新設計了核心並添加了一些擴展，我對我的選擇非常滿意。

另一個目標是提高擴展修改解析器行為的能力，以便任何 Markdown 方言都可以透過擴展機制實現。新增了可擴展選項 API，以允許在一個位置設定所有選項。解析器、渲染器和擴充功能使用這些選項進行配置，包括停用一些核心區塊解析器。

這是一項正在進行的工作，有許多 API 變更。在功能集基本完成之前，不會嘗試保持對原始專案的向後 API 相容性，甚至不會對該專案的早期版本保持向後相容性。

特性比較

特徵	Flexmark-java	commonmark-java	掛鉤
相對解析時間（越少越好）	1x（1）	0.6x 至 0.7x (2)	25 倍平均值，20,000 倍至 ∞ 病理輸入 (3)
AST 中的所有來源元素
具有源位置的 AST 元素			有一些錯誤和特質
AST 很容易操縱	AST後處理是一種擴展機制	AST後處理是一種擴展機制	不是一個選擇。沒有節點的父節點訊息，子節點為List<>。
AST 元素具有所有部分的詳細來源位置			僅節點開始/結束
可以停用核心解析功能
透過擴展 API 實現的核心解析器		特定區塊解析器和節點類別的`instanceOf`測試	核心暴露了很少的擴展點
易於理解和修改解析器實現			一個具有複雜交互作用的 PEG 解析器 (3)
塊元素的解析是相互獨立的			一切盡在一個 PEG 語法中
跨解析器、渲染器和所有擴充的統一配置		擴展列表之外沒有任何內容	核心的`int`位標誌，擴充沒有
解析效能針對擴充使用進行了最佳化		解析核心效能，擴充盡其所能	性能不是一個特徵
功能豐富，有許多開箱即用的配置選項和擴展		擴展有限，沒有選項
處理器的依賴性定義以確保正確的處理順序		由擴充列表排序指定的順序，容易出錯	不適用，核心定義了新增擴充處理的位置

(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)

pegdown 病理輸入 17 [在 650 毫秒內解析，18 [在 1300 毫秒內解析

進步

解析器選項，標記為任務項目的項目將被實現，其餘部分已完成：

手動鬆散列表
編號清單始終以 1 開頭。
修復清單項目縮排，項目必須縮排至少 4 個空格
寬鬆的清單開始選項，允許清單在前面沒有空白行時開始。
傑基爾前線問題
Jekyll 標籤元素，支援{% include file %} ，包含 Markdown 和 HTML 文件內容
GitBook 連結 URL 編碼。不適用
HTML 註解節點：區塊和內聯
多行圖像 URL
規格範例元素
內嵌 HTML：全部、非註解、註釋
HTML 區塊：全部、非註解、註釋
縮寫
註腳
定義
目錄
刪除線
任務清單
無 Atx 接頭空間
沒有標題縮排
硬包裹（透過將 SOFT_BREAK 選項更改為"<br />"來實現）
寬鬆的人力資源規則選項
維基連結
圍欄代碼區塊
具有自動 ID 生成功能的標頭錨鏈接
表跨度選項用於表擴展
帶有 GitHub 和 Creole 語法的 Wiki 鏈接
使用 GitHub 表情符號 URL 選項的表情符號捷徑
引號
聰明人
排版
GitHub 擴充
GitHub 語法
出版
壓制
處理器擴充
Commonmark 語法抑制

我很高興決定為我自己的專案切換到基於 commonmark-java 的解析器。儘管我必須對其內部進行大手術才能獲得完整的源位置追蹤和匹配源元素的 AST，但使用它很愉快，現在擴展也很愉快。如果您不需要源級元素AST 或flexmark-java 添加的其餘內容，並且CommonMark 是您的目標markdown 解析器，那麼我鼓勵您使用commonmark-java，因為它是滿足您需求的絕佳選擇，並且其性能不會受到影響用於您不會使用的功能的開銷。

基準測試

最新，2017 年 1 月 28 日 flexmark-java 0.13.1，來自 CE EAP 2017 的 intellij-markdown，commonmark-java 0.8.0：

文件	commonmark-java	Flexmark-java	intellij-markdown	掛鉤
自述文件慢	0.420毫秒	0.812毫秒	2.027毫秒	15.483毫秒
版本	0.743毫秒	1.425毫秒	4.057毫秒	42.936毫秒
通用標記規格	31.025毫秒	44.465毫秒	600.654毫秒	575.131毫秒
降價範例	8.490毫秒	10.502毫秒	223.593毫秒	983.640毫秒
規格	4.719毫秒	6.249毫秒	35.883毫秒	307.176毫秒
桌子	0.229毫秒	0.623毫秒	0.800毫秒	3.642毫秒
表格格式	1.385毫秒	2.881毫秒	4.150毫秒	23.592毫秒
裹	3.804毫秒	4.589毫秒	16.609毫秒	86.383毫秒

上述比例：

文件	commonmark-java	Flexmark-java	intellij-markdown	掛鉤
自述文件慢	1.00	1.93	4.83	36.88
版本	1.00	1.92	5.46	57.78
通用標記規範	1.00	1.43	19.36	18.54
降價範例	1.00	1.24	26.34	115.86
規格	1.00	1.32	7.60	65.09
桌子	1.00	2.72	3.49	15.90
表格格式	1.00	2.08	3.00	17.03
裹	1.00	1.21	4.37	22.71
全面的	1.00	1.41	17.47	40.11

文件	commonmark-java	Flexmark-java	intellij-markdown	掛鉤
自述文件慢	0.52	1.00	2.50	19.07
版本	0.52	1.00	2.85	30.12
通用標記規範	0.70	1.00	13.51	12.93
降價範例	0.81	1.00	21.29	93.66
規格	0.76	1.00	5.74	49.15
桌子	0.37	1.00	1.28	5.85
表格格式	0.48	1.00	1.44	8.19
裹	0.83	1.00	3.62	18.83
全面的	0.71	1.00	12.41	28.48

因為這兩個檔案代表了 pegdown 的病態輸入，所以我不再將它們作為基準測試的一部分來運行，以防止結果出現偏差。結果供後代參考。

文件	commonmark-java	Flexmark-java	intellij-markdown	掛鉤
懸掛掛鉤	0.082毫秒	0.326毫秒	0.342毫秒	659.138毫秒
懸掛掛鉤2	0.048毫秒	0.235毫秒	0.198毫秒	1312.944毫秒

上述比例：

文件	commonmark-java	Flexmark-java	intellij-markdown	掛鉤
懸掛掛鉤	1.00	3.98	4.17	8048.38
懸掛掛鉤2	1.00	4.86	4.10	27207.32
全面的	1.00	4.30	4.15	15151.91

文件	commonmark-java	Flexmark-java	intellij-markdown	掛鉤
懸掛掛鉤	0.25	1.00	1.05	2024.27
懸掛掛鉤2	0.21	1.00	0.84	5594.73
全面的	0.23	1.00	0.96	3519.73

VERSION.md 是我用於 Markdown Navigator 的版本日誌文件
commonMarkSpec.md 是 intellij-markdown 測試套件中用於效能評估的 33k 行檔案。
commonmark-java 專案中的 spec.txt commonmark 規格 markdown 文件
hang-pegdown.md 是一個包含單行 17 個字元的檔案[[[[[[[[[[[[[[[[[這會導致 pegdown 進入超指數解析時間。
hang-pegdown2.md 一個包含單行 18 個字元的檔案[[[[[[[[[[[[[[[[[[這會導致 pegdown 進入超指數解析時間。
wrap.md 是我用來測試打字換行效能的文件，結果發現當 pegdown 花費 0.1 秒來解析文件時，它與打字程式碼換行無關。在插件中，解析可能會發生多次：語法螢光筆傳遞、psi 樹建構傳遞、外部註釋器。
markdown_example.md 一個包含 10,000 多行、包含 500kB 以上文字的檔案。