cpanとperldocの歩き方

この記事は[Perl入学式 Advent Calendar 2016](http://qiita.com/advent-calendar/2016/perl-entrance)の16日目の記事です。

どうも、こんにちは[トーカナイザの守護霊](https://twitter.com/mackee_w)ことマコピーです。Perl入学式には2013年からサポーターとして参加しています。最近はサポーターとしてはあまり出ていませんが、東京の懇親会にただ飲みに来るおっさんとして活躍しています。

## CPANとは

Perlで実用的なアプリケーションを書く上で避けては通れないCPANの話をします。Rubyで言うrubygems、Pythonで言うpypi、Node.jsで言うnpmです。
例えば「なーんか適当なサイトの内容を取ってきたいなー」と思ったときにPerlだと標準でHTTPクライアントが同梱されていないので(追記: と思ったんですが、5.14から`HTTP::Tiny`がコアモジュールに同梱されていました。なので「HTTPとは・・・」みたいにはならないですね)、自分で「HTTPとは・・・・」みたいなところから書き始めないといけません。もう想像しただけでウゲェとなりますね。
昔は「こうやれば出来るよ」みたいなコードをホームページに乗せてそれをダウンロードするなりコピペするなりして人々はURLを叩いていましたが、今ではCPANにそういうみんなが使いそうなプログラムがモジュールという形で置かれていて、CPANクライアントという専用のコマンドを使うことでダウンロードして使えるような場所に配置することで、すぐにやりたいことがやれる世の中が実現しています。

```bash
$ cpanm Furl
...
$ perl -MFurl -E 'my $furl = Furl->new; my $res = $furl->get("http://example.com/"); say $res->content;'
<!doctype html>
<html>
<head>
    <title>Example Domain</title>

    <meta charset="utf-8" />
    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style type="text/css">
    body {
```

...というようなCPANの話というのは以下の記事にPerl5 Advent Calendarのほうで@magnolia_k_さんが書かれていました。。。

[改めて、CPANいいよね！](http://qiita.com/magnolia_k_/items/36d32050a891fca49e76)

というわけで上記に書かれていないことを書いていこうと思います。

## CPANモジュールのドキュメントを読もう！

さてCPANモジュールを落としてきても使い方がわからないと使うことができませんね。そこでドキュメントを読みましょう！
ググる前に一発ドキュメントを読んだほうが「なるほど！？」となるケースがあります。他の方の書かれた記事ではバージョンが違ったり、環境が違ってそのまま動かないケースもあり、原典をたどるのが一番確実だと私は思っています。

やはりそういうときのためにもPerlにはコマンドが用意されており、`perldoc`というコマンドがそれに当たります。

```bash
$ perldoc Furl
Furl(3)               User Contributed Perl Documentation              Furl(3)



NAME
       Furl - Lightning-fast URL fetcher

SYNOPSIS
           use Furl;

           my $furl = Furl->new(
               agent   => 'MyGreatUA/2.0',
               timeout => 10,
           );

           my $res = $furl->get('http://example.com/');
           die $res->status_line unless $res->is_success;
           print $res->content;

           my $res = $furl->post(
               'http://example.com/', # URL
               [...],                 # headers
               [ foo => 'bar' ],      # form data (HashRef/FileHandle are also okay)
           );

           # Accept-Encoding is supported but optional
           $furl = Furl->new(
               headers => [ 'Accept-Encoding' => 'gzip' ],
           );
           my $body = $furl->get('http://example.com/some/compressed');
```

先ほどの記事にも書かれているとおり、CPANモジュールには必ずと行っていいほど`SYNOPSYS`という(簡単な|主な)使い方が掲載されており、これを見るだけで**英語がわからなくてもPerlが分かれば**出来ることがだいたい分かるというスグレモノです。
私はまず一発目は`SYNOPSYS`を見て分からなければしたのドキュメントを見たりコードを読んだりしています。それでも分からなかったらググったり人に聞いたりするという具合です。

しかし上の`perldoc`コマンドは`cpanm`コマンドなどでCPANモジュールをインストールしておかなければ見ることができません。例えば目的にかなうか分からないのにドキュメントを見るためだけに`cpanm`するのはちょっと気が引ける感じがします。

そういうときにcpan.orgやmetacpanを使いましょう。

http://www.cpan.org/
https://metacpan.org/

僕は見た目が好きなのでmetacpanを使っています。

そう言えばググるとcpan.orgのほうが出てくるんですが、

http://search.cpan.org/~syohex/Furl-3.09/lib/Furl.pm

というURLの`cpan.org`という部分を`mcpan.org`に変えます。

http://search.mcpan.org/~syohex/Furl-3.09/lib/Furl.pm

するとmetacpanの方にリダイレクトされます。

@bayashi_net さんが以下のような記事も書いていますので参考にしてみてください。

[CPAN モジュールの使い方を調べる](https://bayashi.net/diary/2014/0721)

## Q: で、どうやってCPANモジュールを探せばいいの

### A: CPANソムリエに聞く。

つまり人に聞くということですね！！！　Perl入学式や各種pmに行くとCPANモジュールに一家言を持ったCPANソムリエがいるはずなので「○○みたいなことやりたいんですけれどそういうのに便利なモジュールありませんか？」と聞いてみてください。

あと上記CPAN モジュールの使い方を調べるという記事にもCPANソムリエになる方法というリンクが貼られているのですがこちらは今参照できないようです。中にはCPANソムリエはこういう基準でCPANモジュールを選んでいるよというのが書かれていたのですが、Internet Archiveとかで読んでみてください。

### A: CPANモジュールガイドを読む

https://www.amazon.co.jp/dp/486267108X

という本があります。2011年と少し古いですが、色褪せない様々なモジュールもあるので読んでみるのも一つの手かと思います。

### A: Task::**っ ていうモジュールを見てみる

CPANには`Task::Kensho`というモジュールがあります。

https://metacpan.org/pod/Task::Kensho

どういうモジュールかというとドキュメントには「このモジュールがおすすめだよ！」というのが列挙されて、cpanmするとおすすめモジュールが依存として入ってくるというシステムになっています。便利ですね。
他にも`Task::**`というモジュールはいろいろあり、例えば各個人のおすすめモジュールみたいなのもあります。

https://metacpan.org/pod/Task::BeLike::SONGMU

@songmu さんおすすめモジュールのモジュールです。

これ以外にもそういえば一昨年ぐらいの*-awesomeブームでわたしが作って今はHachioji.pmで管理していただいている https://github.com/hachiojipm/awesome-perl というのもあります。

## perldocコマンドでPerl自体のドキュメントを読む

上記で説明した`perldoc`コマンドは、Perl自体のドキュメントのリーダーでもあります。

```bash
$ perldoc perlop
PERLOP(1)             User Contributed Perl Documentation            PERLOP(1)



NAME
       perlop - Perl operators and precedence
```

`perlop`はPerlにおける演算子(数字を比較する際に使う`==`や`!=`、`>` `<`、代入演算子の`=`、`+=`、`-=`、あと`++`や`--`などについての話も書かれています。
さらに重要なのが演算子間の優先順位です。例えば掛け算`*`や割り算`/`は足し算`+`、引き算`-`よりも先に処理されますが(算数でも同じですね)、この場合`*`と`/`は`+`や`-`よりも優先順位が高いと言えます。そのようなドキュメントが`perlop`には書かれています。

## perldocを日本語で読む

しかし`perldoc`コマンドで出てくるドキュメントは英語でしかも説明的なものが多いですから少しとっつきにくいですよね。そこでなんとperldocの日本語訳というものがインターネットには存在します。便利ですね。

http://perldoc.jp/

有志によって運営されていて、しかも新しい情報も載っていますからPerlの書き方、使い方について知るには良質の情報源であると言えます。
例えば先述の`perlop`はこのページで見られます。

http://perldoc.jp/docs/perl/5.20.1/perlop.pod

みなさんperldoc.jpでperldocを見ていきましょう！

## よく見るperldoc

`perlop`の`op`はオペレータ(演算子)のopですが、知りたい情報がどのドキュメントに書かれているか知るのは難易度が高いですよね。
ちなみに本体のperldocの一覧はここで見られます。

http://perldoc.jp/index/core

日本語で簡単な説明が書かれていますが、私がよく見るドキュメントを挙げてみます。

### perlsyn

http://perldoc.jp/docs/perl/5.20.1/perlsyn.pod

Perlの文法についてです。if文やfor文など言語構造についてのドキュメントが書かれています。最近ですと[Perl 5版のELVMバックエンドを実装する](http://qiita.com/mackee_w/items/5397d6b9215f41c41db1)という記事を書くときに、`goto`とLABELについてここで調べていました。普段gotoなんて使わないからドキュメントを見に行こうとなるわけですね。

### perlre perlretut

http://perldoc.jp/pod/perlre
http://perldoc.jp/pod/perlretut

`perlre`は正規表現のドキュメントです。Perlはチュートリアル向けのドキュメントもあり`perlretut`で順を追って解説されています。

### perlvar

http://perldoc.jp/docs/perl/5.20.1/perlvar.pod

Perlには特殊変数というのがあります。`$_`もその一種で、一文字変数とも呼ばれます。CPANモジュールを読んでいたときに「あれ、この変数ってどういう意味だろう？」というときに`perlvar`で調べます。一文字変数はたいてい記号なのでググれないのでほぼほぼ`perlvar`に頼ることになります。

### perlfunc

http://perldoc.jp/docs/perl/5.20.1/perlfunc.pod

組み込み関数のドキュメントです。配列を操作する際の`push`や`shift`、フィルタするときの`grep`、リストから変換する際の`map`、あと文字列操作関数である`substr`や`join`、`split`なんかもここに書かれています。
時々普段使っている関数が別の役割を持っていたりもするので結構長いこと私はPerlを書いていますが結構見に行ったりします。

## まとめ

- 調べるときはできるだけ公式のドキュメントを読もう！
- 英語は怖くない。例示だけでも結構分かることがある
- perldocにいろんなことが書かれているぞ。読むと結構楽しいぞ [perlstyle](http://perldoc.jp/docs/perl/5.22.1/perlstyle.pod)とか、[perlpolicy](http://perldoc.jp/docs/perl/5.18.0/perlpolicy.pod)とか

次は @mahoyaya さんです。