MarkdownSharpのクラス仕様

doxygenを使用してドキュメントの作成を行ったので、コレをもとにMarkdownSharpの機能を確認します。

ドキュメントは、以下のリンクより参照できます。
MarkdownSharpクラス仕様

クラス構成

前回確認したとおり、実質的にMarkdownSharpは、MarkdownクラスとMarkdownOptionsクラスの2つで構成されています。

Markdownクラス

メソッド

まずメソッド一覧を確認します。

• Markdown ()
• Markdown (bool loadOptionsFromConfigFile)
• Markdown (MarkdownOptions options)
• string Transform (string text)

コンストラクタが3つと、実際の変換関数が1つの計4つしかありません。
非常にシンプルな構成ですね。
各メソッドの内容は、以下のとおりです。

Markdown()

デフォルトコンストラクタです
Markdownクラスのインスタンスをデフォルトのオプション構成で生成します。

Markdown (bool loadOptionsFromConfigFile)

Markdownクラスのインスタンスを、設定ファイルを元に生成することができます。
設定ファイルからの読み込みは、引数をtrueにしたときのみ有効になるので、new Markdown(false)は、new Markdown()と等価です。

設定はappSettings(app.config)に、以下のキーで登録しておきます。
各パラメータの意味は、後述のプロパティを参照してください。

Markdown.StrictBoldItalic           (true/false) 
Markdown.EmptyElementSuffix         (">" or " />" を、ダブルクォーテーション無しで記載) 
Markdown.LinkEmails                 (true/false) 
Markdown.AutoNewLines               (true/false) 
Markdown.AutoHyperlink              (true/false) 
Markdown.EncodeProblemUrlCharacters (true/false)

Markdown (MarkdownOptions options)

MarkdownOptionsオブジェクトで定義したオプションで、Markdownクラスのインスタンスを生成します。

string Transform (string text)

実際にMarkdown形式のテキストをhtmlに変換する処理です。
Markdown形式の構文は、wikipediaに記載されています。

呼び元側で行われるエスケープ処理など、他のサブルーチンが呼び順は重要です。
aタグとimgタグに含まれる、任意の”*”や”_”はエンコードされるので、リンクと画像の置換はEscapeSpecialChars()の前に発生する必要があります。

プロパティ

プロパティは、7つあります。
その内、最初の6つはコンストラクタで指定可能な情報です。

string EmptyElementSuffix         [get, set]
bool   LinkEmails                 [get, set]
bool   StrictBoldItalic           [get, set]
bool   AutoNewLines               [get, set]
bool   AutoHyperlink              [get, set]
bool   EncodeProblemUrlCharacters [get, set]
string Version                    [get]

string EmptyElementSuffix

空タグの終了文字を指定します。
一般的に、HTMLを出力する場合は、”>”で、XHTMLの場合は ” />”を指定します。

空タグと言うのは、brやhrのように、開きと閉じがペアになってなっておらず、単独で意味をなすタグのことです。xhtmlの場合はxml文法に準拠する必要があるので”<br>”ではなく”<br />”と書く必要があるのですが、ここでどちらの出力を行うかを指定できます。

デフォルト値は” />”です。

bool LinkEmails

注意：falseにするとは通常のmarkdown仕様とは異なる振る舞いとなり、デフォルトはtrueです。

bool StrictBoldItalic

trueにすると、ボールドとイタリックの変換に対して、どちらかの側の非単語の文字を必要とします。

例えばboldの場合、本プロパティをfalseにすると…

  マッチングルール: (\*\*|__) (?=\S) (.+?[*_]*) (?<=\S) \1
  置換のかけ方    : <strong>$2</strong>

  マッチングルール: ([\W_]|^) (\*\*|__) (?=\S) ([^\r]*?\S[\*_]*) \2 ([\W_]|$)
  置換のかけ方    : $1<strong>$3</strong>$4

注意：trueにするとは通常のmarkdown仕様とは異なる振る舞いとなり、デフォルトはfalseです。

bool AutoNewLines

trueにすると、テキスト上に改行文字がある場合、出力されたhtmlでも改行を行います。

注意：trueにするとは通常のmarkdown仕様とは異なる振る舞いとなり、デフォルトはfalseです。

bool AutoHyperlink

trueにすると、テキスト上に記載されたURLに対して、aタグによるリンクを自動生成します。

注意：trueにするとは通常のmarkdown仕様とは異なる振る舞いとなり、デフォルトはfalseです。

bool EncodeProblemUrlCharacters

trueにすると、URL中に「 ” ‘ * ( ) [ ] $ : 」の文字列があった場合、%xxの形式にエンコードします。

注意：trueにするとは通常のmarkdown仕様とは異なる振る舞いとなり、デフォルトはfalseです。

string Version

使用しているMarkdownのバージョンを返します。
例えばver1.13の場合、”1.13″という文字列が返ってきます。

また、http://code.google.com/p/markdownsharp/ で最新版のソースが入手できます。

MarkdownOptionクラス

Markdownのコンストラクタに渡すためのコンテナです。
本クラスの状態は変更不可(immutable)なので、newした後にプロパティ値を変更したい場合は、別途新しいインスタンスをnewする必要があります。

MarkdownOptionメソッド

こちらは、3つのコンストラクタが有ります。

• MarkdownOptions ()
• MarkdownOptions (bool loadFromConfigFile)
• MarkdownOptions (bool autoHyperlink, bool autoNewlines, string emptyElementsSuffix, bool encodeProblemUrlCharacters, bool linkEmails, int nestDepth, bool strictBoldItalic, int tabWidth)

MarkdownOptions ()

デフォルトコンストラクタです。
システムのデフォルトパラメータを元にオプション定義を生成します。
デフォルト値は、標準のmarkdown仕様と互換性があるものとなっています。

MarkdownOptions (bool loadFromConfigFile)

loadFromConfigFileパラメータをtrueにすると、app.configの定義内容を元にオプション情報をセットします。
app.configに記載するKey,valueの値は、前述したMarkdownクラスのコンストラクタを参照してください。

loadFromConfigFileパラメータfalseの場合は、new MarkdownOptions()と同じ処理を行います。

MarkdownOptions (bool autoHyperlink, bool autoNewlines, string emptyElementsSuffix, bool encodeProblemUrlCharacters, bool linkEmails, int nestDepth, bool strictBoldItalic, int tabWidth)

全てのパラメータを明示的に引数で指定して、オブジェクトを生成します。
NestDepthとTabWidthのパラメータはMarkdownクラス側で見ていないので、何を指定しても意味が無いようです。

MarkdownOptionプロパティ

以下のプロパティを参照可能です。(セットすることはできません)
各パラメータの意味は、前述のMarkdownクラスの各パラメータを参照してください。

bool    AutoHyperlink
bool    AutoNewlines 
string  EmptyElementSuffix
bool    EncodeProblemUrlCharacters
bool    LinkEmails
bool    StrictBoldItalic
int     NestDepth
int     TabWidth