ぱいぱいにっき

Pythonが好きすぎるけれど、今からPerlを好きになりますにっき

Node.jsのドキュメントを読む 胎動編

ラーメン食べるとお腹が壊れます。どうもマコピーです。

さてNode.jsのアプリを書こうと思うのでココで改めてというか、必要になった時しか読んでいなかったドキュメントをイチから読んでいこうと思います。
そのメモの記録をblogged。

公式ドキュメントはこちら。
Node.js v0.8.16 Manual & Documentation
和訳はこちら Node.js v0.8.16 Manual & Documentation
基本的に英語版を見て分からなかったら和訳を見る感じです。
現在の安定版は0.8.16。

今回はAbout this documentationを読み進めていこうと思います。

About this documentation

単純なAPIリファレンスの解説だけじゃなくてNode.jsの概念的な説明についても言及していくよって書いてあります。
あと、HTML形式のドキュメントの他にもJSONでもドキュメントを取得できるようです。やってみましょう。

$ node
> var httpsync = require('httpsync');
undefined
> var req = httpsync.get({url: 'http://nodejs.org/api/documentation.json'});
undefined
> var res = req.end();
undefined
> var data = JSON.parse(res.data);
undefined
> data
{ source: 'doc/api/documentation.markdown',
  miscs: 
   [ { textRaw: 'About this Documentation',
       name: 'About this Documentation',
       type: 'misc',
       desc: '<p>The goal of this documentation is to comprehensively explain the Node.js\nAPI, both from a reference as well as a conceptual point of view.  Each\nsection describes a built-in module or high-level concept.\n\n</p>\n<p>Where appropriate, property types, method arguments, and the arguments\nprovided to event handlers are detailed in a list underneath the topic\nheading.\n\n</p>\n<p>Every <code>.html</code> document has a corresponding <code>.json</code> document presenting\nthe same information in a structured manner.  This feature is\nexperimental, and added for the benefit of IDEs and other utilities that\nwish to do programmatic things with the documentation.\n\n</p>\n<p>Every <code>.html</code> and <code>.json</code> file is generated based on the corresponding\n<code>.markdown</code> file in the <code>doc/api/</code> folder in node&#39;s source tree.  The\ndocumentation is generated using the <code>tools/doc/generate.js</code> program.\nThe HTML template is located at <code>doc/template.html</code>.\n\n</p>\n',
       miscs: [Object] } ] }

なるほどね。ちなみにこのHTMLやJSONはmarkdownで書かれているので、ブラウザめどいって方はそちらを見るのもありかもしれません。
markdownはWebには無いようなのでjoyent/node · GitHubをcloneしてきて見る感じです。

Stability Index

Node.jsの各ドキュメントの頭にはStability:ウンタラカンタラっていうのが書かれています
f:id:mackee_w:20130105094750p:plain
これが書かれているのがまだ成長過程にあるNode.jsのドキュメントらしいなって思うんですけれど、つまりこれは「以下の項目のAPIは変更する予定がある/安定している/もう変更しないよ」っていう目印のようです。
Stability Indexには以下の種類があります。

  • 0 - 廃止予定
  • 1 - 実験的
  • 2 - 不安定
  • 3 - 安定
  • 4 - 凍結
  • 5 - 固定

仕事のコードで使うなら少なくとも3以上の物をつかいましょう。ざっと見たところModuleだとかAssertion testingなどの基本機能は5(固定)ですが、ChildprocessやBufferといったものは3(安定)だったりします。Cryptoは2(不安定)、Clusterは1(実験的)のようです。

ちなみにNode.js ChangeLogを見るとCryptoは0.8.12で「crypto: Reduce stability index to 2-Unstable (isaacs)」と書かれています。つまりそれまでは3でした。こんなこともあるようです。

試しにPerlワンライナーで適当に集計してみるとこんな感じ。

$ curl 'http://nodejs.org/api/all.json' -s | perl -E 'while(<>) { if ( $_ =~ /.*"stability": ([0-9]).*/) { $st{$1}++ } } use DDP; p %st';
{
    0   1,
    1   3,
    2   8,
    3   16,
    4   4,
    5   4
}

3が最も多い結果となりました。

JSON Output

先ほどのJSONのドキュメントもあるよっていうことがここにも書いてあります。Stability Indexは1、JSONで吐くこと自体も実験的のようですね。



とりまのっそりとこんなかんじで続けていこうと思います。