wrdapは、MS-Word文書を扱うためのruby用ライブラリです。
今回の主な変更点は、markdownの原稿中に中央揃え・右揃えなどの指示を書き込めるようにしたことです。
markdownの原稿は、pandoc.exeというコマンドでMS-Wordの文書に変換できます。
これまでは、指示を別のファイルに書いておくか、文字列に記録しておく必要がありました。しかし、それだと煩雑で、保管も不便です。そこで、一体化できるように工夫しました。
［pandocに関する参考サイト］
pandoc.exeは、markdownの原稿をMS-Word文書に変換できるコマンドです。htmlやTeXの原稿に変換することもできます。
pandoc.exeで変換する場合、markdownの原稿中に書かれているhtmlのコメントは無視されます。
そこで、原稿中に中央揃えなどの指示をhtmlコメントとして書いておき、それを抽出して、MS-Wordの起動・処理の際に意図通りの調整が行われるようにしました。
たとえば、下のようなmarkdownの原稿があったとします。
-------- 原稿ここから
# テスト文書
<!-- center -->
これは、markdownをdocxファイルに変換するためのテスト用文書です。
2016年２月27日
<!-- right -->
-------- 原稿ここまで
上の原稿が test.md というファイルになっているものとします。
その場合、次のrubyスクリプトで test.docx を生成できます。
「テスト文書」が中央揃え、「2016年２月27日」が右揃えになります。
pandoc.exeとMS-Wordの両法を利用。
# encoding: Windows-31J
require "wrdap"
mkd_str = File.read("test.md")
print Wrd::mkd2docx(mkd_str, "test.docx")
Wrd::mkd2docx() というメソッドは、どの行を中央揃えや右揃えにしたかといった情報を文字列にして返します。なので、それを出力するために print を書きました。
以下、markdownの原稿中に指示情報等を盛り込むことに関連するメソッドについて詳述します。
○ 機能: markdownの原稿中に書かれた中央揃えなどの指示情報を抽出する。
○ str: markdownの原稿が代入された文字列。
○ 戻り値: 指示情報等を記録した文字列。抽出できなかった時はnil。
○ 利用例: info_str = Wrd::comment_info(mkd_str)
この戻り値 info_str は、Wrdoc::set_info(info_str) とすることにより、指示通りの調整を行うことができる。サンプルのスクリプトをあげると次のとおり。
# encoding: Windows-31J
require "wrdap"
out_file = "test02.docx"
mkd_str = File.read("test.md")
info_str = Wrd::comment_info(mkd_str)
docx_str = Wrd::pandoc_docx(mkd_str)
File.open(out_file, "wb") {|ff| ff.write docx_str}
Wrdap.new(out_file) do |doc|
doc.set_info(info_str)
doc.save
end
○ 備考１: 中央揃えなどの指示情報としては次のものがある。
center 中央揃え
left 左揃え
right 右揃え
justify 両端揃え
distribute 均等割り付け
pagebreak 改ページ
no 処理なし
[「pagebreak <=5」とすれば、ページの残り行数５行以下の場合に改ページ]
center と pagebreak の両法を指定したい時は、カンマで区切って書くか、改行して書く。たとえば下のとおり。
<!-- center, pagebreak <=5 -->
<!-- center
pagebreak <=5 -->
○ 備考２: 「指示等の情報」には中央揃えなどの他に、用紙の横幅、用紙の縦の長さ、あるいは、ページ番号や標準日本語フォントなども含まれる。
これらを複数指定する場合は、カンマで区切るのでなく改行して書く。
半角の '#' から改行までは無視される。
たとえば、markdownの原稿中に下のように記述。
<!-- 用紙の横幅 210.0
用紙の縦の長さ 297.0
# １行の文字数 40.0
# １ページの行数 36.0
上余白 35.0
下余白 30.0
左余白 30.0
右余白 30.0
ヘッダの高さ 15.0
フッタの高さ 17.5
ガター 0.0
段組数 1
段組境界線 false
ページ番号 なし # あり, フッターにあり
標準日本語フォント MS 明朝 # MS P明朝, MS ゴシック, MS Pゴシックなど
標準欧文フォント Century # Calibri, Arial, Times New Romanなど
標準フォントサイズ 10.5 -->
○ 機能: 指示情報等の例を返す。どのような情報があったかを確認したい時に利用。
○ 戻り値: 指示情報等の例を３分類の形で返す。つまり、三つの要素からなる配列を返す。次の三つ。
○ 利用例: pa, ps, sz = Wrd::info()
ここで得られる pa, ps, sz は、いずれも文字列。
sz(ページサイズに関する情報)は指示情報ではないが、ページセットアップの情報を書くときに参考にされたい。
○ 備考: ps(ページセットアップに関する情報)は、日本語MS-Wordの標準的な情報なので、markdownの原稿の最後に「」で囲む形で挿入すれば、MS-Wordの標準的なページサイズや文字フォントにするための指示となる。
たとえば下のようにする。
mkd_str = mkd_str + "\n<!-- #{Wrd::info[1]} -->\n"
こうすると、ページサイズがA4、標準日本語フォントが「MS 明朝」、欧文フォントはCentury、フォントサイズが10.5にするとの指示になる。
○ 機能: markdownの原稿をMS-Word用の文書に変換。
○ mkd_str: markdownの原稿が代入されている文字列。
○ out_file: 出力ファイル名。"test.docx" など。
ファイル名の拡張子として次ぎのものを指定可能。
docx, doc, docm, odt, rtf, xml
どの拡張子も MS-Word によって保存される。
odtは Open Document、xmlは Word2003xmlを意味する。
○ 戻り値: どのような調整が行われたかの報告が代入された文字列。
○ 備考: この mkd2docx() では下の調整が行われる。
表の調整において「列名を均等割り付けに」というのは、表の第１行目を見出し(項目名)とみなして均等割り付けにするもの。
箇条書きの行番号については、「i.」とか「iv.」などの小文字のローマ数字を、まる囲み数字の「①」とか「④」などに変換する。
もちろん、markdownの原稿中に表がなければ表に関する調整は行われないし、箇条書きがなければ箇条書きの調整が行われない。
rubyスクリプトのサンプルを掲げると下のとおり。
-------- ここから
# encoding: Windows-31J
require "wrdap"
mkd_str = DATA.read
print Wrd::mkd2docx(mkd_str, "test.docx")
__END__
# 簡易変換の例
<!-- center -->
## 表の例
|名称|電話番号
|---|---
|時報|117
|天気予報|177
## 箇条書きの例
i. バナナ
ii. リンゴ
iii. みかん
-------- ここまで
Wrd::comment_pa(str) は、markdownの原稿からパラグラフの配置に関する指示情報(center, right など)を抽出する。
Wrd::comment_ps(str) の方は、markdownの原稿からページセットアップに関する指示情報(用紙の横幅、用紙の縦の長さなど)を抽出。
どちらも戻り値は文字列。
comment_pa() で得られた文字列は、Wrdoc::paragraph_adjust(str) の引数として用いることができる。
comment_ps() の戻り値は、Wrdoc::page_setup() の引数として利用できる。
このメソッドは、rubyの配列を '|' を区切り文字とするmarkdown用の表形式に変換するメソッド。次のような仕様変更を行いました。
(a) 第１引数として、rubyの配列だけでなく、文字列を指定できるようにした。
文字列は、CSVまたはタブ区切りテキストが代入されているもの。
あるいは、CSVやタブ区切りテキストが書き込まれているファイルの名前。
文字列に改行コードが含まれておらず、かつ、該当の名前のファイルが存在する場合にファイル名とみなされる。
(b) markdownにおけるtableの見出しと本体の区切りを第１引数の配列または文字列に盛り込んでおけるようにした。
見出しと本体の区切りとは、CSV形式で書くと「-----,:----,--:--,----:」のようなもの。
'-' と ':' を組み合わせて記述する。':' の位置づけで左揃え、中央揃え、右揃えを指定。
従来は、この見出しと本体の区切りを第２以降の引数において配列として与える仕様になっていたが、それだと面倒なので、第１引数の配列・文字列に盛り込めるように改めた。従来通り第２引数で指定することもできる。
区切りが第１引数と第２以降の引数の両法で指定されている場合、第１引数のものが優先的に採用される。
(c) tableの見出しと本体の区切りが省略された場合、table本体のデータの状況に応じて自動的に区切りを挿入。
table本体の列がすべて整数である場合、または、小数点以下の桁数が一致する数値である場合、その列が右揃えになるよう区切りを「----:」にする。
それ以外の列については「-----」になる。
このような見出しと本体の区切りを自動的に挿入する。
従来も区切りを自動的に挿入していたが、どの列も「-----」としていた。
メソッドの利用例をあげると次のとおり。
# encoding: Windows-31J
require "wrdap"
csv_str = <<EOS
名称,数値
円周率,3.141597
自然対数,2.718282
EOS
print Wrd::matrix2table(csv_str)
上の実行結果は下のようになる。
|名称|数値
|-----|----:
|円周率|3.141597
|自然対数|2.718282
上の例では「数値」の欄は右揃えの指定になっているが、データ本体の小数点以下の桁数が異なるものがあると、右揃えの指定にはならない。
メソッド matrix2table(data, *arg) の仕様を改めて掲げると下のとおり。
○ 機能: rubyの配列あるいは文字列を縦線形式のmarkdownの表に変換
○ data: 表の素材となるrubyの配列または文字列。
文字列は、CSVあるいはタブ区切りテキストが代入されたもの。または、それらが記録されたファイルの名前。
○ arg: 必要に応じて次の３つを指定可能(複数指定可)。
1) markdownのtableの見出しと本体の区切り
2) tableの属性(htmlのborderなど)の指定
3) tfootを設けるための指定
○ 戻り値: 文字列。縦線形式のmarkdown形式に変換されたtableを返す。
○ 利用例: str = matrix2table(xx)
str = pipe_table(xx, ["-----:"]*4) # 4列とも右寄せにする場合
str = matrix2table(xx, 'border="1"') # table属性の指定
str = pipe_table(xx, '========') # tfootの指定
○ 備考: オプションの「2) tableの属性(htmlのborderなど)」および「3) tfoot」は、ruby用ライブラリkramdownの利用を意式したもの。ワード文書生成時には使えないので注意。kramdownは、markdown→html変換等を行うためのruby用ライブラリ。
str2ary() というメソッドは、CSVやタブ区切りテキストの文字列を配列に変換するものです。
従来は、数値として解釈できるデータを文字列でなく数値に変換していました。
その際、「12.0」のように小数点以下に0しかないものは整数に変換していました。
これだと、いろいろ不都合なことがあるので、数値に変換せず文字列のままにしておくことができるように改めました。
数値に変換するかどうかの切り替えは、第３引数 atype で指定します。
これが :num だと、従来通り数値に変換されます。
それ以外の値、たとえば nil などにすると数値への変換が行われません。
第３引数を省略すると、:num が指定されたものとみなされて、数値への変換が行われます。従来と同じ結果を得ることになります。
このメソッド Wrd::str2ary(str, sep, atype) の仕様を掲げます。
○ 機能: 文字列を配列に変換する。
○ str: CSVやタブ区切りテキストが代入されている文字列。
○ sep: フィールドセパレータ(区切り文字)。
省略またはnilの時は自動判別。省略時は nil。
自動判別の場合、第１引数のstrの中にタブコードが多く含まれていれば “\t"、カンマが多ければ “," になる。
○ atype: 数値に変換可能なデータを数値に変換するか うかの指定。
:num を指定すれば数値への変換が行われる。省略時は :num。
nil など :num 以外を指定すると数値への変換は行われない。
○ 戻り値: 変換結果である配列。２次元配列として返される。
○ 利用例: ary = str2ary(str)
ary = str2ary(str, “\t", nil)
○ 備考: 文字列から配列への変換は、rubyの標準添付ライブラリ csv を利用している。
～ 以上 ～
Copyright (C) T. Yoshiizumi, 2016 All rights reserved.