nDiki : Pod

Pod - Plain Old Documentation format

Perl スクリプトファイルの中に埋み可能なドキュメンテーションフォーマット。ドキュメンテーションコメントに使われる。

2003年11月19日 (水)

pod2latex

仕事で書いた Perl モジュールの API 仕様を紙媒体にしなければならないので、今回は pod2latex を使ってみる。

 pod2latex -modify -full -out hoge-utf8.tex lib

で lib ディレクトリ以下の *.pm の Pod が集められて hoge-utf8.tex になる。ソースを UTF-8 で書いているのでこれを lv などで EUC-JP に変換して、platex してdvipdfmx。

前に Javadoc から LaTeX に落とした時に比べて非常にすんなりと変換してくれる。 '=item foo([opt])' とかすると ] 文字が落ちたりする以外は特に今のところ目につく問題なし。

ま、いざとなったらスクリプトに手を入れて直せるだろうし、なかなかいいんじゃないでしょうか。

スポンサードリンク

[ permalink ]

[ 11月19日全て ]

2005年2月20日 (日)

Ming でいきなりハマる

一昨日インストールした Ming 0.3 beta 1 + Perl でいろいろ実験。 Ming 関連は資料が少ない。

SWFバージョンの設定

SWF::setVersion(6) をしても吐き出されるバージョンは5。 SWF::Movie の Pod に書いてある

 new SWF::MovieWithVersion(6)

はエラー。

結局 xs ファイルを見て、

 SWF::Movie::newSWFMovieWithVersion(6);

なら呼べてバージョン6形式で吐けることを確認。

テキストフィールドのインスタンス名? 変数名?

テキストフィールドの onChanged イベント処理のテスト。

SWF::TextField インスタンスに setName で名前を設定して ActionScript から onChanged イベントハンドラを設定するも、ウンともスンとも言わない。設定した名前に文字列を代入すると表示が書き換えられるはする。はて。

どうやらMacromedia Flash ではテキストフィールドにインスタンス名と変数名があるようだ。 setName で設定した名前はどっちだったのか? どうやら変数名っぽいのだが。

また手元の本によると onChanged はインスタンス名を指定するらしい。 Ming ではどうする?

いろいろいじったところ、SWF::Movie に add した後の返り値である SWF::DisplayItem オブジェクトに対して setName し、ActionScript でこの名前のインスタンスに対して onChanged にハンドラを与えたところうまく動くようになった。ということはこれがインスタンス名なのか?

[ permalink ]

[ 2月20日全て ]

2006年2月15日 (水)

ドキュメンテーション大全

プロジェクトの後半で納品用ドキュメントの整備を始めるのだが、その時はたいがいもう切羽詰りはじめていて構成やら体裁やらマネジメントやらを工夫する余力が無かったりする。ついつい(次回は改良しようと思っていつも思っている)前回のプロジェクトの手法を踏襲してしまいがちだ。ともすれば劣化コピーになりかねない。

やはり、忙しくても日頃からの改善は重要である。

最近はアジェンダ・議事録・開発メモなどを、積極的に Wiki や Subversion で共有するようにし、その点では以前より改善してきている。

今後はさらに、出荷ドキュメントのレビュープロセスなどを確立し品質を高めていきたいところである。現状でもチームメンバでのピアデスクチェックやパスアランドを非形式的に行っているのだが、「チェックの程度」やその後の「修正」および「修正の確認」については、まだなんとなくやったかなという具合。この辺りを工夫したい。

先月発売されていて気になっていた「開発の現場 Vol.003」に、何かヒントがあるかなと思って買ってみた。

開発の現場 Vol.003 効率UP&スキルUP ドキュメンテーション大全

パラパラと見た感じではテクニカルライティングの話はあまりなく、主にソフトウェア開発における中間成果物としてのドキュメントや開発者間ドキュメントをどうとりまとめていくかという話が中心のよう。 Wiki による開発資料のライトな共有など、うちのチームでも進めている話など。

「(最初から)完全なドキュメントを書こうとしない」というのはもっとも。状況はほとんどの場合変わるし、最初の段階では未確定の部分も多い。だからといって、いつまでたっても手元で温めていてもしょうがない。

技術的な話では Perl の Pod を活用しようという話。 Perl 以外の言語のコメント中に Pod 形式でドキュメントを書こうという提案や、Apache で動的に Pod ドキュメントを整形しようという話とか。

テキストフォーマットとしての Pod は =over / =item / =back によるリスト表現など、最近のフォーマットに比べてすごく読み易いわけではないが、たしかに他の言語のコメントに埋め込んでおいて処理するのは、標準の Pod 関連のモジュールでできるな。

自分も Pod でドキュメントを書くけれど、(Perl 以外は) 個人的には reStructuredText にしたいと考えている。ただ Pod みたいに他のテキストの一部に埋め込んでその部分のみ処理する記法およびツールがが標準の reStructuredText / Docutils には見当らない。実はどっかにあるのだろうか。

[ 読書ノート ]

[ permalink ]

[ 2月15日全て ]

2006年7月25日 (火)

Perl 用の doxygen のようなツールはないのかな

WiKicker のソースコードを人に説明するのにプリントアウトして説明するのに、doxygen のようなツールが欲しいのだけれど Perl 用のものはないのかな。

ソースコードを色付けした HTML に変換してくれる
Pod とコード本体を混在してドキュメント化してくれる
ソースツリー内のファイルをそれぞれ処理してくれて、インデックスファイルも生成してくれる。
できれば識別子がリンクになってくれる

というのが希望。1 だけなら結構いろいろなツールがあり、1 + 2 なら perltidy で実現できる。しかし 3、4 までしてくれるツールが見つけられない。

とりあえず perltidy の Perl::Tidy と File::Find で再帰的にまとめて HTML に変換するスクリプトだけは書いて、一気に変換だけはできるようにしておいた。

インデックスの作成までは面倒なので未着手。

[ permalink ]

[ 7月25日全て ]

2006年7月28日 (金)

Perl で CR/LF/CRLF 全対応の1行毎読み込み処理

Perl プログラムでテキストファイル処理を改行コード CR/LF/CRLF 全対応にしようと思ったが、書こうとするとこれが結構面倒臭いことに気がつく。

$/ に正規表現が設定できないため、<FILEHANDLE> で単純に3パターン対応ができない (LF と CRLF に対応とかならすぐできる)。

小さいファイルと仮定して良いなら全部読み込んで自前で行分割、大きいファイルならまじめにバッファリングして改行コードをスキャンして行処理するのが正攻法かな。多少効率悪くなりそうだけれど。

Pod::Html (1.0504) の場合

Perl 5.8.8 の Pod::Html (1.0504) だと pod2html の中で $/ = "" と設定して、パラグラフ単位で読み込んでそのあと処理している。

PerlIO レイヤー

最近の Perl であれば PerlIO::crlf、 PerlIO::eol あたりが使えそうである。

もちろん Perl 5.005_03 だと NG。

[ permalink ]

[ 7月28日全て ]

2009年8月28日 (金)

今日のさえずり - 「チューペットみたいな何か」いっぱいあった

2009年08月27日

09:28 前に座っている人のワイシャツの胸ポケットに現ナマがちらり。 [mb]
09:37 「もしよかったらこれ読んでください」とラブレター風の封筒を配るオネエサンたち。アイデアは認める。 #Akihabara L:秋葉原 [mb]
11:52 PAR::Environment の Pod 読むと PAR_GLOBAL_* 環境変数の説明が書いてあるんだけれど、ソースコード見ても全然使ってないんだよなあ。 *P3
12:27 HDD もう1台買った。デジカメデータ用。 [mb]
12:40 マクドナルドの最近のコールドカップのフタ、まんなかがオデキみたいでちょっと抵抗がある。 *P3
17:38 jQuery + Flexigrid を HTML 出力に追加。 *P3
19:45 えーっ、チューペット生産終了になってたのか。 [mb]
19:49 あれ? チューペットって真ん中で折れるやつだっけ? 折れないやつだっけ? [mb]
19:59 西友に行ってみたら「チューペットみたいな何か」いっぱいあった。焦るな。 [mb]
20:02 @hitoxu もう食べられないと思うと無性に欲しくなりますね、チューペット。 [mb]
23:30 2009年8月25日の歩行: 8690歩、6.69km、79分、5.03km/h、消費 319.2kcal、脂肪燃焼 45.6g、4.1エクササイズ。 *P3
23:32 2009年8月26日の歩行: 855歩、0.63km、9分、4.05km/h、消費 32.8kcal、脂肪燃焼 4.7g、0.4エクササイズ。 *P3
23:34 2009年8月27日の歩行: 7853歩、6.29km、58分、6.49km/h、消費 286.6kcal、脂肪燃焼 40.9g、4.2エクササイズ。 *P3

2009年08月28日

09:24 スターバックスに寄って TO GO したいと起床してから思っているのだが、タンブラー会社にあるんだよなあ。 [mb]
09:43 やっぱり TO GOo した。会社に着いたら入れ替える。 L:秋葉原 [mb]
12:14 この間配っていたやつ、ラブプラスのだったのか。 *P3
12:59 明日8月29日から明後日8月30日の2日間、大井町で第2回大井フェスタ & 第55回大井どんたく開催。 #Oimachi *P3
15:00 Firefox に HTML Validator 入れた。 *P3
15:05 Flexigrid 化したページ Internet Explorer 7 でみたらヘッダがずれてる。 *P3
15:14 Flexigrid + Internet Explorer 7 のずれは DOCTYPE を XHTML 1.0 Strict にしたら直った。ふう。 *P3
15:46 XHTML 1.0 Transitional に変更 (Flexigrid のヘッダ行がずれないように th に width を指定するから)。 *P3
16:46 スターバックスのアニバーサリータンブラー 12oz ちょっと欲しい。 *P3
19:01 ルイーダの酒場を見たいというので案内した。 L:秋葉原 [mb]
19:23 大井フェスタ & 大井どんたくの横断幕でてる。 #Oimachi L:大井町 [mb]
27:19 Net::Twitter が古いので dh-make-perl した。 *P3

[ permalink ]

[ 8月28日全て ]

2010年11月15日 (月)

今日のさえずり: なんで事務系の IT 詳しくない人が Google Chrome 使ってるんだよ

2010年11月15日

07:12 ぼちぼち起床。
07:15 もしかして twicca って戻るボタンで閉じきっちゃうとアプリケーションが終了して定期新着チェックが働かなくなるのかな? #twicca
08:02 何このぶ厚さ! (かなり久しぶりに4枚切り食べてる)
10:55 なんで事務系の IT 詳しくない人が Google Chrome 使ってるんだよ。Internet Explorer を使ってください。
11:04 ブラウザの互換性を理解している人は OK。事務系サイトの Web ブラウザ未対応にはまる人は NG。RT @Naney: なんで事務系の IT 詳しくない人が Google Chrome 使ってるんだよ。Internet Explorer を使ってください。
15:18 なんでうちのオフィスは「重複」を「じゅうふく」と呼ぶ人が多数派なの? やめて伝染る。
18:00 perlbrew install perl-<version> --as myproject-perl すると --as の名前の入ったディレクトリ名で -Dprefix されるのね。同じ Perl バージョンで別々の Perl を入れられることを確認。
19:31 Mojolicious::Lite + Mojolicious::Plugin::Xslate で layout を使った時に、レイアウトテンプレート側では <: $c.content | mark_raw :> で受けとれたけれどこれでいいのかな?
19:33 それと Mojolicious::Lite でのレイアウトテンプレートファイルを置く場所でちょっとはまった。直下の layouts/ ではなくて templates/layouts/ 以下に置かないと駄目だった。
20:56 @__gfx__ ありがとうございます。Mojolicious::Lite の Pod ドキュメント見て最初 Xslate でも <: $content :> で参照できるのかと思ってましたがそうではないんですね。
21:01 @__gfx__ content ヘルパが Mojolicious::Plugin::DefaultHelpers にあるというところまでは辿りついたのですが、どう処理が流れるのかまでは追ってなくて。
22:16 @__gfx__ そうですね。layout にこだわりは無いので Xslate の機能使おうと思います。
22:37 この間車がぶつかって曲がったポールがまた斜めってる。ライトの破片があるし、またぶつけられたな。
23:59 Skype for Android 1.0.0.614 インストールしてみた。PC 上の Skype for Linux と通話できることを確認(Wi-Fi 接続)。ハウリングしたので音質はよくわからん。起動しておくと電池食うのかな? #Xperia

[ permalink ]

[ 11月15日全て ]

2011年6月8日 (水)

require_ok してテスト可能な Perl スクリプトを書く

ちょっとしたものをのぞいて、Perl プログラムはアプリケーション部分も App 的 Perl モジュール(.pm)に入れて、実行するスクリプトファイル (.pl) では use して new して run するだけにしている。

 #!/usr/bin/perl

 use warnings;
 use strict;

 use MyApp; exit MyApp->new->run;

@ARGV の処理は new から呼ばれているプライベートメソッドの中で local @ARGV してから、Getopt::Long::GetOptions あたりで解析処理をしている。

でテストスクリプトではこの MyApp を use_ok して local @ARGV = qw(引数組み合わせパターン...) した後に new を呼んだ結果を検査するようにしていた。

そんなところ今回「.pm の中で @ARGV いじるのやっぱり気持ち悪くない?」っていう意見をもらった。気持ちはわかる。ただ

 MyApp->new(@ARGV)->run;

のように .pl 側で受け取ったものを解析すれば?」いいかというと、直接 @ARGV を使わない Getopt::Long::GetOptionsFromArray は 2.36 からしかなくて、古いバージョンの Getopt::Long でも動くようにすると結局 local @ARGV になってしまうのである。

また「@ARGV の解析は .pm の方には入れたくない」っていう意見もあったので、今回はそれらのコードは .pl 側に追い出すことにした。

そうすると次の課題は .pl にある @ARGV の解析処理のテストはどう書けばいいかなと。.pl ファイルを require したらスクリプトが走っちゃうし。試行錯誤していたらマスタリング Perl で紹介されている caller(0) を使う方法を教えてもらった。

caller(0) で直接実行されたのか、require されたのかで処理を変える

 スクリプトファイル(.pl)

 #!/usr/bin/perl

 package App;
 # スクリプトの実行開始エントリ
 sub main {
   # ここに実行したい処理呼び出しを書く。
 }

 main() unless caller(0);

こうするとこのスクリプトファイルを直接実行した場合は main サブルーチンが実行され、他から require された場合は main は実行されないというようにすることができる。前者の場合は caller(0) は undef を返し、後者は 'main' (あるいその他のパッケージ名)が返されることを利用している。

これでテストファイルの中でこのファイルを require_ok できるようになるので、あとは各サブルーチンのテストを書けばよい。

pod2usage の exit を回避

それから Pod::Usage を使っているんだけれど、テストでは Pod::Usage::pod2usage で exit されてしまうと困るので exit が何もしないようにしておく。テストスクリプトでは以下のようにする。

 BEGIN {
   *CORE::GLOBAL::exit = sub {};
   require_ok('script/myscript.pl');
 }

これで myscript.pl のテスト中に pod2usage が exit を呼んでもスルーさせられる。ただし本番では exit させたい pod2usage がある場合は、その後に制御が流れていっても問題がおきないようにプログラムを書いておく必要があるので注意。

pod2usage の STDERR 出力をチェック

それから pod2usage で期待するメッセージが STDERR に吐かれているかをテストするには STDERR をオープンしなおせばよい。

 {
   my $message;
   local *STDERR;
   open STDERR, '>', \$message or die $!;
   # ここで pod2usage がメッセージを出すことが期待されるテストを実行。
   like($message, qr/expected message/);
 }

以上、スクリプトのテストについての何点かのまとめ。

[ permalink ]

[ 6月8日全て ]

2014年2月28日 (金)

Email::Sender::Transport::SMTP::TLS を使って Perl スクリプトからメール送信

TLS と認証が必要な SMTP サーバ経由でメールを送信する以前書いたスクリプトをちょっと整理した。標準入力からメッセージ本文を受けとって送信できるように機能を切り出し。

メールでコンテンツを投稿できるサービスにメールを投げる時用。

標準入力で受け取った本文を Email::MIME でメールの形式に変換して、Email::Sender::Simple を使って送信。transpot として Email::Sender::Transport::SMTP::TLS を使う。なお、今 Email::Sender::Transport::SMTP::TLS の Pod ドキュメントをみたら今後は Email::Sender::Transport::SMTPS の方がお薦めと書いてあったのでその方が良いのかも。

 #!/usr/bin/perl

 use warnings;
 use strict;
 use utf8;
 use open IN => ':utf8';
 use open ':std';

 use Email::MIME;
 use Email::Sender::Simple qw(sendmail);
 use Email::Sender::Transport::SMTP::TLS;

 eval {

   my $message;
   {
     local $/ = undef;
     $message = <>;
   }

   my $subject = "sendXXX: $message";
   $subject = substr($subject, 0, 32 - 3) . '...' if length($subject) > 32;

   my $new_mail = Email::MIME->create(
     header_str => [
       From    => 'me@example.com',
       To      => 'post@example.com',
       Cc      => 'me@example.com',
       Subject => $subject,
     ],
     attributes => {
       content_type => 'text/plain',
       charset      => 'UTF-8',
       encoding     => '8bit',
     },
     body_str => $message
   );

   sendmail(
     $new_mail,
     {
       from      => 'me@example.com',
       transport => Email::Sender::Transport::SMTP::TLS->new(
         {
           host     => 'smtp@example.com',
           port     => 587,
           username => 'myusername',
           password => 'mypassword'
         }
       )
     }
   );
 };
 if ($@) {
    open my $file, '>>', '/home/me/var/log/sendXXX/error.log' or die $!;
    print $file $@, "\n";
    close $file;
    exit 1;
 }
 exit 0;

[ Perl モジュール ]

[ permalink ]

[ 2月28日全て ]