【しばらく編集不可モードで運営します】 編集(管理者用) | 差分 | 新規作成 | 一覧 | RSS | FrontPage | 検索 | 更新履歴

Text::WikiFormatのアバウト翻訳 - 注:誤訳多し

目次

注:誤訳多し

Wikiテキストを翻訳し、他のフォーマットへ整形するためのモジュール。

元になったページ。http://search.cpan.org/author/CHROMATIC/Text-WikiFormat-0.5/lib/Text/WikiFormat.pm

名前

 Text::WikiFormat - Wikiテキストを翻訳し、他のフォーマットへ整形するためのモジュール。

要約

 use Text::WikiFormat;
 my $html = Text::WikiFormat::format($raw);

記述

オリジナルのWikiウェブサイトは、編集し、ページを加えるために非常に単純なインターフェースを持つように意図されました。 そのフォーマットルールは単純で、つかいやすいものです。 さらに、それらはこのモジュールによって、他のより複雑なマークアップ言語に容易に変換できます。 このモジュールはデフォルトでHTMLを生成しますが、有効なPOD、DocBook?、 XMLあるいは他の想像的なフォーマットを生成するために拡張することができます。

最も重要な関数は、format()です。これはデフォルトでインポートされません。

format()

format()関数は第一引数として変換対象のテキストを要求し、変換されたテキストを返します。 それは2つめ以降の引き数を取ることができます。 第2の引数はタグのハッシュへのリファレンスです。 この中に渡されたものはすべてデフォルト・タグ振る舞いをオーバーライドするでしょう。 これらのタグの使用法は後述します。 第3の引数はオプションのハッシュ参照です。 それは、現在次のものに制限されています。

任意のリンクの接頭辞です。HTMLモードにおいて、これはWikiへのパスです。 実際のリンク項目はそれ自身、接頭辞に追加されるで しょう。 これは完全なURIを作成するために使用されます:

 { prifix => 'http://example.com/wiki.pl?page=' }

デフォルトで負になっているこのフラグは、使うことによってリンクに意味を持たせられます。 拡張リンクは角括弧によってマークされます。これは全てのエンジンからパクッたものです(http://everydevel.com/)。 タイトルはパイプを挟んで、リンクターゲットの後に置くことができます。 すなわち、以下は全て有効な拡張リンクです。

 [有効 な リンク]
 [リンク先|タイトル]

拡張を許可した目的のフォーマットのどこにリンクの意味が表示されるのかというと、 そのタイトルはURIの代わりに表示されます。 HTML的に言えば、タイトルはA要素(そのHREF属性の内容ではない)の内容となるのです。

デフォルトで真になっているこのフラグは、WikiWordがあるところならどこにでもリンクが作成されるようにします。 このフラグを負にした場合、おそらく、上記の拡張を可能にしたくなるだろうということに注意してください。 さもないと、あなたのドキュメントの中でリンクを作成する方法がなくなってしまいます。 このフラグを負にするためには、次のペアを使用してください。

{ implicit_links => 0 }

Wikiフォーマット

Wikiフォーマットは非常に単純です。 3つのシングルクォートで包まれたアイテムは強調としてマークされます。 2つのシングルクォートで包まれたアイテムは斜体強調されたものとしてマークされます。 多数の単語から成るどんな単語もリンクに変えられます。 行頭から始まる、最初の4つ以上のハイフン文字が水平線を作ります。 改行は適切なタグに翻訳されます。

リストはすべて1つのタブあるいは4つのスペースによってインデントを付けられます。 リストは番号が振られていないかもしれません。 そこでは、各アイテム はそれ自身の特徴を持つかもしれません。 これらは主要な星印およびスペースによってマークされます。 さらに、それらは命じることができます。ここで期間およびオプションのスペースは、1つ以上の英数字の文字のどんなコンビネーションにも続くことができます。 一方のマークのない、あらゆる字下げしたテキストもコードであると考えられ、 整形済みのものとして扱われます。

下記はマークされるような拡張リンクと共に、有効なWikiフォーマットです。

 ANormalLink
 [let the Sun shine|AnExtendedLink]

   * unordered one
   * unordered two

   1. ordered one
   2. ordered two

   code one
   code two

The first line of a normal paragraph. The second line of a normal paragraph. Whee.

輸出

人生をより快適にしたければ、既にデフォルト・タグを持っていて、オプションが設定されているサブルーチンを自由に輸入することができます。 あなたが接頭辞を使用すれば、これは特に手軽です。

 use Text::WikiFormat prifix => 'http://www.example.com/';
 wikiformat('sume text');

4個の特別のキーを除いて、タグはすべてタグとして解釈されます。

輸入関数が何と呼ばれるかをコントロールするためにasフラグを使ってください。 そう、例えば・・・、

 use Text::WikiFormat as => 'formatTextInWikiStyle';
 formatTextInWikiStyle('some text');

しかし、あなたはもっといい名前を選ぶかもしれません。

呼び出しの持つ意味は、format()関数のそれと同じです。 この呼出し例では、輸入関数へのどんな追加のタグあるいはオプションもデフォルトとして指定されたものをオーバーライドするでしょう。

 use Text::WikiFormat as => 'wf', extended => 0;
 wf('some text', {}, { extended => 1 });

デフォルトでは拡張リンクを不能にすることを指定していますが、このとき拡張リンクは可能になるでしょう。

この特徴はTony Bowden <tony@kasei.com>によって示唆されました。 しかし、全実装の非はほとんど私にあります。 Kate L Pugh(<kake@earth.li>)は、テストコードと共に機能が作動しないことを指摘してくれました、 おかげで、この問題は今回修正されました。

内部の詳細

タグ

行単位の項目とリスト、2つのタイプのWikiマークアップがあります。リストはラインから構成され、さらに他のリストを含むことができます。

行単位の項目

行単位の項目には、単純なタグとデータを含んでいるタグ、という2つの種類があります。 単純なタグというのは、改行や水平線のことです。 改行は改行文字(\n)に遭遇するたびに、常に挿入されます。 行頭に4つ以上のダッシュ文字で始まっている場合は、常に水平線が挿入されます。 このとき、余白は許可されません。 これらは自動的にそれぞれHTMLタグに(<BR>と<HR>に)なります。 この動作をオーバーライドするためには、単に次のもののようなタグを渡してください。

 my $html = format($text, { newline => "\n" });

3つの行単位の項目はより複雑で、サブルーチン参照を要求します。 このカテゴリーは強調やより強い強調のタグやリンクを含んでいます。 そして、サブルーチンに渡された第1の引数は、マークの間に見つかったデータになるでしょう。 第2の引数はハッシュへの参照である$optsです。 強調タグのためのデフォルトの動作はこの構文で再定義することができます。

 my $html = format($text, { strong => sub { "<b>$_[0]</b>" } });

リスト

3つのタイプのリストがあります。 コード 、番号無しのリスト、番号付きのリスト。 これらの各々は通常、1つ以上の一方のタブ、あるいは4つ以上の余白文字での字下げによってマークされます。 (しかしながら、これは改行を含んでいません。) これらの3つのカテゴリーのうちのどれにも属さない行も、自動的にパラグラフリストに入ります。

リストはバージョン0.50の時点で、字下げを持っていることを要求しません。 しかしながら、これに注意してください。

タグ・ハッシュ中のリスト・エントリーは配列参照を含んでいるに違いありません。 最初の2つのアイテムは、リストの最初に、およびリストの終わりに使用されるタグです。 あなたが期待どおり、最後のアイテムは、各ラインの最初および終わりに使用されるタグを含んでいます。 個々のラインのより多くの処理がある必要があるところで、 第3のアイテムとしてサブルーチンを使用してください。 番号はHTMLリスト中でこのようにして規律 正しいラインに付けられます:

 my $html = format($text, { ordered => [ '<ol>', "</ol>\n", sub { qq|<li value="$_[1]">$_[0]</li>\n| } ] });

それが処理された後、これらのサブルーチンへの第1の引数は行自体のテキストです。 (リスト・アイテムとしてこれをマークアップするために使用されるインデント、およびマークは削除されます。 また、行の残りは他の行単位の整形項目があるかチェックされます。) 後の引数はこのリスト・タ イプを見つけるために使用される正規表現中の捕らえられた変数です。 規律正しいリストのための正規表現は次のとおりです:

 qr/^(?:\t+|\s{4,})([\dA-Za-z]+)\.\s*/;

これは、ラインが1つ以上のタブか、あるいは4つ以上のスペースで始まるに違いないということを意味します。 その後、それは、単一の文字列および有無を問わない余白が後続する1つ以上の英数文字列を含んでいるに違いありません。 この最後のグループの内容は、保存され、第2の引数としてサブルーチンに渡されるでしょう。

リストは自動的に始められ、必要なときに終了します。

リストの見付け方

Text::WikiFormat?は、リストを見つけるために正規表現を使用します。 これらは%tagsハッシュの中でそのリストキーとして維持されます。 コード・リスト・アイテムを見つける正規表現を変更するためには、次のものを使用してください:

 my $html = format(
  $wikitext,
  list => { code => qr/^(?:\t+|\s{4,}):\s+/ }
 );

これはインデントおよびマーク・コード・ラインへのコロンを要求するでしょう。 近道は、$Text::WikiFormat?::indentが変更後のインデントマーカーにマッチするか、試しに使用してみることです。 (あなたがそれを変更すれば、既存のリスト正規表現はあなたの修正を反映しないかもしれません。 これは、将来のバージョンだがこれで実際に修正されるかもしれません。) すべきだ できるだけ読み出し専用の変数にしておかれること。

正確な順序でのリストの見付け方

勇猛なバグ・リポーター、Tom HukinsがCPAN RT Bug#671の中で指摘するように、 Text::WikiFormat?がリストを探索する効率はPerlのプラットフォームおよびバージョンによって変わります。 いくつかの、リストを見つけるための特定の正規表現によって、 1種類のリストであるように意図されるものは、異なる種類のリストとして扱われてしてしまうかもしれません。

新しいリスト・タイプを加えている場合は、このことを覚えておいてください。 %tagsの中のlistorderエントリーは、ほとんどの特効薬から最小の特効薬として、 その正規表現を適用することをText::WikiFormat?に強いるために存在します。 それは配列参照を含んでいます。 デフォルトで、最初に規律正しいリストを捜し、次に無秩序のリストを探し、 そして、最後にコードの参照を探します。 どんな追加のリスト・タイプも内蔵のタイプの前に処理されるでしょう。 しかし、もしあなたがオーダーを明示的にセットしなければ、実行の順序は保証されません。 私はあなたの心のすべてを読むことができないのです。:)

著者

著者はchromatic、chromatic@wgz.orgです。ゼリービーンズ・チーム(Jonathan Paulettを含む)からの多くの入力から、Tony BowdenとTom Hukinsは両方ともいくつかの有用な特徴を示唆しまてくれました。 Kate L Pughは、さらにいくつかのパッチを提供しました。実装のことで至らないことがあれば、それは私のせいです。

バグ

format_line()の中のリンクチェッカーは、HTML、XMLあるいはSGMLスタイルに続かない、既存のリンクを検知してはなりません。 それらは、いくつかのSGMLスタイルでまた死ぬかもしれません。 Sic transit gloria mundi.

TODO

著作権

Copyright(C)2002, 全ての権利はchromaticに帰属します。 このモジュールはPerl自体と同じ条件の下で配布されます。