flexmark javaダウンロード - flexmark javaソースコードのダウンロード

flexmark java

JAVAソースコード

1.0.0

ダウンロード

フレックスマーク-Java

flexmark-java は、ブロックを最初に使用し、Markdown 解析アーキテクチャの後にインラインを使用するCommonMark (仕様 0.28)パーサーの Java 実装です。

その強みは、速度、柔軟性、要素を構成する語彙素の個々の文字に至るまでソース位置の詳細を含むマークダウンソース要素ベースの AST、および拡張性です。

API を使用すると、解析プロセスをきめ細かく制御でき、インストールされている多数の拡張機能を使用した解析に最適化されています。パーサーと拡張機能には、パーサーの動作と HTML レンダリングのバリエーションに関する豊富なオプションが付属しています。最終的な目標は、パーサーとレンダラーが他のパーサーを非常に正確に模倣できるようにすることです。これで、Markdown Processor Emulation の実装が部分的に完了しました。

このプロジェクトの動機は、JetBrains IDE 用の Markdown Navigator プラグインのペグダウンパーサーを置き換える必要性でした。ペグダウンには優れた機能セットがありますが、一般にその速度は理想的とは言えず、異常な入力の場合は解析中にハングするか、実質的にハングします。

バージョン 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次のサンプルに追加します。

 <依存関係>
    <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 オプション = new MutableDataSet();        // コメントを解除してオプションの拡張機能を設定します //options.set(Parser.EXTENSIONS, Arrays.asList(TablesExtension.create(), StrikethroughExtension.create()));        // コメントを解除してソフト ブレークをハード ブレークに変換します //options.set(HtmlRenderer.SOFT_BREAK, "<br />n");        パーサー parser = Parser.builder(options).build();        HtmlRenderer レンダラー = HtmlRenderer.builder(options).build();        // パーサーとレンダラーのインスタンスを再利用できます Node document = parser.parse("This is *Sparta*");        文字列 html = renderer.render(ドキュメント);  // "<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/依存関係」を除外します}

詳細については、次のドキュメントを参照してください。
Wiki ホーム使用例拡張機能の詳細拡張機能の作成

ペグダウン移行ヘルパー

PegdownOptionsAdapterクラスは、pegdown Extensions.*フラグをフレックスマークオプションと拡張機能リストに変換します。 Pegdown Extensions.javaは便宜上含まれており、pegdown 1.6.0 には存在しない新しいオプションです。これらはflexmark-profile-pegdownモジュールにありますが、このリポジトリ (PegdownOptionsAdapter.java、Extensions.java) からソースを取得し、プロジェクトのニーズに合わせて変更した独自のバージョンを作成できます。

拡張フラグを静的なPegdownOptionsAdapter.flexmarkOptions(int)に渡すことも、 PegdownOptionsAdapterインスタンス化し、便利なメソッドを使用して拡張フラグを設定、追加、削除することもできます。 PegdownOptionsAdapter.getFlexmarkOptions()ペグダウン拡張フラグを反映するオプションを使用して、 DataHolderの新しいコピーを毎回返します。

 import com.vladsch.flexmark.html.HtmlRenderer;import com.vladsch.flexmark.parser.Parser;import com.vladsch.flexmark.profile.pegdown.Extensions;import com.vladsch.flexmark.profile.pegdown.PegdownOptionsAdapter;import com .vladsch.flexmark.util.data.DataHolder;パブリックclass PegdownOptions {final private static DataHolder OPTIONS = PegdownOptionsAdapter.flexmarkOptions( Extensions.ALL
    );    静的最終パーサー PARSER = Parser.builder(OPTIONS).build();    静的最終 HtmlRenderer RENDERER = HtmlRenderer.builder(OPTIONS).build();    // PARSER を使用して解析し、RENDERER を使用してペグダウン互換性を使用してレンダリングします。}

デフォルトの flexmark-java ペグダウンエミュレーションでは、空白行で HTML ブロックを中断する、それほど厳密ではない HTML ブロック解析が使用されます。ペグダウンは、HTML ブロック内のすべてのタグが閉じている場合にのみ、空白行の HTML ブロックを中断します。

元のペグダウン HTML ブロックの解析動作に近づけるには、 boolean strictHtml引数を取るメソッドを使用します。

 import com.vladsch.flexmark.html.HtmlRenderer;import com.vladsch.flexmark.parser.Parser;import com.vladsch.flexmark.profile.pegdown.Extensions;import com.vladsch.flexmark.profile.pegdown.PegdownOptionsAdapter;import com .vladsch.flexmark.util.data.DataHolder;パブリックclass PegdownOptions {final private static DataHolder OPTIONS = PegdownOptionsAdapter.flexmarkOptions(true, Extensions.ALL
    );    静的最終パーサー PARSER = Parser.builder(OPTIONS).build();    静的最終 HtmlRenderer RENDERER = HtmlRenderer.builder(OPTIONS).build();    // PARSER を使用して解析し、RENDERER を使用してペグダウン互換性を使用してレンダリングします。}

カスタムリンクリゾルバーを使用したサンプルも利用できます。これには、リンクの URL または属性を変更するためのリンクリゾルバーと、生成されたリンク HTML をオーバーライドする必要がある場合のカスタムノードレンダラーが含まれています。

flexmark-java には、pegdown 1.6.0 で利用可能な拡張機能に加えて、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 \|

リリース、バグ修正、機能強化、サポート

JetBrains IDE の Markdown Navigator プラグインのパーサーとして flexmark-java を使用しています。私はバグを修正したり改善を得るために、最新の未リリースバージョンを使用することが多いです。したがって、プロジェクトの致命的なバグを見つけた場合、またはプロジェクトに影響を及ぼしているfixed for next releaseマークされている Github の問題ページのバグを見つけた場合は、私に知らせてください。すぐに新しいリリースを作成して対処できるかもしれません。あなたの問題。そうしないと、すでに修正されたものからは誰も影響を受けないと考えて、バグ修正と機能拡張が蓄積されることになります。

API の拡張ポイントは非常に多くあります

API には、用途に応じた多くの拡張オプションがあります。ソフトスタートとしては、要求された拡張機能の簡単なサンプルが含まれるflexmark-java-samplesモジュールが最適です。次に最適な場所は、追加するものと同様の構文を持つ既存の拡張機能のソースです。

拡張機能が適切な API と一致している場合、タスクは通常、非常に短くて簡単です。拡張機能が意図しない方法で API を使用している場合、または予期されるハウスキーピングプロトコルに従っていない場合は、if/else 条件の処理と 1 つのバグを修正するだけで別のバグが作成されるというネズミの巣との厳しい戦いに遭遇する可能性があります。

一般に、単純な拡張機能を追加するのに数十行以上かかる場合は、やり方が間違っているか、API に拡張ポイントが欠落しているかのどちらかです。実装されているすべての拡張機能を見ると、そのほとんどが API によって指示された定型文以外の数行のコードであることがわかります。それがこのライブラリの目標です。拡張機能を簡単に作成できる拡張可能なコアを提供することです。

より大きな拡張機能はflexmark-ext-tablesとflexmark-ext-spec-exampleで、どちらの内容も約 200 行のコードです。エクステンションのサイズを見積もるためのガイドポストとして使用できます。

拡張機能を追加した私自身の経験から、新しいタイプの拡張機能には、実装をシームレスにするために API を拡張するか、拡張機能が適切な方法で API に負荷をかける前には見えなかったバグを修正することで対処するのが最適な場合があることがわかりました。あなたが意図している拡張機能は、まさにそのようなアプローチを必要とする拡張機能である可能性があります。

答えが見つからない場合は、ためらわずに問題を開いてください

重要なのは、拡張機能や機能を実装したい場合は、ためらわずに問題をオープンしてください。最善の方法についてアドバイスいたします。無駄な労力を費やす前に、拡張機能のニーズに対応できるように API を改善できるため、時間を大幅に節約できる可能性があります。

私がこのプロジェクトの主任料理人でありボトル洗浄者であり、ヴァルカンの精神を融合するスキルがまったくないことを理解していただきたいのですが。あなたの心が読めないので、何を実装したいのか説明してください。皆さんの積極的な努力がなければ、私が知っていることを皆さんに伝えることはできないので、ソースコードとドキュメントに関するバックグラウンドでの偵察作業を行ってください。

コンサルティングが可能です

商用アプリケーションをお持ちで、自分で拡張機能を作成したくない場合、または拡張機能の実装と flexmark-java の統合にかかる時間と労力を削減したい場合は、お気軽にご連絡ください。コンサルティング/契約ベースで対応させていただきます。

マークダウンプロセッサエミュレーション

その名前にもかかわらず、commonmark は他のマークダウンフレーバーのスーパーセットでもサブセットでもありません。むしろ、元の「コア」Markdown の標準的で明確な構文仕様を提案し、効果的にさらに別のフレーバーを導入します。 flexmark はデフォルトで commonmark に準拠していますが、そのパーサーはさまざまな方法で調整できます。最も一般的に使用されるマークダウンパーサーをエミュレートするために必要な調整のセットは、 flexmark でParserEmulationProfilesとして利用できます。

ParserEmulationProfileという名前が示すように、特定のマークダウンフレーバーに合わせて調整されるのはパーサーだけです。プロファイルを適用しても、commonmark で利用可能な機能を超える機能は追加されません。 flexmark を使用して別のマークダウンプロセッサの動作を完全にエミュレートする場合は、パーサーを調整し、エミュレートするパーサーで使用できる追加機能を提供する flexmark 拡張機能を構成する必要があります。

Markdown Processors Emulation に従って他のマークダウンプロセッサのエミュレーションをより適切に制御するためのリストパーサーの書き換えが完了しました。これらのパーサーの特定のマークダウン処理動作をエミュレートするためのプロセッサープリセットの追加は、短いやるべきことリストに含まれています。

一部のエミュレーションファミリは、他のエミュレーションファミリよりもターゲットをより適切にエミュレートします。努力のほとんどは、これらのプロセッサが標準のマークダウンを解析する方法と、特にリスト関連の解析をエミュレートすることに向けられました。オリジナルの Markdown を拡張するプロセッサの場合は、flexmark-java にすでに実装されている拡張機能を Parser/Renderer ビルダーオプションに追加する必要があります。

プロセッサに同等の拡張機能が実装されている場合、拡張機能は特定のプロセッサエミュレーション用の独自のプリセットを含むように変更されます。

矛盾を見つけた場合は、問題を解決できるように問題を開いてください。

主要なプロセッサファミリが実装されており、一部のファミリメンバーも次のとおりです。

ジキル
最新の実装仕様の CommonMark、現在 CommonMark (仕様 0.28)

リーグ/コモンマーク
特定のバージョンの互換性のための CommonMark (仕様 0.27)
特定のバージョンの互換性のための CommonMark (仕様 0.28)
GitHub コメント

マークダウン.pl

Php マークダウンエクストラ
GitHub Docs (古い GitHub マークダウンパーサー)

クラムダウン
固定インデント

マルチマークダウン
ペグダウン

ファミリ内のバリアントの設定詳細をカプセル化するプロファイルが 0.11.0 で追加されました。

CommonMark (ファミリのデフォルト): ParserEmulationProfile.COMMONMARK
FixedIndent (ファミリのデフォルト): ParserEmulationProfile.FIXED_INDENT
GitHub コメント (CommonMark のみ): ParserEmulationProfile.COMMONMARK
古い GitHub ドキュメント: ParserEmulationProfile.GITHUB_DOC
Kramdown (ファミリのデフォルト): ParserEmulationProfile.KRAMDOWN
Markdown.pl (ファミリーのデフォルト): ParserEmulationProfile.MARKDOWN
MultiMarkdown: ParserEmulationProfile.MULTI_MARKDOWN
ペグダウン、ペグダウン拡張機能を使用するにはflexmark-profile-pegdownでPegdownOptionsAdapterを使用します。
ペグダウン、ペグダウン拡張機能なしParserEmulationProfile.PEGDOWN
ペグダウン拡張機能なしのペグダウン HTML ブロック解析ルールParserEmulationProfile.PEGDOWN_STRICT

歴史と動機

flexmark-javaは commonmark-java プロジェクトのフォークであり、元のソース内のすべての要素を反映する AST、AST 内のすべての要素の完全なソース位置追跡、およびより簡単な JetBrains Open API PsiTree 生成を生成するように修正されています。

API は、解析プロセスをより詳細に制御できるように変更され、インストールされている多数の拡張機能を解析するために最適化されました。パーサーと拡張機能には、パーサーの動作と HTML レンダリングのバリエーションに関する多くの調整オプションが付属しています。最終的な目標は、パーサーとレンダラーが他のパーサーを非常に正確に模倣できるようにすることです。

この動機は、Markdown Navigator プラグインのペグダウンパーサーを置き換える必要性からでした。ペグダウンには優れた機能セットがありますが、一般にその速度は理想的とは言えず、異常な入力の場合は解析中にハングするか、実質的にハングします。

commonmark-java は、理解しやすく拡張しやすい優れた解析アーキテクチャを備えています。目標は、AST にソース位置追跡を追加しても、AST の解析と生成の容易さが必要以上に変化しないようにすることでした。

commonmark-java をパーサーとして選択する理由は、速度、理解の容易さ、拡張の容易さ、および速度です。コアを作り直し、いくつかの拡張機能を追加したので、自分の選択に非常に満足しています。

もう 1 つの目標は、パーサーの動作を変更する拡張機能の機能を向上させ、拡張メカニズムを通じてマークダウンのあらゆる方言を実装できるようにすることでした。拡張可能なオプション API が追加され、すべてのオプションを 1 か所で設定できるようになりました。パーサー、レンダラー、および拡張機能は、一部のコアブロックパーサーの無効化などの構成にこれらのオプションを使用します。

これは進行中の作業であり、API に多くの変更が加えられています。元のプロジェクトとの API の下位互換性を維持する試みは行われず、機能セットがほぼ完成するまでは、このプロジェクトの以前のバージョンとの互換性も維持されません。

機能の比較

特徴	フレックスマーク-Java	コモンマーク-Java	ペグダウン
相対的な解析時間 (短いほど良い)	1x (1)	0.6x ～ 0.7x (2)	平均 25 倍、病理学的入力の場合は 20,000 倍から ∞ (3)
AST 内のすべてのソース要素
ソース位置を含む AST 要素			多少の間違いや特異性はありますが
ASTは簡単に操作できる	AST 後処理は拡張メカニズムです	AST 後処理は拡張メカニズムです	オプションではありません。ノードの親情報はありません。子は List<> です。
AST 要素には、すべてのパートの詳細なソース位置が含まれています			ノードの開始/終了のみ
コア解析機能を無効にすることができます
拡張 API を介して実装されたコアパーサー		特定のブロックパーサーとノードクラスの`instanceOf`テスト	コアはいくつかの拡張ポイントを公開します
パーサー実装の理解と変更が容易			複雑な相互作用を備えた 1 つの PEG パーサー (3)
ブロック要素の解析は互いに独立しています			すべてを 1 つの 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)

ペグダウンの病理学的入力は 650 ミリ秒で 17 [解析、1300 ミリ秒で 18 [

進捗

パーサーオプション、タスク項目としてマークされた項目が実装され、残りは完了します。

手動のルーズリスト
番号付きリストは常に 1 から始まります。
リスト項目のインデントを修正しました。項目は少なくとも 4 つのスペースでインデントする必要があります
緩和されたリスト開始オプション。前に空行がない場合でもリストを開始できます。
ジキル前付
Jekyll タグ要素。 {% include file %} 、Include Markdown および HTML ファイルコンテンツをサポート
GitBook リンクの URL エンコード。適用できない
HTML コメントノード: ブロックおよびインライン
複数行の画像 URL
仕様例要素
インラインHTML: すべて、コメント以外、コメント
HTML ブロック: すべて、コメント以外、コメント
略語
脚注
定義
目次
取り消し線
タスクリスト
Atxヘッダースペースがありません
ヘッダーのインデントなし
ハードラップ (SOFT_BREAK オプションを"<br />"に変更することで実現)
緩和された人事ルールのオプション
ウィキリンク
フェンスで囲まれたコードブロック
自動 ID 生成によるヘッダーのアンカーリンク
テーブル拡張のために実装されるテーブルスパンオプション
GitHub およびクレオール構文を使用した Wiki リンク
GitHub 絵文字 URL オプションを使用した絵文字ショートカット
引用
スマート
タイポグラフィー
GitHub 拡張機能
GitHub の構文
出版
抑制する
プロセッサ拡張
コモンマーク構文の抑制

私は自分のプロジェクトのために commonmark-java ベースのパーサーに切り替えるという決定に非常に満足しています。完全なソース位置追跡とソース要素と一致する AST を得るために内部に大規模な手術を行う必要がありましたが、これを扱うのは楽しいし、今では拡張するのが楽しいです。ソースレベルの要素 AST や flexmark-java が追加した残りの部分が必要なく、CommonMark がターゲットのマークダウンパーサーである場合は、commonmark-java を使用することをお勧めします。これはニーズに最適な選択肢であり、パフォーマンスが低下することはありません。使用しない機能のオーバーヘッドを考慮します。

ベンチマーク

最新、2017 年 1 月 28 日の flexmark-java 0.13.1、CE EAP 2017 の intellij-markdown、commonmark-java 0.8.0:

ファイル	コモンマーク-Java	フレックスマーク-Java	インテリジマークダウン	ペグダウン
README-遅い	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ミリ秒

上記の比率:

ファイル	コモンマーク-Java	フレックスマーク-Java	インテリジマークダウン	ペグダウン
README-遅い	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	3月17日
包む	1.00	1.21	4.37	22.71
全体	1.00	1.41	17.47	40.11

ファイル	コモンマーク-Java	フレックスマーク-Java	インテリジマークダウン	ペグダウン
README-遅い	0.52	1.00	2.50	19.07
バージョン	0.52	1.00	2.85	12月30日
共通マークスペック	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

これら 2 つのファイルはペグダウンの病理学的入力を表すため、結果の偏りを防ぐためにベンチマークの一部としてこれらのファイルを実行することはなくなりました。結果は後世のためにここにあります。

ファイル	コモンマーク-Java	フレックスマーク-Java	インテリジマークダウン	ペグダウン
ハングペグダウン	0.082ミリ秒	0.326ミリ秒	0.342ミリ秒	659.138ミリ秒
ハングペグダウン2	0.048ミリ秒	0.235ミリ秒	0.198ミリ秒	1312.944ミリ秒

上記の比率:

ファイル	コモンマーク-Java	フレックスマーク-Java	インテリジマークダウン	ペグダウン
ハングペグダウン	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

ファイル	コモンマーク-Java	フレックスマーク-Java	インテリジマークダウン	ペグダウン
ハングペグダウン	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 行のファイルです。
spec.txt commonmark-java プロジェクト内の commonmark スペックマークダウンファイル
Hang-pegdown.md は、17 文字[[[[[[[[[[[[[[[[[
Hang-pegdown2.md 18 文字の 1 行を含むファイル[[[[[[[[[[[[[[[[[[これにより、ペグダウンは超指数関数的な解析時間になります。
Wrap.md は、ラップオンタイピングのパフォーマンスをテストするために使用していたファイルですが、ペグダウンによるファイルの解析に 0.1 秒かかる場合、ラップオンタイピングコードとは何の関係もないことがわかりました。プラグインでは、構文ハイライトパス、psi ツリー構築パス、外部アノテーターなどの解析が複数回行われる場合があります。
markdown_example.md は、500kB 以上のテキストを含む 10,000 行以上のファイルです。