Pinky:blog

この文書では、トランスレータ（テキストからHTMLへの変換を行うモジュール）の仕様について解説します。

これは開発者向け（既存のトランスレータを改良したい人、あるいは一からトランスレータを作りたい人向け）の文書です。Pinky:blogを普通に利用する方は、この文書ではなく使い方を参照してください。

• ▲TOP

Pinky:blogが用いるHTMLトランスレータの実体は、Ruby言語によって書かれたスクリプト（xxx.rb）と、そのスクリプトが必要とするものを含んだディレクトリのセットである。

• ▲TOP

markdownトランスレータを例にとって解説する。

mod/
  - translator/
      - markdown.rb
      - markdown/
          - （必要なファイル）

モジュールディレクトリmodの位置は、設定ファイルpinkyblog_conf.rbによって定義される。標準ではblog.cgiと同じ場所にある。

Pinky:blogはmarkdown.rbをトランスレータとして認識する。ファイル名は、半角英数字、ハイフン（-）、アンダースコア（_）、ドット記号（.）のみで構成されていることが望ましい。

markdown.rbが必要とするファイルは、全てmarkdownという名前のディレクトリの下に置く。このディレクトリは、必要でなければなくてもかまわない。

• ▲TOP

スクリプトxxx.rbの基本的な構成は、次のようになる。

CAPTION = "〜記法で書く"

class Translator
  def text_to_html(text)
    （トランスレート処理）
  end

  def format_guide
    return(<<-TEXT)
    （その記法の解説文）
    TEXT
  end
end

スクリプトの文字コードはUTF-8N（BOMなしUTF-8）でなければならない。

定数CAPTIONには、その書き方を表す短い文字列を設定する。これは記事を書くとき、記法を選択するボックスに表示される。

Translatorクラス

Pinky:blogから実際に呼び出されるのはTranslatorクラスである。Pinky:blogはTranslator.newで新しいインスタンスを作成し、メソッドtext_to_html(text)でHTMLへの変換処理を行う。

format_guideは、その記法についての解説文（マニュアル）をブラウザに表示するときに呼び出されるメソッドで、このメソッドはその記法自体で書かれたテキストを返す必要がある。たとえばmarkdownトランスレータのformat_guideメソッドは、markdownで書かれた簡易マニュアル（String）を返す必要がある。

他のファイルを呼ぶ

添付ディレクトリにある必要なファイル（スクリプトなど）を呼び出すには、定数DIR_PATHを用いる。

たとえばbluecloth.rbを呼び出したい場合には、次のように書く。

require (DIR_PATH + 'bluecloth').to_s

DIR_PATHはPathnameオブジェクトである。

コンテキスト

スクリプトxxx.rbは、無名Moduleの下で（module_evalで）評価される。つまり、先に挙げたスクリプトの例は、実際には次のようなイメージになる。

module ***
  CAPTION = "〜記法で書く"

  class Translator
    def text_to_html(text)
      （トランスレート処理）
    end
  end
end

このため、使われていない名前（Translator・CAPTION・DIR_PATH以外の名前）で、クラス・モジュール・定数を自由に定義することができる。

• ▲TOP