niszetの日記

アナログCMOS系雑用エンジニアが頑張る備忘録系日記

(Pandoc) Jira Writerを読む(自分用メモ)

これが一番シンプルなのでは?と思ったので。

docxは仕様が複雑なので、もっと簡単なファイルフォーマットでReader/Writerを学ぼうと思ったところ、最近追加されたJiraのWriterがわかりやすそうだったのでこれにした。Readerはまだない。

たぶん、ほかのtext系のファイルフォーマットでも良いと思う。docxみたいなバイナリ(といっても実態はxmlだが)を読むのはやめよう。あれは沼。あれは闇。あれは全てを飲み込む狂気の形式。。。

JiraのWriterのコードはここにある。

github.com

これを読む前に、Pandoc's native ASTについてはある程度理解している必要がある。ここでは説明しない。

あと、Haskellの基本的な文法もある程度さらっている必要がある。具体的な処理がわからなくても、モナドってなんだっけ…もにゃもにゃ…くらいのことはわかってないと当然読めない。これもここでは説明しない。なぜなら説明できるほどわからないから。

というわけで、多分間違ってる箇所があるのだが、Haskellは難しいしPandocのコードは長いしで、ちゃんと理解してから書こうとするといつまでも書けないのでとりあえず、読んだ記録ぐらいのつもりで書く。なので、あまり参考にならないししないでくださいな。

module Text.Pandoc.Writers.Jira ( writeJira ) where ... から、このモジュールからはwriteJiraだけが外に出ていることがわかる。つまり、ほかの関数は中で自由にしている。ただし、ほかのファイルを読むと同名の関数が定義されていたりするので、必要な処理はどの形式でもおおむねかわらないのではということがなんとなーく見れる。

肝心のwriteJiraはこんな感じの定義。

writeJira :: PandocMonad m => WriterOptions -> Pandoc -> m Text
writeJira opts document =
  evalStateT (pandocToJira opts document) startState

WriterOptionsPandoc を受け取っているが、PandocLuaで扱ったとき、documentのtop階層だったはずなので、たぶんそれ。実体もdocumentってなってるので多分。ここで、Textは import Data.Text (Text, pack) のTextだろう。

で、pandocToJiraは直後に定義がある。

pandocToJira :: PandocMonad m
             => WriterOptions -> Pandoc -> JiraWriter m Text

ここで、JiraWriter

type JiraWriter = StateT WriterState

とあって、

data WriterState = WriterState
  { stNotes     :: [Text]      -- Footnotes
  , stListLevel :: Text        -- String at beginning of list items, e.g. "**"
  }

とあるので、状態を持ちながら、Writerのオプションと文書を受け取ってPandocMonad Textを返している、というなる、のかな?ということは、ファイルへの書き出しはここではしておらず、あくまでPandoc's ASTをうけとって、Jiraの形式に変換して返しているのだろうということになりますね。

他に、escapeCharForJira :: Char -> TextescapeStringForJira :: Text -> Textから、エスケープするべき文字を変換していることがわかり、メインの変換処理はblockToJirablockListToJirainlineListToJirainlineToJiraで行っていて、Listの入っているものはmapMでListなしの関数を呼び出して処理、それぞれの処理は要素毎に定義してある、ということが見て取れる。つまり、Pandoc's ASTのすべての型に対して、blockToJirainlineToJiraの処理を書き、それのList版を書き…とやっていけばよいということがわかる。

あとは補助関数っぽいので、これらはフォーマットごとに違うだろう。

あとはstateがどのようにふるまっているのかが追い切れていないのでいずれ読む…のと、個別の関数の挙動が(Haskellの理解が浅いために)把握しきれていないので、これを順次追いかけていく予定…。

ということで、Pandoc's ASTを把握したら次はWriterを見てみるのが良さそう、という考えは良さそうです。

概略がわかれば、あとはひとつひとつ追っていけばよいので気が楽ですね(楽ではない)

という、メモでした。