diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown index 58419663ae51..2ba78e37a3f2 100644 --- a/doc/api/_toc.markdown +++ b/doc/api/_toc.markdown @@ -1,5 +1,7 @@ ## Table of Contents + +* [概要](synopsis.html) +* [グローバル](globals.html) +* [標準入出力](stdio.html) +* [タイマー](timers.html) +* [モジュール](modules.html) +* [C/C++ アドオン](addons.html) +* [プロセス](process.html) +* [ユーティリティ](util.html) +* [イベント](events.html) +* [バッファ](buffers.html) +* [ストリーム](streams.html) +* [暗号化](crypto.html) +* [TLS/SSL](tls.html) +* [文字列デコーダ](string_decoder.html) +* [ファイルシステム](fs.html) +* [パス](path.html) +* [Net](net.html) +* [UDP/データグラム](dgram.html) +* [DNS](dns.html) +* [HTTP](http.html) +* [HTTPS](https.html) +* [URL](url.html) +* [クエリ文字列](querystring.html) +* [Readline](readline.html) +* [REPL](repl.html) +* [VM](vm.html) +* [子プロセス](child_processes.html) +* [表明とテスティング](assert.html) +* [TTY](tty.html) +* [OS](os.html) +* [デバッガ](debugger.html) +* 付録 + * [付録 1: 推奨されるサードパーティ製のモジュール](appendix_1.html) + * [付録 2: 廃止された API](appendix_2.html) + diff --git a/doc/api/addons.markdown b/doc/api/addons.markdown index 5d8edd02d75f..c55a3902c261 100644 --- a/doc/api/addons.markdown +++ b/doc/api/addons.markdown @@ -1,40 +1,103 @@ ## Addons + +アドオンは動的に共有オブジェクトをリンクします。 +それらは、C や C++ のライブラリに接合点を提供します。 +API はいくつかのライブラリの知識が必要で、(現時点では) かなり複雑です。 + + + - V8 JavaScript は C++ のライブラリです。 + JavaScript のオブジェクト作成や関数呼び出し等のインタフェースに使用されます。 + ドキュメントは主に、`v8.h` のヘッダファイル + (Node のソースツリーの中の `deps/v8/include/v8.h`) に記されています。 + + + - libev は C の event loop ライブラリです。 + ファイル記述子が読み取り可能になるのを待つとき、タイマーを待つとき、シグナルを受信するのを待つときはいつでも、 + libv のインタフェースが必要になります。 + つまり、何らかの I/O 処理をすると必ず libev を使う必要があるということです。 + Node は `EV_DEFAULT` というイベントループを使います。 + ドキュメントは、[こちら](http:/cvs.schmorp.de/libev/ev.html) にあります。 + + + - libeio は C のスレッドプールライブラリです。 + ブロックする POSIX システムコールを非同期に実行するために使用されます。 + こういった呼び出しのための大抵のラッパーは、既に `src/file.cc` に用意されているので、 + おそらくこれを使う必要はないでしょう。 + 必要になったら、`deps/libeio/eio.h` のヘッダファイルを参照して下さい。 + + + - Node の内部ライブラリ。 + もっとも重要なのは `node::ObjectWrap` クラスで、 + このクラスから派生させることが多くなるでしょう。 + + + - その他。どのような物が利用できるかは `deps/` 以下を参照してさい。 + + +Node は全ての依存ライブラリを実行ファイルに静的にコンパイルします。 +モジュールのコンパイル時には、それらのリンクについて一切気にする必要は有りません。 + + +では、 C++ で以下の様に動作する小さなアドオンを作成してみましょう。 + exports.hello = 'world'; + +まず `hello.cc` というファイルを作成します: + + #include using namespace v8; @@ -46,10 +109,16 @@ To get started we create a file `hello.cc`: target->Set(String::New("hello"), String::New("world")); } + +このソースコードは、`hello.node` というバイナリアドオンとしてビルドされる必要が有ります。 +そのために `wscript` と呼ばれる以下のようなコードを Python で書きました: + srcdir = '.' blddir = 'build' VERSION = '0.0.1' @@ -66,15 +135,37 @@ like this: obj.target = 'hello' obj.source = 'hello.cc' + +`node-waf configure build` を実行すると、`build/default/hello.node` が作成されます。これが作成したアドオンです。 + + +`node-waf` 単に [WAF](http://code.google.com/p/waf) は Python ベースのビルドシステムです。 +`node-waf` は、ユーザの負担を減らすために提供されています。 + + +全ての Node アドオンは次のシグネチャを持つ `init` という関数をエクスポートする必要が有ります: + extern 'C' void init (Handle target) + +現時点では、アドオンのドキュメントはこれで全てです。 +実際の例は、 を参照してください。 diff --git a/doc/api/appendix_1.markdown b/doc/api/appendix_1.markdown index c035466fd1c0..ea7cccdb18e0 100644 --- a/doc/api/appendix_1.markdown +++ b/doc/api/appendix_1.markdown @@ -1,14 +1,28 @@ ## Appendix 1 - Third Party Modules + +Node 向けにサードパーティ製のモジュールが数多くあります。 +執筆時点 (2010 年 8 月) では、モジュールのマスタリポジトリは +[wiki ページ](http://github.com/ry/node/wiki/modules) です。 + + +この付録は、良質だと考えられているモジュールを初心者が素早く見つけることを手助けする「小さな」ガイドを意図しています。 +これは完全なリストは意図していません。 +どこかでより完全なモジュールが見つかるかもしれません。 + - Module Installer: [npm](http://github.com/isaacs/npm) - HTTP Middleware: [Connect](http://github.com/senchalabs/connect) @@ -41,4 +55,9 @@ elsewhere. [expresso](http://github.com/visionmedia/expresso), [mjsunit.runner](http://github.com/tmpvar/mjsunit.runner) + +このリストへのパッチを歓迎します。 diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown index abced9d5de3b..036c8d072b9e 100644 --- a/doc/api/assert.markdown +++ b/doc/api/assert.markdown @@ -1,47 +1,106 @@ ## Assert + +このモジュールはアプリケーションの単体テストを記述するために使用され、 +`require('assert')` でアクセスできます。 + ### assert.fail(actual, expected, message, operator) + +`actual` と `expected` を `operator` で区切ったメッセージを持つ例外を +スローします。 + ### assert.ok(value, [message]) + +`value` が `true` かテストします、 +これは `assert.equal(true, value, message);` と等価です。 + ### assert.equal(actual, expected, [message]) + +`==` 演算子を強制して浅い同値性をテストします。 + ### assert.notEqual(actual, expected, [message]) + +`==` 演算子を強制して浅い非同値性をテストします。 + ### assert.deepEqual(actual, expected, [message]) + +深い同値性をテストします。 + ### assert.notDeepEqual(actual, expected, [message]) + +深い非同値性をテストします。 + ### assert.strictEqual(actual, expected, [message]) + +`===` 演算子で厳密な同値性をテストします。 + ### assert.notStrictEqual(actual, expected, [message]) + +`!==` 演算子で厳密な非同値性をテストします。 + ### assert.throws(block, [error], [message]) + +`block` がエラーをスローすることを期待します。 +`error` はコンストラクタ、正規表現、または検証関数にすることができます。 + + +コンストラクタを使って instanceof で検証: + assert.throws( function() { throw new Error("Wrong value"); @@ -49,8 +108,13 @@ Validate instanceof using constructor: Error ); + +正規表現を使ってエラーメッセージを検証: + assert.throws( function() { throw new Error("Wrong value"); @@ -58,8 +122,13 @@ Validate error message using RegExp: /value/ ); + +独自のエラー検証: + assert.throws( function() { throw new Error("Wrong value"); @@ -74,9 +143,21 @@ Custom error validation: ### assert.doesNotThrow(block, [error], [message]) + +`block` がエラーをスローしないことを期待します。 +詳細は assert.throws を参照してください。 + ### assert.ifError(value) + +`value` が false でないことをテストし、true だったらそれをスローします。 +コールバックの第 1 引数である `error` をテストするのに便利です。 diff --git a/doc/api/buffers.markdown b/doc/api/buffers.markdown old mode 100644 new mode 100755 index ae24855fb60d..a5853defece3 --- a/doc/api/buffers.markdown +++ b/doc/api/buffers.markdown @@ -1,19 +1,47 @@ ## Buffers + +純粋な JavaScript は Unicode と相性がいいものの、バイナリデータの扱いはうまくありません。 +TCP ストリームやファイルシステムを扱う場合は、オクテットストリームを処理する必要があります。 +Node にはオクテットストリームを操作、作成、消費するためにいくつかの戦略があります。 + + +生のデータは `Buffer` クラスのインスタンスに保存されます。 +`Buffer` は整数の配列と似ていますが、 +V8 ヒープの外部に割り当てられた生のメモリに対応します。 +`Buffer` のサイズを変更することはできません。 + + +`Buffer` オブジェクトはグローバルです。 + + +バッファを JavaScript 文字列オブジェクトとの間で変換するにはエンコーディング方式を明示する必要があります。 +いくつかのエンコーディング方式があります。 + + +* `'ascii'` - 7bit の ASCII データ専用です。 + このエンコーディング方式はとても高速で、もし上位ビットがセットされていれば取り除かれます。 +このエンコーディングは、null 文字 (`'\0'` または `'\u0000'`) を `0x20` +(スペースの文字コード) に変換することに注意してください。 +null 文字を 0x00 に変換したい場合は `'utf8'` を使用してください。 +* `'utf8'` - 可変長のバイト単位でエンコードされたUnicode文字。 + 多くのWebページやその他のドキュメントは UTF-8 を使っています。 +* `'ucs2'` - 固定長の2バイト（リトルエンディアン）でエンコードされたUnicode文字。 + BMP (基本多言語面、U+0000～U+FFFF) のみエンコードすることができます。 +* `'base64'` - Base64 文字列エンコーディング. +* `'binary'` - 生のバイナリデータを各文字の最初の 8bit として使用するエンコーディング方式。 +このエンコーディング方式はもはや価値がなく、`Buffer` オブジェクトでは可能な限り使用すべきではありません。 +このエンコーディングは、Node の将来のバージョンで削除される予定です。 +* `'hex'` - 各バイトを 2 桁の16進数文字列でエンコードします。 ### new Buffer(size) + +`size` オクテットの新しいバッファを割り当てます。 + ### new Buffer(array) + +オクテットの `array` を使用する新しいバッファを割り当てます。 + ### new Buffer(str, encoding='utf8') + +与えられた `str` を内容とする新しいバッファを割り当てます。 + ### buffer.write(string, offset=0, encoding='utf8') + +与えられたエンコーディングを使用して、`string` をバッファの `offset` から書き込みます。 +書き込まれたオクテット数を返します。 +もし `buffer` が文字列全体を挿入するのに十分なスペースを含んでいなければ、文字列の一部だけを書き込みます。 +このメソッドは文字の一部だけを書き込むことはありません。 + + +例: utf8 の文字列をバッファに書き込み、それをプリントします + buf = new Buffer(256); len = buf.write('\u00bd + \u00bc = \u00be', 0); console.log(len + " bytes: " + buf.toString('utf8', 0, len)); + +書き込まれた文字数 (書き込まれたバイト数とは異なる場合があります) は、 +次に `buf.write()` が呼び出されて上書きされるまで +`Buffer._charsWritten` に設定されています。 ### buffer.toString(encoding, start=0, end=buffer.length) + +`encoding` でエンコードされたバッファデータの `start` から +`end` までをデコードした文字列を返します。 + + +上の `buffer.write()` の例を参照してください。 + ### buffer[index] + +`index` の位置のオクテットを取得および設定します。 +その値は個々のバイトを参照するので、妥当な範囲は 16 進の `0x00` から `0xFF` +または `0` から`255`までの間です。 + + +例: ASCII 文字列を 1 バイトずつバッファにコピーします + str = "node.js"; buf = new Buffer(str.length); @@ -97,12 +197,23 @@ Tests if `obj` is a `Buffer`. ### Buffer.byteLength(string, encoding='utf8') + +文字列の実際のバイト数を返します。 +これは文字列の*文字*数を返す `String.prototype.length` と同じではありません。 + + +例: + str = '\u00bd + \u00bc = \u00be'; console.log(str + ": " + str.length + " characters, " + @@ -113,10 +224,17 @@ Example: ### buffer.length + +バイト数によるバッファのサイズ。 +これは実際の内容のサイズではないことに注意してください。 +`length` はバッファオブジェクトに割り当てられたメモリ全体を参照します。 + buf = new Buffer(1234); console.log(buf.length); @@ -128,11 +246,22 @@ buffer object. It does not change when the contents of the buffer are changed. ### buffer.copy(targetBuffer, targetStart=0, sourceStart=0, sourceEnd=buffer.length) + +バッファ間で memcpy() をします。 + + +例: バッファを2個作成し、`buf1` の 16 バイト目から 19 バイト目を、 +`buf2` の 8 バイト目から始まる位置へコピーします。 + buf1 = new Buffer(26); buf2 = new Buffer(26); @@ -149,15 +278,31 @@ into `buf2`, starting at the 8th byte in `buf2`. ### buffer.slice(start, end=buffer.length) + +元のバッファと同じメモリを参照しますが、`start` と `end` +で示されるオフセットで始まり短くされた新しいバッファを返します。 + + +**新しいバッファスライスの変更は、オリジナルバッファのメモリを変更することになります！** + + +例: ASCII のアルファベットでバッファを構築してスライスし、元のバッファで 1 バイトを変更します。 + var buf1 = new Buffer(26); for (var i = 0 ; i < 26 ; i++) { @@ -174,11 +319,19 @@ from the original Buffer. ### buffer.readUInt8(offset, endian) + +バッファの指定された位置を符号無し 8bit 整数として読み込みます。 +エンディアンは `'big'` か `'little'` のどちらかでなくてはならず、 +バッファからバイト列を読み出すバイトオーダーを指定します。 + +例: var buf = new Buffer(4); @@ -203,11 +356,19 @@ Example: ### buffer.readUInt16(offset, endian) + +バッファの指定された位置を符号無し 16bit 整数として読み込みます。 +エンディアンは `'big'` か `'little'` のどちらかでなくてはならず、 +バッファからバイト列を読み出すバイトオーダーを指定します。 + +例: var buf = new Buffer(4); @@ -232,11 +393,19 @@ Example: ### buffer.readUInt32(offset, endian) + +バッファの指定された位置を符号無し 32bit 整数として読み込みます。 +エンディアンは `'big'` か `'little'` のどちらかでなくてはならず、 +バッファからバイト列を読み出すバイトオーダーを指定します。 + +例: var buf = new Buffer(4); @@ -253,38 +422,72 @@ Example: ### buffer.readInt8(offset, endian) + +バッファの指定された位置を符号付き 8bit 整数として読み込みます。 +エンディアンは `'big'` か `'little'` のどちらかでなくてはならず、 +バッファからバイト列を読み出すバイトオーダーを指定します。 + +バッファの内容を 2 の補数による符号付き値として扱うこと以外は +`buffer.readUInt8` と同じように動作します。 ### buffer.readInt16(offset, endian) + +バッファの指定された位置を符号付き 16bit 整数として読み込みます。 +エンディアンは `'big'` か `'little'` のどちらかでなくてはならず、 +バッファからバイト列を読み出すバイトオーダーを指定します。 + +バッファの内容を 2 の補数による符号付き値として扱うこと以外は +`buffer.readUInt16` と同じように動作します。 + ### buffer.readInt32(offset, endian) + +バッファの指定された位置を符号付き 32bit 整数として読み込みます。 +エンディアンは `'big'` か `'little'` のどちらかでなくてはならず、 +バッファからバイト列を読み出すバイトオーダーを指定します。 + +バッファの内容を 2 の補数による符号付き値として扱うこと以外は +`buffer.readUInt32` と同じように動作します。 + ### buffer.readFloat(offset, endian) + +バッファの指定された位置を 32bit 浮動小数点数として読み込みます。 +エンディアンは `'big'` か `'little'` のどちらかでなくてはならず、 +バッファからバイト列を読み出すバイトオーダーを指定します。 + +例: var buf = new Buffer(4); @@ -299,11 +502,19 @@ Example: ### buffer.readDouble(offset, endian) + +バッファの指定された位置を 64bit 倍精度浮動小数点数として読み込みます。 +エンディアンは `'big'` か `'little'` のどちらかでなくてはならず、 +バッファからバイト列を読み出すバイトオーダーを指定します。 + +例: var buf = new Buffer(8); @@ -322,10 +533,18 @@ Example: ### buffer.writeUInt8(value, offset, endian) + +`value` を符号無し 8bit 整数としてバッファの指定された位置に、 +指定されたエンディアンで書き込みます。 +`value` は妥当な 8bit 符号無し整数でなければならないことに注意してください。 + +例: var buf = new Buffer(4); buf.writeUInt8(0x3, 0, 'big'); @@ -347,10 +566,18 @@ Example: ### buffer.writeUInt16(value, offset, endian) + +`value` を符号無し 16bit 整数としてバッファの指定された位置に、 +指定されたエンディアンで書き込みます。 +`value` は妥当な 16bit 符号無し整数でなければならないことに注意してください。 + +例: var buf = new Buffer(4); buf.writeUInt16(0xdead, 0, 'big'); @@ -368,10 +595,18 @@ Example: ### buffer.writeUInt32(value, offset, endian) + +`value` を符号無し 32bit 整数としてバッファの指定された位置に、 +指定されたエンディアンで書き込みます。 +`value` は妥当な 32bit 符号無し整数でなければならないことに注意してください。 + +例: var buf = new Buffer(4); buf.writeUInt32(0xfeedface, 0, 'big'); @@ -387,34 +622,65 @@ Example: ### buffer.writeInt8(value, offset, endian) + +`value` を符号付き 8bit 整数としてバッファの指定された位置に、 +指定されたエンディアンで書き込みます。 +`value` は妥当な 8bit 符号付き整数でなければならないことに注意してください。 + +`value` を 2 の補数による符号付き値として書き込むこと以外は +`buffer.writeUInt8` と同じように動作します。 ### buffer.writeInt16(value, offset, endian) + +`value` を符号付き 16bit 整数としてバッファの指定された位置に、 +指定されたエンディアンで書き込みます。 +`value` は妥当な 16bit 符号付き整数でなければならないことに注意してください。 + +`value` を 2 の補数による符号付き値として書き込むこと以外は +`buffer.writeUInt16` と同じように動作します。 ### buffer.writeInt32(value, offset, endian) + +`value` を符号付き 32bit 整数としてバッファの指定された位置に、 +指定されたエンディアンで書き込みます。 +`value` は妥当な 32bit 符号付き整数でなければならないことに注意してください。 + +`value` を 2 の補数による符号付き値として書き込むこと以外は +`buffer.writeUInt32` と同じように動作します。 ### buffer.writeFloat(value, offset, endian) + +`value` を 32bit 浮動小数点数としてバッファの指定された位置に、 +指定されたエンディアンで書き込みます。 +`value` は妥当な 32bit 浮動小数点数でなければならないことに注意してください。 + var buf = new Buffer(4); buf.writeFloat(0xcafebabe, 0, 'big'); @@ -430,10 +696,18 @@ Example: ### buffer.writeDouble(value, offset, endian) + +`value` を 64bit 倍精度浮動小数点数としてバッファの指定された位置に、 +指定されたエンディアンで書き込みます。 +`value` は妥当な 64bit 倍精度浮動小数点数でなければならないことに注意してください。 + +例: var buf = new Buffer(8); buf.writeFloat(0xdeadbeefcafebabe, 0, 'big'); @@ -450,8 +724,12 @@ Example: ### buffer.fill(value, offset=0, length=-1) + +指定された値でバッファを埋めます。 +オフセットと長さが与えられなかった場合はバッファ全体を埋めます。 var b = new Buffer(50); b.fill("h"); diff --git a/doc/api/child_processes.markdown b/doc/api/child_processes.markdown index a8cc8780eec4..61d54b6875c2 100644 --- a/doc/api/child_processes.markdown +++ b/doc/api/child_processes.markdown @@ -1,48 +1,115 @@ ## Child Processes + +Nodeは `ChildProcess` クラスを通じて 3 方向の `popen(3)` 機能を提供します。 + + +それは完全にノンブロッキングな方法で子プロセスの `stdin`、`stdout`、 +そして `stderr` を通じたデータストリームを実現します。 + + +子プロセスの生成は `require('child_process').spawn()` を使います。 + + +子プロセスは常に 3 本のストリームと関連づけられています。 +`child.stdin`、`child.stdout`、そして `child.stderr` です。 + + +`ChildProcess` は `EventEmitter` です。 + ### Event: 'exit' `function (code, signal) {}` + +このイベントは子プロセスが終了した後で生成されます。 +プロセスが普通に終了した場合、`code` はプロセスの終了コードです。 +それ以外の場合は `null` です。 +プロセスがシグナルを受け取って終了した場合、`signal` は文字列によるシグナルの名前です。 +それ以外の場合は `null` です。 + + +`waitpid(2)` を参照してください。 + ### child.stdin + +子プロセスの `stdin` を表現する `Writable Stream` です。 +多くの場合、`end()` を通じてこのストリームを閉じると子プロセスが終了する原因となります。 + ### child.stdout + +子プロセスの `stdout` を表現する `Readable Stream` です。 + ### child.stderr + +子プロセスの `stderr` を表現する `Readable Stream` です。 + ### child.pid + +子プロセスの PID です。 + + +例: + var spawn = require('child_process').spawn, grep = spawn('grep', ['ssh']); @@ -52,25 +119,50 @@ Example: ### child_process.spawn(command, args=[], [options]) + +`args` をコマンドライン引数として、与えられた `command` で新しいプロセスを起動します。 +`args` が省略された場合、空の配列がデフォルトとなります。 + + +第 3 引数は追加のオプションを指定するために使われ、そのデフォルトは: + { cwd: undefined, env: process.env, customFds: [-1, -1, -1], setsid: false } + +`cwd` で起動されたプロセスのワーキングディレクトリを指定することができます。 +`env` は新しいプロセスに見える環境変数を指定するために使います。 +`customFds` は新しいプロセスの [stdin, stdout, stderr] を既存のストリームに接続することを可能にします; +`-1` は新しいストリームが作られなければならないことを意味します。 +`setsid` に true が設定されると、サブプロセスは新しいセッションで実行されます。 + + +`ls -lh /usr` を実行して `stdout`、`stderr`、および終了コードを取得する例: + var util = require('util'), spawn = require('child_process').spawn, ls = spawn('ls', ['-lh', '/usr']); @@ -88,8 +180,13 @@ Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the exit cod }); + +とても手の込んだ方法で実行する 'ps ax | grep ssh' の例: + var util = require('util'), spawn = require('child_process').spawn, ps = spawn('ps', ['ax']), @@ -125,8 +222,13 @@ Example: A very elaborate way to run 'ps ax | grep ssh' }); + +exec の失敗をチェックする例: + var spawn = require('child_process').spawn, child = spawn('bad_command'); @@ -138,13 +240,23 @@ Example of checking for failed exec: }); + +関連項目: `child_process.exec()` + ### child_process.exec(command, [options], callback) + +コマンドを子プロセスとして実行し、その出力を蓄えて、その全てをコールバックに渡す高水準の方法です。 + var util = require('util'), exec = require('child_process').exec, child; @@ -158,13 +270,28 @@ output, and return it all in a callback. } }); + +コールバックは引数 `(error, stdout, stderr)` を得ます。 +成功すると、`error` は `null` になります。 +エラーだと、`error` は `Error` のインスタンスとなり、 +`err.code` は子プロセスの終了コード、 +`err.signal` はプロセスを終了させたシグナルとなります。 + + +任意の第 2 引数でいくつかのオプションを指定することができます。 +オプションのデフォルトは + { encoding: 'utf8', timeout: 0, maxBuffer: 200*1024, @@ -172,23 +299,45 @@ There is a second optional argument to specify several options. The default opti cwd: null, env: null } + +もし `timeout` が 0 より大きいと、 +子プロセスは実行時間が `timeout` ミリ秒よりも長くなると kill されます。 +子プロセスは `killSignal` で kill されます (デフォルト: `'SIGTERM'`)。 +`maxBuffer` は標準出力と標準エラーの最大のデータ量を指定します － この値を超えると子プロセスは kill されます。 + ### child_process.fork(modulePath, arguments, options) + +これは `spawn()` の特別版で、Node プロセスを起動します。 +返されるオブジェクトは通常の ChildProcess の全てのメソッドに加えて、 +組み込みの通信チャネルを持ちます。 +チャネルは `child.send(message)` によって書き込まれ、 +メッセージを受信すると `child` 上で `'message'` イベントが生成されます。 + + +例: + var cp = require('child_process'); var n = cp.fork(__dirname + '/sub.js'); @@ -199,31 +348,63 @@ For example: n.send({ hello: 'world' }); + +そして子スクリプトの `'sub.js'` は次のようになります: + process.on('message', function(m) { console.log('CHILD got message:', m); }); process.send({ foo: 'bar' }); + +子供の `process` オブジェクトは `send()` メソッドを持ち、 +`process` はチャネルでメッセージを受信するたびにイベントを生成します。 + + +デフォルトでは，起動された Node プロセスは親プロセスに関連づけられた標準入力、 +標準出力、標準エラー出力を持ちます。 +これは `customFds` オプションによって上書きすることが出来ます。 + + +これらの子 Node は、やはり V8 の新しいインスタンスです。 +新しい Node ごとに少なくとも 30 ミリ秒の起動時間と +10MB のメモリを前提としてください。 +つまり、数千の子プロセスを作ることは出来ません。 ### child.kill(signal='SIGTERM') + +子プロセスにシグナルを送ります。 +引数が与えられない場合、子プロセスには `'SIGTERM'` が送られます。 +利用可能なシグナルの一覧は `signal(7)` を参照してください。 + var spawn = require('child_process').spawn, grep = spawn('grep', ['ssh']); @@ -234,7 +415,14 @@ be sent `'SIGTERM'`. See `signal(7)` for a list of available signals. // send SIGHUP to process grep.kill('SIGHUP'); + +この関数は `kill` と呼ばれるものの、 +子プロセスに届けられるシグナルが実際には子プロセスを殺さないかもしれないことに注意してください。 +`kill` はただプロセスにシグナルを送るだけです。 + See `kill(2)` diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index 19b88c2f8608..f09dd703b469 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -1,36 +1,92 @@ ## Crypto + +このモジュールにアクセスするには `require('crypto')` を使用します。 + + +暗号化モジュールは下層のプラットフォームで OpenSSL が有効であることを必要とします。 +それは安全な HTTPS ネットワークや http コネクションの一部として使われる、 +安全な認証情報をカプセル化する方法を提供します。 + + +同時に OpenSSL のハッシュ、HMAC、暗号、復号、署名、そして検証へのラッパーを一式提供します。 + ### crypto.createCredentials(details) + +認証情報オブジェクトを作成します。オプションの `details` は以下のキーを持つ辞書です: + + +* `key` : PEM でエンコードされた秘密鍵を保持する文字列 +* `cert` : PEM でエンコードされた証明書を保持する文字列 +* `ca` : 信頼できる認証局の証明書が PEM でエンコードされた文字列または文字列の配列 + + +'ca' の詳細が与えられなかった場合、node.js はデフォルトとして + +で与えられる、信頼できる認証局の公開されたリストを使用します。 + ### crypto.createHash(algorithm) + +ハッシュオブジェクトを生成して返します。 +与えられたアルゴリズムによる暗号ハッシュ関数はダイジェストの生成に使われます。 + + +`algorithm` は、プラットフォーム上の OpenSSL +のバージョンでサポートされている利用可能なアルゴリズムに依存します。 +例えば `'sha1'`、`'md5'`、`'sha256'`、`'sha512'`、などです。 +最近のリリースでは、`openssl list-message-digest-algorithms` +で利用可能なダイジェストアルゴリズムが表示されます。 + + +例: このプログラムはファイルのsha1ハッシュ値を求めます。 + var filename = process.argv[2]; var crypto = require('crypto'); var fs = require('fs'); @@ -49,157 +105,339 @@ Example: this program that takes the sha1 sum of a file ### hash.update(data) + +与えられた `data` でハッシュの内容を更新します。 +これは新しいデータがストリームに流される際に何度も呼び出されます。 + ### hash.digest(encoding='binary') + +渡された全てのデータがハッシュ化されたダイジェストを計算します。 +`encoding` は `'hex'`、`'binary'`、または `'base64'` のいずれかです。 + ### crypto.createHmac(algorithm, key) + +与えられたアルゴリズムとキーで HMAC を計算する、HMAC オブジェクトを作成して返します。 + + +`algorithm` は OpenSSL でサポートされているアルゴリズムに依存します － +前述の `createHash` を参照してください。 + ### hmac.update(data) + +与えられた `data` で HMAC の内容を更新します。 +これは新しいデータがストリームに流される際に何度も呼び出されます。 + ### hmac.digest(encoding='binary') + +渡された全てのデータが HMAC 化されたダイジェストを計算します。 +`encoding` は `'hex'`、`'binary'`、または `'base64'` のいずれかです。 + ### crypto.createCipher(algorithm, key) + +与えられたアルゴリズムとキーを使用する暗号オブジェクトを作成して返します。 + + +`algorithm` は、OpenSSL に依存します。例えば `'aes192'` などです。 +最近のリリースでは、`openssl list-cipher-algorithms` +で利用可能な暗号アルゴリズムが表示されます。 + ### cipher.update(data, input_encoding='binary', output_encoding='binary') + +`data` で暗号を更新します。 +`input_encoding` で与えられるエンコーディングは `'utf8'`、`'ascii'`、`'binary'` のいずれかです。 +`output_encoding` は暗号化されたデータの出力フォーマットを指定するもので、 +`'utf8'`、`'ascii'` または `'binary'` のいずれかです。 + + +暗号化されたコンテンツが返されます。これは新しいデータがストリームに流される際に何度も呼び出されます。 + ### cipher.final(output_encoding='binary') + +暗号化されたコンテンツの残りを返します。 +`output_encoding` は次のいずれかです: `'binary'`、`'base64'` または `'hex'` + ### crypto.createDecipher(algorithm, key) + +与えられたアルゴリズムとキーを使用する復号オブジェクトを作成して返します。 +これは前述の暗号オブジェクトの鏡写しです。 + ### decipher.update(data, input_encoding='binary', output_encoding='binary') + +`'binary'`、`'base64'` または `'hex'` のいずれかでエンコードされた復号を `data` で更新します。 +`output_decoding` は復号化されたプレーンテキストのフォーマットを指定するもので、 +`'binary'`、`'ascii'` あるいは `'utf8'` のいずれかです。 + ### decipher.final(output_encoding='binary') + +復号化されたプレーンテキストの残りを返します。 +`output_decoding` は `'binary'`、`'ascii'` あるいは `'utf8'` のいずれかです。 + ### crypto.createSign(algorithm) + +与えられたアルゴリズムで署名オブジェクトを作成して返します。 +最近のOpenSSLのリリースでは、`openssl list-public-key-algorithms` +で利用可能な署名アルゴリズムの一覧が表示されます。例えば 'RSA-SHA256'。 + ### signer.update(data) + +署名オブジェクトをデータで更新します。 +これは新しいデータがストリームに流される際に何度も呼び出されます。 + ### signer.sign(private_key, output_format='binary') + +署名オブジェクトに渡された全ての更新データで署名を計算します。 +`private_key` は PEM でエンコードされた秘密鍵を内容とする文字列です。 + + +`'binary'`、`'hex'`、あるいは `'base64'` のいずれかを指定した `output_format` による署名を返します。 + ### crypto.createVerify(algorithm) + +与えられたアルゴリズムで検証オブジェクトを作成して返します。これは前述の署名オブジェクトと鏡写しです。 + ### verifier.update(data) + +検証オブジェクトをデータで更新します。 +これは新しいデータがストリームに流される際に何度も呼び出されます。 + ### verifier.verify(object, signature, signature_format='binary') + +署名されたデータを `object` と `signature` で検証します。 +`object` は RSA 公開鍵、DSA 公開鍵、X.509証明書のいずれかを +PEM でエンコードしたオブジェクトです。 +`signature` は先に計算したデータの署名で、 +その `signature_format` は `'binary'`、`'hex'`、または `'base64'` のいずれかです。 + + +署名されたデータと公開鍵による検証の結果によって true または false を返します。 + ### crypto.createDiffieHellman(prime_length) + +ディフィー・ヘルマン鍵共有オブジェクトを作成し、 +与えられた長さの素数を生成します。生成元は `2` です。 + ### crypto.createDiffieHellman(prime, encoding='binary') + +与えられた素数からディフィー・ヘルマン鍵共有オブジェクトを作成します。 +生成元は `2` です。 +エンコーディングは `'binary'`、`'hex'`、または `'base64'` のいずれかです。 ### diffieHellman.generateKeys(encoding='binary') + +ディフィー・ヘルマン法で秘密および公開鍵を作成し、 +指定の方法でエンコーディングされた公開鍵を返します。 +この鍵は相手側に渡されるものです。 ### diffieHellman.computeSecret(other_public_key, input_encoding='binary', output_encoding=input_encoding) + +`other_public_key` を相手側の公開鍵として共有の秘密鍵を計算して返します。 +与えられた公開鍵は指定の `input_encoding` を使って解釈され、 +秘密鍵は `output_encoding` で指定された方法でエンコードされます。 +エンコーディングは `'binary'`、`'hex'`、または `'base64'` のいずれかです。 +出力のエンコーディングが与えられなかった場合は、入力のエンコーディングが +出力エンコーディングとして使われます。 ### diffieHellman.getPrime(encoding='binary') + +ディフィー・ヘルマン法の素数を指定のエンコーディングで返します。 +エンコーディングは `'binary'`、`'hex'`、または `'base64'` のいずれかです。 ### diffieHellman.getGenerator(encoding='binary') + +ディフィー・ヘルマン法の生成元を指定のエンコーディングで返します。 +エンコーディングは `'binary'`、`'hex'`、または `'base64'` のいずれかです。 ### diffieHellman.getPublicKey(encoding='binary') + +ディフィー・ヘルマン法による公開鍵を指定のエンコーディングで返します。 +エンコーディングは `'binary'`、`'hex'`、または `'base64'` のいずれかです。 ### diffieHellman.getPrivateKey(encoding='binary') + +ディフィー・ヘルマン法による秘密鍵を指定のエンコーディングで返します。 +エンコーディングは `'binary'`、`'hex'`、または `'base64'` のいずれかです。 ### diffieHellman.setPublicKey(public_key, encoding='binary') + +ディフィー・ヘルマン法による公開鍵を設定します。 +鍵のエンコーディングは `'binary'`、`'hex'`、または `'base64'` のいずれかです。 + ### diffieHellman.setPrivateKey(public_key, encoding='binary') + +ディフィー・ヘルマン法による秘密鍵を設定します。 +鍵のエンコーディングは `'binary'`、`'hex'`、または `'base64'` のいずれかです。 diff --git a/doc/api/debugger.markdown b/doc/api/debugger.markdown index 0bbfeab2164f..8fc7b75a8203 100644 --- a/doc/api/debugger.markdown +++ b/doc/api/debugger.markdown @@ -1,27 +1,47 @@ ## Debugger + +V8は外部プロセスから [TCP プロトコル](http://code.google.com/p/v8/wiki/DebuggerProtocol)経由で接続可能なデバッガを備えています。 +Node にはこのデバッガへのクライアントが組み込まれています。 +これを使うには、 `debug` 引数を指定して Node を起動します。 +次のようになります: % node debug myscript.js debug> + +ポイントは，`myscript.js` はまだ実行されないことです。 +スクリプトを開始するには、`run` コマンドを入力します。 +全てがうまくいけば、出力はこのようになります: % node debug myscript.js debug> run debugger listening on port 5858 connecting...ok + +Node のデバッガクライアントはあらゆるコマンドを完全にサポートしているわけではありませんが、 +単純なステップ実行やインスペクションが可能です。 +スクリプトのソースコードに `debugger;` 文を挿入すると、 +ブレークポイントが有効になります。 + +例えば、`myscript.js` が次のようだとします: // myscript.js x = 5; @@ -31,7 +51,10 @@ For example, suppose `myscript.js` looked like this: }, 1000); console.log("hello"); + +ひとたびデバッガを実行すると、4行目で中断します。 % ./node debug myscript.js debug> run @@ -59,15 +82,23 @@ Then once the debugger is run, it will break on line 4. % + +``print`` コマンドは変数を評価します。 +``next`` コマンドは次の行にステップオーバーします。 +他にもいくつかのコマンドを利用することができます。 +それらについては ``help`` をタイプしてください。 ### Advanced Usage + +V8 デバッガは Node をコマンドラインの `--debug` フラグで起動したり、起動済みの Node プロセスに `SIGUSR1` シグナルを送ることでも有効にできます。 diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index cc2aea20e249..1638e93e6d82 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -1,46 +1,96 @@ ## UDP / Datagram Sockets + +データグラムソケットは `require('dgram')` で利用可能になります。 +データグラムはほとんどの場合 IP/UDP メッセージで扱われますが、UNIX ドメインソケットでも使用することができます。 + ### Event: 'message' `function (msg, rinfo) { }` + +ソケット上で新しいデータグラムが到着した時に生成されます。`msg` は `Buffer` で、 +`rinfo` は送信者のアドレス情報とデータグラムのバイト数を持ったオブジェクトです。 + ### Event: 'listening' `function () { }` + +ソケットでデータグラムの待ち受けを開始すると生成されます。 +これは UDP ソケットが作成されるとすぐに発生します。 +UNIX ドメインソケットでは `bind()` を呼び出すまで待ち受けを開始しません。 + ### Event: 'close' `function () { }` + +`close()` によってソケットがクローズすると生成されます。 +このソケットでは新しい `message` イベントは生成されなくなります。 + ### dgram.createSocket(type, [callback]) + +指定された種類のデータグラムソケットを作成します。 +妥当な種類は: `udp4`、`udp6`、そして`unix_dgram` です。 + + +オプションのコールバックは `message` イベントのリスナーとして加えられます。 + ### dgram.send(buf, offset, length, path, [callback]) + +UNIX ドメインのデータグラムソケット用です。相手先のアドレスはファイルシステムのパス名です。 +オプションのコールバックはOSによって`sendto`の呼び出しが完了した後に起動されるために提供されるかもしれません。 +コールバックが呼び出されるまで `buf` の再利用は安全ではありません。 +`bind()` によってソケットがパスネームにバインドされていない限り、 +このソケットでメッセージを受信することはないことに注意してください。 + + +UNIXドメインソケット `/var/run/syslog` を通じて OSX 上の syslogd にメッセージを送信する例: + var dgram = require('dgram'); var message = new Buffer("A message to log."); var client = dgram.createSocket("unix_dgram"); @@ -54,6 +104,8 @@ Example of sending a message to syslogd on OSX via Unix domain socket `/var/run/ ### dgram.send(buf, offset, length, port, address, [callback]) + +UDP ソケット用です。相手先のポートと IP アドレスは必ず指定しなければなりません。 +`address` パラメータに文字列を提供すると、それは DNS によって解決されます。 +DNS エラーと `buf` が再利用可能になった時のためにオプションのコールバックを指定することができます。 +DNS ルックアップは送信を少なくとも次の機会まで遅らせることに注意してください。 +送信が行われたことを確実に知る唯一の手段はコールバックを使うことです。 + + +`localhost` の適当なポートに UDP パケットを送信する例; + var dgram = require('dgram'); var message = new Buffer("Some bytes"); var client = dgram.createSocket("udp4"); @@ -72,12 +136,25 @@ Example of sending a UDP packet to a random port on `localhost`; ### dgram.bind(path) + +UNIX ドメインのデータグラムソケット用です。 +`path` で指定されたソケット上でデータグラムの着信待ち受けを開始します。 +クライアントは `bind()` しなくても `send()` することができますが、 +`bind()` しないでデータグラムを受信することはありません。 + + +受信した全てのメッセージをエコーバックする UNIX ドメインのデータグラムソケットサーバの例: + var dgram = require("dgram"); var serverPath = "/tmp/dgram_server_sock"; var server = dgram.createSocket("unix_dgram"); @@ -93,8 +170,13 @@ Example of a Unix domain datagram server that echoes back all messages it receiv server.bind(serverPath); + +このサーバと対話する UNIX ドメインのデータグラムクライアントの例: + var dgram = require("dgram"); var serverPath = "/tmp/dgram_server_sock"; var clientPath = "/tmp/dgram_client_sock"; @@ -116,11 +198,22 @@ Example of a Unix domain datagram client that talks to this server: ### dgram.bind(port, [address]) + +UDP ソケット用です。`port` とオプションの `address` でデータグラムを待ち受けます。 +`address` が指定されなければ、OS は全てのアドレスからの待ち受けを試みます。 + + +41234 番ポートを待ち受ける UDP サーバの例: + var dgram = require("dgram"); var server = dgram.createSocket("udp4"); @@ -142,33 +235,68 @@ Example of a UDP server listening on port 41234: ### dgram.close() + +下層のソケットをクローズし、データの待ち受けを終了します。 +`bind()` が呼び出されていない、自動的にメッセージを待ち受けていた UDP ソケットでも同じです。 + ### dgram.address() + +オブジェクトが持っているソケットのアドレス情報を返します。 +UDP ソケットでは、このオブジェクトは `address` と `port` を持っています。 +UNIX ドメインソケットでは、`address` だけを持っています。 + ### dgram.setBroadcast(flag) + +ソケットのオプション `SO_BROADCAST` を設定またはクリアします。 +このオプションが設定されると、UDP パケットはローカルインタフェースのブロードキャスト用アドレスに送信されます。 + ### dgram.setTTL(ttl) + +ソケットオプションの `IP_TTL` を設定します。 +TTL は「生存期間」を表しますが、このコンテキストではパケットが通過を許可される IP のホップ数を指定します。 +各ルータまたはゲートウェイはパケットを送出する際 TTL をデクリメントします。 +ルータによって TTL がデクリメントされて 0 になるとそれは送出されません。 +TTL 値の変更は通常、ネットワークの調査やマルチキャストで使われます。 + + +`setTTL()` の引数は 1 から 255 のホップ数でです。ほとんどのシステムでデフォルトは 64 です。 + ### dgram.setMulticastTTL(ttl) + +`IP_MULTICAST_TTL` ソケットオプションを設定します。 +TTL は「生存期間」を表しますが、この文脈では特にマルチキャストのトラフィックにおいてパケットが通過できるIPホップの数を指定します。 +それぞれのルーターまたはゲートウェイは、パケットを転送する際に TTL をデクリメントします。 +TTL がルーターによって 0 までデクリメントされると、それは転送されません。 +`setMulticastTTL()` の引数はホップを表す数値で、0 から 255 の間です。 +ほとんどのシステムでデフォルトは 64 です。 + ### dgram.setMulticastLoopback(flag) + +`IP_MULTICAST_LOOP` ソケットオプションを設定またはクリアします。 +このオプションが設定されると、マルチキャストのパケットはローカルインタフェースでも受信できるようになります。 + ### dgram.addMembership(multicastAddress, [multicastInterface]) + +`IP_ADD_MEMBERSHIP` ソケットオプションを設定し、マルチキャストグループに参加することをカーネルに伝えます。 + +`multicastInterface` が指定されなかった場合は、全ての妥当なインタフェースをメンバーシップに加えようとします。 + ### dgram.dropMembership(multicastAddress, [multicastInterface]) + +`addMembership` の反対です - `IP_DROP_MEMBERSHIP` ソケットオプションによって、マルチキャストグループから抜けることをカーネルに伝えます。 +これはソケットのクローズ時やプロセスの終了時にカーネルによって自動的に呼び出されるため、ほとんどのアプリケーションはこれを呼び出す必要がありません。 + +`multicastInterface` が指定されなかった場合は、全ての妥当なインタフェースをメンバーシップから削除しようとします。 diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index 9212cc051d38..cfc154e96196 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -1,10 +1,20 @@ ## DNS + +このモジュールにアクセスするには `require('dns')` を使用します。 + + +これは `'www.google.com'` を解決して、返された IP アドレスを逆引きで解決する例です。 + var dns = require('dns'); dns.resolve4('www.google.com', function (err, addresses) { @@ -27,89 +37,210 @@ resolves the IP addresses which are returned. ### dns.lookup(domain, family=null, callback) + +ドメイン (例 `'google.com'`) を解決して最初に見つかった +A (IPv4) または AAAA (IPv6) レコードにします。 + + +コールバックは引数 `(err, address, family)` を持ちます。 +`address` 引数は IP v4 または v6 アドレスを表現する文字列です。 +`family` 引数は 4 または 6 の整数で、`address` のファミリーを意味します +(この値は必ずしも最初に `lookup` に渡す必要はありません)。 + ### dns.resolve(domain, rrtype='A', callback) + +ドメイン (例 `'google.com'`) を解決して `rrtype` で指定されたレコードタイプの配列にします。 +妥当な `rrtype` は `A` (IPV4アドレス)、`AAAA` (IPV6アドレス)、 +`MX` (mail exchangeレコード), `TXT` (テキストレコード)、`SRV` (SRVレコード)、 +`PTR` (IP を逆引きでルックアップするために使われる)、`NS` +(ネームサーバレコード)、そして CNAME (別名レコード) です。 + + +コールバックは引数 `(err, addresses)` を持ちます。 +`addresses` の各要素の種類はレコードの種類によって決まり、 +対応する後述のルックアップメソッドで記述されます。 + + +エラー発生時、`err` は `Error` オブジェクトのインスタンスであり、 +`err.errno` は後述するエラーコードのいずれか、 +`err.message` はエラーを英語で説明する文字列となります。 + ### dns.resolve4(domain, callback) + +`dns.resolve()` と同じですが、IPv4 アドレス (`A` レコード) だけを問い合わせます。 +`addresses` は IPv4 アドレスの配列です (例
+`['74.125.79.104', '74.125.79.105', '74.125.79.106']`) + ### dns.resolve6(domain, callback) + +IPv6 (`AAAA` レコード) を問い合わせることを除いて `dns.resolve4()` と同じです。 + ### dns.resolveMx(domain, callback) + +`dns.resolve()` と同じですが、mail exchange (`MX` レコード) だけを問い合わせます。 + + +`addresses`は MX レコードの配列で、それぞれは priority と exchange の属性を持ちます +(例 `[{'priority': 10, 'exchange': 'mx.example.com'},...]`)。 + ### dns.resolveTxt(domain, callback) + +`dns.resolve()` と同じですが、テキスト (`TXT` レコード) だけを問い合わせます。 +`addresses` は `domain` で利用可能なテキストレコードの配列です。 +(例、`['v=spf1 ip4:0.0.0.0 ~all']`) + ### dns.resolveSrv(domain, callback) + +`dns.resolve()` と同じですが、サービスレコード (`SRV` レコード) だけを問い合わせます。 +`addresses` は `domain` で利用可能な SRV レコードの配列です。 +SRV レコードのプロパティは priority、weight、port、そして name です +(例 `[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]`)。 + ### dns.reverse(ip, callback) + +IP アドレスからドメイン名の配列へ逆引きで解決します。 + + +コールバックは引数 `(err, domains)` を持ちます。 + ### dns.resolveNs(domain, callback) + +`dns.resolve()` と同じですが、ネームサーバレコード (`NS` レコード) +だけを問い合わせます。 +`address` は `domain` で利用可能なネームサーバレコードの配列です +(例 `['ns1.example.com', 'ns2.example.com']`)。 + ### dns.resolveCname(domain, callback) + +`dns.resolve()` と同じですが、別名レコード (`CNAME` レコード) +だけを問い合わせます。 +`address` は `domain` で利用可能な別名レコードの配列です +`domain` (e.g., `['bar.example.com']`)。 + + +エラーがあった場合、`err` は非 null で Error オブジェクトのインスタンスとなります。 + + +どの DNS 問い合わせもエラーコードを返せます。 + + +- `dns.TEMPFAIL`: タイムアウト、SERVFAIL あるいは同様のもの。 +- `dns.PROTOCOL`: 応答が不正。 +- `dns.NXDOMAIN`: ドメインが存在しない。 +- `dns.NODATA`: ドメインは存在するが、要求された種類のデータがない。 +- `dns.NOMEM`: 処理中にメモリが不足。 +- `dns.BADQUERY`: 問い合わせが不正な形式。 diff --git a/doc/api/events.markdown b/doc/api/events.markdown index cf1ec9216b91..ef4cbc478810 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -1,53 +1,109 @@ ## Events + +Node のオブジェクトの多くはイベントを生成します: +`net.Server`は相手から接続するたびにイベントを生成し、 +`fs.readStream`はファイルがオープンされるたびにイベントを生成します。 +イベントを生成する全てのオブジェクトは `events.EventEmitter` のインスタンスです。 +次のようにすることでこのモジュールにアクセスできます: `require("events");` + + +通常、イベント名はキャメル記法による文字列で表現されますが、 +厳格な制限ではなく、どんな文字列でも受け入れられます。 + + +関数をオブジェクトにアタッチすることができ、それはイベントが生成された時に実行されます。 +これらの関数は*リスナー*と呼ばれます。 + ### events.EventEmitter + +EventEmitterクラスにアクセスするには、`require('events').EventEmitter` を使います。 + + +`EventEmitter` のインスタンスがエラーに遭遇した時、 +典型的な動作は `'error'` イベントを生成することです。 +node ではエラーイベントは特別に扱われます． +もしそのリスナーがなければ、デフォルトの動作はスタックトレースを出力してプログラムを終了することです。 + + +全ての EventEmitter は、新しいリスナーが加えられるとイベント `'newListener'` を生成します。 + #### emitter.addListener(event, listener) #### emitter.on(event, listener) + +指定されたイベントに対するリスナー配列の最後にリスナーを追加します。 + server.on('connection', function (stream) { console.log('someone connected!'); }); #### emitter.once(event, listener) + +**一回限り**のリスナーをイベントに追加します。 +このリスナーはイベントが最初に発生した時に限り起動され、その後で削除されます。 + server.once('connection', function (stream) { console.log('Ah, we have our first user!'); }); #### emitter.removeListener(event, listener) + +指定されたイベントに対するリスナー配列からリスナーを削除します。 +**注意**: リスナーの背後にあるリスナー配列のインデックスが変化します。 + var callback = function(stream) { console.log('someone connected!'); }; @@ -58,22 +114,41 @@ Remove a listener from the listener array for the specified event. #### emitter.removeAllListeners([event]) + +全てのリスナーまたは指定されたイベントに対するリスナーを削除します。 + #### emitter.setMaxListeners(n) + +デフォルトでは、EventEmitter は 10 を越えるリスナが追加されると警告を出力します。 +これはメモリリークを見つけるために役に立つデフォルト値です。 +全ての EventEmitter が 10 に制限されなければならないわけではないことは明らかです。 +この関数は制限を増やすことを許可します。 +0 を設定すると無制限になります。 #### emitter.listeners(event) + +指定されたイベントに対するリスナー配列を返します。 +この配列は変更することができます、例えばリスナーを削除するなど。 + server.on('connection', function (stream) { console.log('someone connected!'); }); @@ -81,10 +156,20 @@ manipulated, e.g. to remove listeners. #### emitter.emit(event, [arg1], [arg2], [...]) + +提供された引数の並びでそれぞれのリスナーを実行します。 + #### Event: 'newListener' `function (event, listener) { }` + +このイベントは誰かが新しいリスナーを追加するといつでも生成されます。 diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown old mode 100644 new mode 100755 index 669b61dc5151..a5bff58307bd --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -1,16 +1,36 @@ ## File System + +File I/O は POSIX 標準の関数に対する単純なラッパーとして提供されます。 +このモジュールを使用するには `require('fs')` してください。 +全てのメソッドは非同期と同期の形式があります。 + + +非同期の形式は常に最後の引数として完了コールバックを受け取ります。 +引数として渡される完了コールバックはメソッドに依存しますが、 +最初の引数は常に例外のために予約されています。 +操作が成功で完了すると最初の引数は `null` または `undefined` となります + + +非同期バージョンの例です: + var fs = require('fs'); fs.unlink('/tmp/hello', function (err) { @@ -18,16 +38,27 @@ Here is an example of the asynchronous version: console.log('successfully deleted /tmp/hello'); }); + +同期バージョンです: + var fs = require('fs'); fs.unlinkSync('/tmp/hello') console.log('successfully deleted /tmp/hello'); + +非同期メソッドでは順序の保証はありません。 +以下のような傾向のエラーがあります。 + fs.rename('/tmp/hello', '/tmp/world', function (err) { if (err) throw err; console.log('renamed complete'); @@ -37,9 +68,15 @@ following is prone to error: console.log('stats: ' + JSON.stringify(stats)); }); + +`fs.stat` は `fs.rename` より先に実行される可能性がありrます。 +正しい方法はコールバックをチェーンすることです。 + fs.rename('/tmp/hello', '/tmp/world', function (err) { if (err) throw err; fs.stat('/tmp/world', function (err, stats) { @@ -48,87 +85,178 @@ The correct way to do this is to chain the callbacks. }); }); + +忙しいプロセスでは、プログラマはこれらの非同期バージョンを使うことが*強く推奨*されます。 +同期バージョンはそれが完了するまでプロセス全体をブロックします － 全ての接続を停止します。 + ### fs.rename(path1, path2, [callback]) + +非同期の rename(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.renameSync(path1, path2) + +同期の rename(2)。 + ### fs.truncate(fd, len, [callback]) + +非同期の ftruncate(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.truncateSync(fd, len) + +同期の ftruncate(2)。 + ### fs.chown(path, mode, [callback]) + +非同期の chown(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.chownSync(path, mode) + +同期の chown(2)。 + ### fs.fchown(path, mode, [callback]) + +非同期の fchown(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.fchownSync(path, mode) + +同期の fchown(2)。 + ### fs.lchown(path, mode, [callback]) + +非同期の lchown(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.lchownSync(path, mode) + +同期の lchown(2)。 + ### fs.chmod(path, mode, [callback]) + +非同期の chmod(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.chmodSync(path, mode) + +同期の chmod(2)。 + ### fs.fchmod(fd, mode, [callback]) + +非同期の fchmod(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.fchmodSync(path, mode) + +同期の fchmod(2)。 + ### fs.lchmod(fd, mode, [callback]) + +非同期の lchmod(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.lchmodSync(path, mode) + +同期の lchmod(2)。 + ### fs.stat(path, [callback]) + +非同期の stat(2)。コールバックは 2 つの引数を受け取る `(err, stats)`で、 +`stats` は `fs.Stats` オブジェクトです。次のようになります。 + { dev: 2049, ino: 305352, mode: 16877, @@ -143,118 +271,248 @@ Asynchronous stat(2). The callback gets two arguments `(err, stats)` where mtime: '2009-06-29T11:11:40Z', ctime: '2009-06-29T11:11:40Z' } + +より詳しくは後述の [fs.Stats](#fs.Stats) の節を参照してください。 + ### fs.lstat(path, [callback]) + +非同期の lstat(2)。コールバックは 2 つの引数を受け取る `(err, stats)`で、 +`stats` は `fs.Stats` オブジェクトです。 +`lstat()` はパスがシンボリックリンクだった場合に、 +参照先のファイルではなくそのリンク自身が調べられる点を除いて `stat()` と同じす。 + ### fs.fstat(fd, [callback]) + +非同期の fstat(2)。コールバックは 2 つの引数を受け取る `(err, stats)` で、 +`stats` は `fs.Stats` オブジェクトです。 +状態を取得するファイルをファイル記述子 `fd` で指定することを除いて、 +`fstat()` は `stat()` と同じです。 + ### fs.statSync(path) + +同期の stat(2)。`fs.Stats` のインスタンスを返します。 + ### fs.lstatSync(path) + +同期の lstat(2)。`fs.Stats` のインスタンスを返します。 + ### fs.fstatSync(fd) + +同期の fstat(2)。`fs.Stats` のインスタンスを返します。 + ### fs.link(srcpath, dstpath, [callback]) + +非同期の link(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.linkSync(srcpath, dstpath) + +同期の link(2)。 + ### fs.symlink(linkdata, path, [callback]) + +非同期の symlink(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.symlinkSync(linkdata, path) + +同期の symlink(2)。 + ### fs.readlink(path, [callback]) + +非同期の readlink(2)。コールバックは 2 つの引数を受け取る `(err, resolvedPath)`です。 + ### fs.readlinkSync(path) + +同期の readlink(2)。解決されたパスを返します。 + ### fs.realpath(path, [callback]) + +非同期の realpath(2)。コールバックは 2 つの引数を受け取る `(err, resolvedPath)`です。 + ### fs.realpathSync(path) + +同期の realpath(2)。解決されたパスを返します。 + ### fs.unlink(path, [callback]) + +非同期の unlink(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.unlinkSync(path) + +同期の unlink(2)。 + ### fs.rmdir(path, [callback]) + +非同期の rmdir(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.rmdirSync(path) + +同期の rmdir(2)。 + ### fs.mkdir(path, mode, [callback]) + +非同期の mkdir(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.mkdirSync(path, mode) + +同期の mkdir(2)。 + ### fs.readdir(path, [callback]) + +非同期の readdir(3)。ディレクトリの内容を読み込みます。 +コールバックは 2 つの引数を受け取る `(err, files)`で、 +`files` は `'.'` と `'..'` を除くディレクトリ内のファイル名の配列です。 + ### fs.readdirSync(path) + +同期の readdir(3)。`'.'` と `'..'` を除くディレクトリ内のファイル名の配列を返します。 + ### fs.close(fd, [callback]) + +非同期の close(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.closeSync(fd) + +同期の close(2)。 + ### fs.open(path, flags, [mode], [callback]) + +非同期のファイルオープン。open(2) を参照してください。 +フラグは以下になります: + +* `'r'` - 読み込み専用でオープンします。 +ファイルが存在しない場合は例外が発生します。 + +* `'r+'` - 読み書き両用でオープンします。 +ファイルが存在しない場合は例外が発生します。 + +* `'w'` - 書き込み専用でオープンします。 +ファイルは作成される (存在しない場合) または長さ 0 に切り詰められます +(存在する場合)。 + +* `'r+'` - 読み書き両用でオープンします。 +ファイルは作成される (存在しない場合) または長さ 0 に切り詰められます +(存在する場合)。 + +* `'a'` - 追記用でオープンします。 +ファイルが存在しない場合は作成されます。 + +* `'a+'` - 読み込みおよび追記用でオープンします。 +ファイルが存在しない場合は作成されます。 + +`mode` のデフォルトは 0666 です。 +コールバックは 2 つの引数を受け取る `(err, fd)`です。 + ### fs.openSync(path, flags, [mode]) + +同期の open(2)。 + ### fs.utimes(path, atime, mtime, callback) ### fs.utimesSync(path, atime, mtime) + +ファイルのタイムスタンプを変更します。 + ### fs.futimes(path, atime, mtime, callback) ### fs.futimesSync(path, atime, mtime) + +ファイルのタイムスタンプを変更します。 +パスがシンボリックリンクだった場合、参照先のファイルを辿らない点が異なります。 + ### fs.fsync(fd, callback) + +非同期の fsync(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 + ### fs.fsyncSync(fd) + +同期の fsync(2)。 + ### fs.write(fd, buffer, offset, length, position, [callback]) + +`fd` で指定されたファイルに `buffer` を書き込みます。 + + + + +`position` はデータが書き込まれる位置をファイルの先頭からのオフセットで示します。 +`position` が `null` の場合、データは現在の位置から書き込まれます。 +pwrite(2) を参照してください。 + + +コールバックは 3 つの引数が与えられる `(err, written, buffer)` で、 +`written` は `buffer` から書き込まれた*バイト数*を示します。 + + +同じファイルに対してコールバックされるのを待つことなく `fs.write()` を何度も呼び出すことは、安全ではないことに注意してください。 +このシナリオでは、 `fs.createWriteStream()` を強く推奨します。 + ### fs.writeSync(fd, buffer, offset, length, position) + +同期版のバッファに基づく `fs.write()`。書き込まれたバイト数を返します。 + ### fs.writeSync(fd, str, position, encoding='utf8') + +同期版の文字列に基づく `fs.write()`。書き込まれたバイト数を返します。 + ### fs.read(fd, buffer, offset, length, position, [callback]) + +`fd` で指定されたファイルからデータを読み込みます。 + + +`buffer` はデータが書き込まれるバッファです。 + + +`offset` は書き込みを開始するバッファ内のオフセットです。 + + +`length` は読み込むバイト数を指定する整数です。 + + +`position` はファイルの読み込みを開始する位置を指定する整数です。 +`position` が `null` の場合、データは現在の位置から読み込まれます。 + + +コールバックは3つの引数が与えられる `(err, bytesRead, buffer)` です。 + ### fs.readSync(fd, buffer, offset, length, position) + +同期版のバッファに基づく `fs.read`。`bytesRead` の数を返します。 + ### fs.readSync(fd, length, position, encoding) + +同期版の文字列に基づく `fs.read`。`bytesRead` の数を返します。 + ### fs.readFile(filename, [encoding], [callback]) + +ファイル全体の内容を非同期に読み込みます。例: + fs.readFile('/etc/passwd', function (err, data) { if (err) throw err; console.log(data); }); + +コールバックは 2 つの引数が渡される `(err, data)` で、`data` はファイルの内容です。 + + +エンコーディングが指定されなければ、生のバッファが渡されます。 + ### fs.readFileSync(filename, [encoding]) + +同期版の `fs.readFile`。`filename` の内容を返します。 + + +`encoding` が指定されるとこの関数は文字列を返します。 +そうでなければバッファを返します。 + ### fs.writeFile(filename, data, encoding='utf8', [callback]) + +非同期にデータをファイルに書き込みます。 +ファイルが既に存在する場合は置き換えられます。 +`data` は文字列またはバッファです。 +`data` がバッファの場合、`encoding` は無視されます。 + + +例: + fs.writeFile('message.txt', 'Hello Node', function (err) { if (err) throw err; console.log('It\'s saved!'); @@ -392,39 +823,79 @@ Example: ### fs.writeFileSync(filename, data, encoding='utf8') + +同期版の `fs.writeFile`。 + ### fs.watchFile(filename, [options], listener) + +`filename` の変更を監視します。コールバックの `listener` はファイルがアクセスされる度に呼び出されます。 + + +第 2 引数はオプションです． +`options` が与えられる場合、それは `persistent` とポーリング間隔をミリ秒で表す `interval` の二つの boolean メンバを含むオブジェクトです。 +デフォルトは `{ persistent: true, interval: 0}` です。 + + +`listener` は現在の状態オブジェクトと前の状態オブジェクトの 2 つの引数を受け取ります: + fs.watchFile(f, function (curr, prev) { console.log('the current mtime is: ' + curr.mtime); console.log('the previous mtime was: ' + prev.mtime); }); + +これらの状態オブジェクトは `fs.Stat` のインスタンスです。 + +もしファイルがアクセスされただけでなく、変更された時の通知が必要であれば、`curr.mtime` と `prev.mtime` を比較する必要があります。 ### fs.unwatchFile(filename) + +`filename` の変更に対する監視を終了します。 + ## fs.Stats + +`fs.stat()` と `fs.lstat()` から返されるオブジェクトはこの型です。 + + + - `stats.isFile()` + - `stats.isDirectory()` + - `stats.isBlockDevice()` + - `stats.isCharacterDevice()` + - `stats.isSymbolicLink()` (`fs.lstat()`でのみ有効) + - `stats.isFIFO()` + - `stats.isSocket()` ## fs.ReadStream + +`ReadStream` は `Readable Stream` です。 + ### Event: 'open' `function (fd) { }` + +`fd` は ReadStream に使われているファイル記述子です。 + ### fs.createReadStream(path, [options]) + +新しい ReadStream オブジェクトを返します (`Readable Stream` を参照してください)。 + + +`options` は以下のデフォルト値を持つオブジェクトです: + { flags: 'r', encoding: null, fd: null, @@ -457,36 +956,74 @@ Returns a new ReadStream object (See `Readable Stream`). bufferSize: 64 * 1024 } + +ファイル全体を読み込む代わりに一部の範囲を読み込むため、 +`options` に `start` および `end` を含めることができます。 +`start` と `end` はどちらも包含的で0から始まります。 + + +100 バイトの長さを持つファイルの最後の 10 バイトを読み込む例: + fs.createReadStream('sample.txt', {start: 90, end: 99}); ## fs.WriteStream + +`WriteStream` は `Writable Stream` です。 + ### Event: 'open' `function (fd) { }` + +`fd` は WriteStream に使われているファイル記述子です。 + ### file.bytesWritten + +これまでに書き込まれたバイト数。 +書き込みがキューイングされたままのデータは含まれません。 + ### fs.createWriteStream(path, [options]) + +新しい WriteStream オブジェクトを返します (`Writable Stream` を参照してください)。 + + +`options` は以下のデフォルト値を持つオブジェクトです: + { flags: 'w', encoding: null, mode: 0666 } diff --git a/doc/api/globals.markdown b/doc/api/globals.markdown old mode 100644 new mode 100755 index f5c353b2fb40..9df688d284bf --- a/doc/api/globals.markdown +++ b/doc/api/globals.markdown @@ -1,10 +1,18 @@ ## Global Objects + +これらのオブジェクトは全てのモジュールで有効です。 +これらのオブジェクトのいくつかは実際はグローバルスコープではなくモジュールスコープです - 注意してください。 + ### global + +グローバルなネームスペースのオブジェクトです。 + +ブラウザでは、トップレベルのスコープはグローバルスコープです。 +これは、ブラウザではグローバルスコープで `var something` と定義するとグローバル変数になることを意味します。 +Node では異なります。 +トップレベルのスコープはグローバルスコープではありません; +Node のモジュール内での `var something` はそのモジュールでローカルになります。 + ### process + +プロセスオブジェクトです。[process object](process.html#process) の節を参照してください。 + ### console + +標準出力および標準エラー出力へのプリントに使われます。 +[標準入出力](stdio.html) を参照してください。 ### require() + +require モジュールを指します。[モジュール](modules.html#modules) の節を参照してください。 +`require` は実際はグローバルではなく、各モジュール毎のローカルです。 ### require.resolve() + +`require()` の内部でモジュールの位置を検索するために使われます。 +モジュールのロードは行わず、ファイル名を解決して返すだけです。 + ### require.cache + +モジュールが要求されると、このオブジェクトの中にキャッシュされます。 +このオブジェクトからキーと値を削除すると、次にそのモジュールが +`require` されたときにリロードされます。 ### require.paths + +`require()` のためのサーチパスの配列です。 +この配列はカスタムパスを追加するために変更することができます。 + + +例: サーチリストの先頭に新しいパスを追加する + require.paths.unshift('/usr/local/node'); ### __filename + +実行されているスクリプトのファイル名です。これは絶対パスであり、 +必ずしもコマンドライン引数で渡されたファイル名と同じではありません。 + + +例: `node example.js` を `/Users/mjr` で実行する + console.log(__filename); // /Users/mjr/example.js + +`__filename` は実際はグローバルではなく、各モジュール毎のローカルです。 + ### __dirname + +スクリプトが実行されているディレクトリ名です。 + + +例: `node example.js` を `/Users/mjr` で実行する + console.log(__dirname); // /Users/mjr + +`__dirname` は実際はグローバルではなく、各モジュール毎のローカルです。 + ### module + +現在のモジュールへの参照です。 +特に `module.exports` は `exports` オブジェクトと同じです。 +より詳しくは `src/node.js` を参照してください。 +`module` は実際はグローバルではなく、各モジュール毎のローカルです。 ### exports + + +現在のモジュールの全てのインスタンス間で共有されるオブジェクトで、 +`require` を通じてアクセス可能になります。 +`exports` は `module.exports` と同じオブジェクトです。 +より詳しくは `src/node.js` を参照してください。 +`exports` は実際はグローバルではなく、各モジュール毎のローカルです。 + + ### setTimeout(cb, ms) ### clearTimeout(t) ### setInterval(cb, ms) ### clearInterval(t) + +タイマー関数はグローバル変数です。[タイマー](timers.html) を参照してください。 diff --git a/doc/api/http.markdown b/doc/api/http.markdown old mode 100644 new mode 100755 index 7af538513c0b..59374c21d3a4 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -1,203 +1,447 @@ ## HTTP + +HTTP サーバおよびクライアントを使用するにはいずれも `require('http')` が必要です。 + + +Node の HTTP インタフェースは、 +伝統的に扱いが難しかったプロトコルの多くの機能をサポートするように設計されています。 +とりわけ大きくて、場合によってはチャンク化されたメッセージです。 +インタフェースは決してリクエストまたはレスポンス全体をバッファリングしないように気をつけています +－ 利用者はストリームデータを使うことができます。 + + +HTTP メッセージヘッダはこのようなオブジェクトとして表現されます: + { 'content-length': '123', 'content-type': 'text/plain', 'connection': 'keep-alive', 'accept': '*/*' } + +キーは小文字化されます。値は変更されません。 + + +考えられる HTTP アプリケーションを完全にサポートするために、 +Node の HTTP API はとても低水準です。それはストリームのハンドリングとメッセージの解析だけに対処します。 +解析はメッセージをヘッダとボディに分けますが、実際のヘッダとボディは解析しません。 + ## http.Server + +これは以下のイベントを持つ `EventEmitter` です: + ### Event: 'request' `function (request, response) { }` + +リクエストの度に生成されます。 +コネクションごとに複数のリクエストがあるかもしれないことに注意してください +(Keep Alive なコネクションの場合)。 + + +`request` は `http.ServerRequest` のインスタンス、 +`response` は `http.ServerResponse` のインスタンスです。 + ### Event: 'connection' `function (stream) { }` + +新しい TCP ストリームが確立した時。 +`stream` は `net.Stream` 型のオブジェクトです。 +通常の利用者がこのイベントにアクセスしたくなることはないでしょう。 +`stream` は `request.connection` からアクセスすることもできます。 + ### Event: 'close' `function (errno) { }` + +サーバがクローズした時に生成されます。 + ### Event: 'checkContinue' `function (request, response) { }` + +httpの Expect: 100-continue リクエストを受信する度に生成されます。 +このイベントが監視されない場合、サーバは自動的に 100 Continue を応答します。 + + +このイベントを処理する場合、クライアントがリクエストボディを送信し続けるべきなら +`response.writeContinue` を呼び出す必要があります。 +あるいは、クライアントがリクエストボディを送信し続けるべきでないなら、 +適切な HTTP レスポンス (例えば 400 Bad Request) を生成します。 + + +このイベントが生成されて処理された場合、`request`イベントは生成されないことに注意してください。 + ### Event: 'upgrade' `function (request, socket, head) { }` + +クライアントが HTTP のアップグレードを要求する度に生成されます。 +このイベントが監視されない場合、アップグレードを要求したクライアントのコネクションはクローズされます。 + + +* `request` はリクエストイベントと同様に HTTP リクエストへの引数です。 +* `socket` はサーバとクライアントの間のネットワークソケットです。 +* `head` はアップグレードストリームの最初のパケットを持つ Buffer のインスタンスです。 +空の場合もあります。 + + +このイベントが生成された後、リクエスト元のソケットはもう `data` イベントリスナーを持ちません。 +このソケットでサーバへ送られたデータを扱うためにそれをバインドしなければならないことを意味します。 + ### Event: 'clientError' `function (exception) { }` + +クライアントコネクションが 'error' イベントを発した場合 － ここに転送されます。 + ### http.createServer([requestListener]) + +新しい Web サーバオブジェクトを返します。 + + +`requestListener` は自動的に `'request'` イベントに加えられる関数です。 + ### server.listen(port, [hostname], [callback]) + +指定されたポートとホスト名でコネクションの受け入れを開始します。 +ホスト名が省略されると、サーバはどんな IPv4 アドレスへの接続も受け入れます (`INADDR_ANY`)。 + + +UNIX ドメインソケットを待ち受ける場合、ポートとホスト名ではなくファイル名を提供します。 + + +この関数は非同期です。最後の引数の `callback` はサーバがポートをバインドすると呼び出されます。 + ### server.listen(path, [callback]) + +`path` で与えられたコネクションを待ち受ける UNIX ドメインソケットのサーバを開始します。 + + +この関数は非同期です。最後の引数の `callback` はサーバがバインドすると呼び出されます。 + ### server.close() + +サーバが新しいコネクションを受け付けるのを終了します。 + ## http.ServerRequest + +このオブジェクトは HTTP サーバ内部 － ユーザではなく － で作成され、 +`'request'` リスナーの第1引数として渡されます。 + + +これは以下のイベントを持つ `EventEmitter` です: + ### Event: 'data' `function (chunk) { }` + +メッセージボディの断片を受信した場合に生成されます。 + + +例: 一つの引数としてボディのチャンクが与えられます。 +転送エンコーディングでデコードされます。 +ボディのチャンクは文字列です。 +ボディのエンコーディングは `request.setBodyEncoding()` で設定されます。 + ### Event: 'end' `function () { }` + +リクエストごとに厳密に一回生成されます。 +その後、このリクエストで `'data'` イベントが生成されることはありません。 + ### Event: 'close' `function (err) { }` + +`response.end()` が呼び出されたり、フラッシュされる前に下層の接続が +切断されたことを示します。 + + +`err` パラメータは常に与えられ、クローズの理由を示します。 + + +`err.code === 'timeout'` は下層のコネクションがタイムアウトしたことを示します。 +これは、全ての着信側の接続はデフォルト 2 分でタイムアウトするために発生します。 + + +`err.code === 'aborted'` はクライアントが仮想の接続をいち早く切断したことを +意味します。 + + +`'end'` と同様、このイベントはリクエスト上で一度だけ発生し、その後ではもう +`'data'` イベントが発生することはありません。 + + +注意: `'close'` は `'end'` の後で発生することがあります。 +その逆もあります。 + ### request.method + +リクエストメソッドを表す文字列です。参照のみ可能です。 +例: `'GET'`、`'DELETE'` + ### request.url + +リクエスト URL を表す文字列です。 +これは実際の HTTP リクエストに存在する URL だけを含みます。 +リクエストがこうなら: + GET /status?name=ryan HTTP/1.1\r\n Accept: text/plain\r\n \r\n + +この場合の `request.url` はこうなります: + '/status?name=ryan' + +URL の要素を解析したい場合は、 +`require('url').parse(request.url)` を参照してください。例: + node> require('url').parse('/status?name=ryan') { href: '/status?name=ryan', search: '?name=ryan', query: 'name=ryan', pathname: '/status' } + +問い合わせ文字列からパラメータを取り出したい場合は、 +`require('querystring').parse` 関数を参照するか、 +`require('url').parse` の第 2 引数に `true` を渡してください。例: + node> require('url').parse('/status?name=ryan', true) { href: '/status?name=ryan', search: '?name=ryan', @@ -208,100 +452,214 @@ you can use the `require('querystring').parse` function, or pass ### request.headers + +参照のみ可能です。 + ### request.trailers + +参照のみ可能です; HTTP のトレーラです (もしあれば)。'end' イベントの後にだけ発生します。 + ### request.httpVersion + +HTTP プロトコルのバージョンを表す文字列です。参照のみ可能です。例: +`'1.1'`、`'1.0'`。 +同様に `request.httpVersionMajor` は最初の整数、 +`request.httpVersionMinor` は 2 番目の整数です。 + ### request.setEncoding(encoding=null) + +リクエストボディのエンコーディングを設定します。 +`'utf8'` または `'binary'` のいずれかです。 +デフォルトは `null` で、`'data'` イベントが +`Buffer` を生成することを意味します。 + ### request.pause() + +リクエストによるイベントの生成を中断します。アップロード速度を落とすのに便利です。 + ### request.resume() + +中断されたリクエストを再開します。 + ### request.connection + +コネクションに関連づけられた `net.Stream` オブジェクトです。 + + + +HTTPS では `request.connection.verifyPeer()` と +`request.connection.getPeerCertificate()` で +クライアントの認証の詳細を取得できます。 + ## http.ServerResponse + +このオブジェクトは HTTP サーバ内部 － ユーザではなく － で作成されます。 +`'request'` リスナーの第 2 引数として渡されます。 +これは `Writable Stream` です。 + ### response.writeContinue() + +HTTP/1.1 の 100 Continue メッセージをクライアントに送信し、 +リクエストボディを送信してもよいことを示します。 +`Server`の [checkContinue](#event_checkContinue_) イベントを参照してください。 + ### response.writeHead(statusCode, [reasonPhrase], [headers]) + +レスポンスヘッダを送信します。 +ステータスコードは `404` のような 3 桁の数字による HTTP ステータスコードです。 +最後の引数 `headers` は、レスポンスヘッダです。 +オプションとして人に読める形式の `reasonPhrase` を第 2 引数で与えることができます。 + + +例: + var body = 'hello world'; response.writeHead(200, { 'Content-Length': body.length, 'Content-Type': 'text/plain' }); + +このメソッドはメッセージごとに 1 回だけ呼び出されなくてはならず、 +`response.end()` の前に呼び出されなければなりません。 + +もしこのメソッドが呼び出される前に `response.write()` または `response.end()` が呼ばれると、暗黙的で可変のヘッダが算出されてこの関数が呼び出されます。 + + +注意: `Content-Length` は文字数ではなくバイト数で与えられます。 +上の例が動作するのは `'hello world'` という文字列が単一バイト文字だけを含むためです。 +もしボディがより上位にコード化された文字を含む場合は、 +指定したエンコーディングによるバイト数を得るために `Buffer.byteLength()` を使うべきです。 + ### response.statusCode + +(`response.writeHead()` が明示的に呼ばれないために) 暗黙的なヘッダが使われる場合、このプロパティはヘッダがフラッシュされる時にクライアントへ送信されるステータスコードを制御します。 + + +例: + response.statusCode = 404; ### response.setHeader(name, value) + +暗黙的ヘッダのヘッダ値を設定します。 +送信されようとしているレスポンスヘッダにこのヘッダが既に含まれている場合、 +その値は置き換えられます。 +同じ名前で複数のヘッダを送信したい場合は文字列の配列を使ってください。 + + +例: + response.setHeader("Content-Type", "text/html"); or @@ -311,56 +669,126 @@ or ### response.getHeader(name) + +すでにキューに入れられているが未送信のヘッダを読み上げます． +名前は大文字小文字を区別しないことに注意してください。 +これはヘッダが暗黙的にフラッシュされる前だけ呼び出すことができます。 + + +例: + var contentType = response.getHeader('content-type'); ### response.removeHeader(name) + +暗黙的に送信するためキューに入れられたヘッダを削除します。 + + +例: + response.removeHeader("Content-Encoding"); ### response.write(chunk, encoding='utf8') + +このメソッドが呼び出され、`response.writeHead()` が呼び出されなければ、 +暗黙的ヘッダモードに切り替わり、暗黙的ヘッダはフラッシュされます。 + +これはレスポンスボディのチャンクを送信します。 +このメソッドはボディの連続した部分を提供するために複数回呼び出されるかもしれません。 + + +`chunk` は文字列またはバッファにすることができます。 +`chunk` が文字列の場合、どのエンコードでバイトストリームにするかを第 2 引数で指定します。 +デフォルトの `encoding` は `'utf8'` です。 + + +**注意**: これは生の HTTP ボディで、 +高水準のマルチパートボディエンコーディングで使われるものとは無関係です。 + + +初めて `response.write()` が呼び出されると、 +バッファリングされていたヘッダ情報と最初のボディがクライアントに送信されます。 +2 回目に `response.write()` が呼ばれると、 +Node はストリーミングデータを分割して送信しようとしていると仮定します。 +すなわち、レスポンスはボディの最初のチャンクまでバッファリングされます。 + ### response.addTrailers(headers) + +このメソッドは HTTP トレーラヘッダ (メッセージの最後に置かれるヘッダ) をレスポンスに追加します。 + + +トレーラはレスポンスがチャンク化されたエンコーディングで**のみ**生成されます; +そうでなければ (例えばリクエストが HTTP/1.0)、黙って破棄されます。 + + +HTTP は、トレーラを生成するならそのヘッダフィールドのリストを値として +`Trailer` ヘッダを送信することを要求していることに注意してください。 + response.writeHead(200, { 'Content-Type': 'text/plain', 'Trailer': 'TraceInfo' }); response.write(fileData); @@ -370,22 +798,48 @@ emit trailers, with a list of the header fields in its value. E.g., ### response.end([data], [encoding]) + +このメソッドはレスポンスの全てのヘッダとボディを送信したことをサーバに伝えます; +サーバはメッセージが終了したと考えるべきです。 +この `response.end()` メソッドは各レスポンスごとに呼び出さなければ*なりません*。 + + +`data` が指定された場合、 +`response.write(data, encoding)` に続けて `response.end()` を呼び出すのと等価です。 + ## http.request(options, callback) + +Node は HTTP リクエストを行うために、サーバごとにいくつかのコネクションを保持します。 +この関数はその一つを使って透過的にリクエストを発行できるようにします。 + + +オプション: + + +- `host`: リクエストを発行するサーバのドメイン名または IP アドレス。 +- `port`: リモートサーバのポート。 +- `socketPath`: Unix ドメインソケット (host:port または socketPath のどちらか) +- `method`: HTTP リクエストのメソッドを指定する文字列。 可能な値: + `'GET'` (デフォルト), `'POST'`, `'PUT'`, そして `'DELETE'`。 +- `path`: リクエストのパス。問い合わせ文字列やフラグメントがあるなら含めるべきです。 + 例. `'/index.html?page=12'` +- `headers`: リクエストヘッダを含むオブジェクト。 +- `agent`: `Agent` の振る舞いを制御します。可能な値は: + - `undefined` (デフォルト): ホストとポートからデフォルトの `Agent` +を使用します。 + - `Agent`: オブジェクト: 明示的に渡された `Agent` を使用します。 + - `false`: このホストとポートの新しい `Agent` を新たに作成します。 + `Agent` は再利用されません。 + + +`http.request()` は `http.ClientRequest` クラスのインスタンスを返します。 +`http.ClientRequest` のインスタンスは書き込み可能なストリームです。 +もし POST リクエストでファイルのアップロードがしたければ、 +`http.ClientRequest` オブジェクトに出力してください。 + + +例: + var options = { host: 'www.google.com', port: 80, @@ -430,16 +913,37 @@ Example: req.write('data\n'); req.end(); + +この例で `req.end()` が呼ばれていることに注意してください。 +`http.request()` では、リクエストが終了したことを示すために、 +常に `req.end()` を呼び出さなければなりません +- リクエストのボディに出力するデータがなかったとしても。 + + +リクエスト中に何らかのエラー (DNS 解決、TCP レベルのエラー、HTTP パースエラーなど) が発生すると、戻り値のリクエストオブジェクトで `'error'` イベントが生成されます。 + + + +いくつかの特別なヘッダに注意が必要です。 + + +* 'Connection: keep-alive' の送信は、サーバへのコネクションを次のリクエストまで持続することを Node に通知します。 + +* 'Content-length' ヘッダの送信は、デフォルトのチャンクエンコーディングを無効にします。 + +* 'Expect' ヘッダの送信は、リクエストヘッダを即時に送信します。 + 通常、'Expect: 100-continue' を送信すると、タイムアウトと `continue` イベントを待ち受けます。詳細は RFC2616 の 8.2.3 節を参照してください。 + ## http.get(options, callback) + +ほとんどのリクエストは本文のない GET リクエストであるため、 +Node は便利なメソッドを提供します。 +このメソッドと `http.request()` の間の違いは、メソッドを GET に設定して `req.end()` を自動的に呼び出すことだけです。 + + +例: + var options = { host: 'www.google.com', port: 80, @@ -474,26 +998,56 @@ Example: ## http.Agent ## http.getAgent(options) + +`http.request()` は HTTP サーバへの複数のコネクションを管理する特別な `Agent` を使用します。 +通常 `Agent` インスタンスはユーザコードに出てきませんが、特定の状況ではエージェントの状態をチェックすることが役に立ちます。 +`http.getAgent()` 関数はエージェントへのアクセスを可能にします。 + + +オプション: + + +- `host`: リクエストを発行するサーバのドメイン名または IP アドレス。 +- `port`: リモートサーバのポート。 +- `soocketPath`: Unix ドメインソケット (host:port または socketPath のどちらか) + ### Event: 'upgrade' `function (response, socket, head) { }` + +サーバがアップグレード要求に応答する度に生成されます。 +このイベントが監視されていない場合、クライアントがアップグレードヘッダを受信するとそのコネクションはクローズされます。 + + +`http.getAget` を使ってどのように `upgrade` イベントを監視するかを示す、 +クライアントとサーバのペア: var http = require('http'); var net = require('net'); @@ -540,34 +1094,65 @@ A client server pair that show you how to listen for the `upgrade` event using ` }); }); - ### agent.maxSockets + +デフォルトでは 5 に設定されます。 +エージェントがいくつのソケットを並行にオープンするかを決定します。 + ### agent.sockets + +エージェントが現在使っているソケットの配列です。 +変更しないでください。 + ### agent.queue -A queue of requests waiting to be sent to sockets. + +ソケットへの送信を待機しているリクエストのキューです。 ## http.ClientRequest + +このオブジェクトは HTTP サーバ内部で作成され、`http.request()` から返されます。 +それはヘッダがキューに入れられた _進行中_ のリクエストを表現します。 +ヘッダは `setHeader(name, value)`, `getHeader(name)`, `removeHeader(name)` API によってまだ可変のままです。 +実際にヘッダが送信されるのは、最初のデータチャンクが送信される時またはコネクションがクローズされる時です。 + + +レスポンスを取得するには、`'response'` 用のリスナーをリクエストオブジェクトに加えます。 +`'response'` イベントはレスポンスヘッダを受信するとリクエストオブジェクトによって生成されます。 +`'response'` イベントは `http.ClientResponse` のインスタンスを唯一の引数として実行されます。 + + +`'response'` イベントの間、レスポンスオブジェクトにリスナーを加えることができます; +とりわけ `'data'` イベントのリスナーです。 +`'response'` イベントはレスポンスボディのどの部分を受信するよりも前に呼び出されることに注意してください。 +そのため、ボディの最初の部分の受信と競合することを心配する必要はありません。 +`'response'` イベントの間に `'data'` イベントのリスナーが加えられる限り、 +ボディ全体を受信することができます。 + // Good request.on('response', function (response) { @@ -592,113 +1185,242 @@ event, the entire body will be caught. }, 10); }); + +これは `Writable Stream` です。 + + +これは以下のイベントを持つ `EventEmitter` です。 + ### Event: 'continue' `function () { }` + +通常、リクエストが 'Expect: 100-continue' を含んでいたことにより、 +サーバが '100 Continue' HTTP レスポンスを送信することで生成されます。 +これはクライアントがリクエストボディを送信すべき事を示します。 + ### Event 'response' `function (response) { }` + +このリクエストに対するレスポンスを受信した時に生成されます。 +このイベントは一回だけ生成されます。 +`response` 引数は `http.ClientResponse` のインスタンスです。 + ### request.write(chunk, encoding='utf8') + +ボディのチャンクを送信します。 +このメソッドを何回も呼び出すと、サーバへのリクエストボディをストリーム化できます － +このケースは `['Transfer-Encoding', 'chunked']` ヘッダでリクエストを生成したことを意味します。 + + +`chunk` 引数は整数の配列か文字列になります。 + + +`encoding` 引数はオプションで、`chunk` が文字列の場合だけ適用されます。 + ### request.end([data], [encoding]) + +リクエストの送信を終了します。 +ボディのいくつかの部分がまだ送信されていない場合、それはストリームにフラッシュされます。 +リクエストがチャンク化されている場合、これは終端の `'0\r\n\r\n'` を送信します。 + + +`data` が指定された場合は、 +`request.write(data, encoding)` に続けて `request.end()` を呼び出すのと等価です。 + ### request.abort() + +リクエストをアボートします (v0.3.8 からの新機能) ## http.ClientResponse + +このオブジェクトは `http.request()` によってリクエストと一緒に作成されます。 +これはリクエストオブジェクトの `'response'` イベントに渡されます。 + + +レスポンスは `Readable Stream` インタフェースを実装します。 + ### Event: 'data' `function (chunk) { }` + +メッセージボディの断片を受信した場合に生成されます。 + ### Event: 'end' `function () { }` + +メッセージごとに厳密に一回だけ生成されます。 +このイベントが生成された後、このレスポンスはどんなイベントも生成しません。 + ### Event: 'close' `function (err) { }` + +`'end'` イベントが生成される前に下層の接続が切断されたことを示します。 +[http.ServerRequest](#http.ServerRequest) の `'close'` +イベントにより多くの情報があります。 + ### response.statusCode + +3 桁の数字によるレスポンスのステータスコードです。例えば `404`。 + ### response.httpVersion + +接続しているサーバとの HTTP のバージョンです。 +おそらく `'1.1'` または `'1.0'` のどちらかです。 +同様に `response.httpVersionMajor` は最初の整数、 +`response.httpVersionMinor` は 2 番目の整数です。 + ### response.headers + +レスポンスヘッダオブジェクトです。 + ### response.trailers + +レスポンスのトレーラオブジェクトです。 +'end' イベントの後にだけ発生します。 + ### response.setEncoding(encoding=null) + +レスポンスボディのエンコーディングを設定します。 +`'utf8'`、`'ascii'`、あるいは `'base64'` のいずれかです。 +デフォルトは `null` で、 +`'data'` イベントが `Buffer` を生成することを意味します。 + ### response.pause() + +イベントの生成によるレスポンスを中断します。ダウンロード速度を落とすのに便利です。 + ### response.resume() + +中断されていたレスポンスを再開します。 diff --git a/doc/api/https.markdown b/doc/api/https.markdown index ff383f7d399b..715cc75a6d7b 100644 --- a/doc/api/https.markdown +++ b/doc/api/https.markdown @@ -1,21 +1,45 @@ ## HTTPS + +HTTPS は TLS/SSL 上の HTTP プロトコルです。 +Node ではこれらは別のモジュールとして実装されています。 + ## https.Server + +このクラスは `tls.Server` のサブクラスで、`http.Server` と同様のイベントを生成します。 +より詳しくは `http.Server` を参照してください。 + ## https.createServer(options, [requestListener]) + +新しい HTTPS Web サーバオブジェクトを返します。 +`option` は `tls.createServer()` と同じです。 +`requestListener` は関数で、 `'request'` イベントに自動的に追加されます。 + + +例: + // curl -k https://localhost:8000/ var https = require('https'); var fs = require('fs'); @@ -33,11 +57,22 @@ Example: ## https.request(options, callback) + +セキュアな Web サーバへのリクエストを作成します。 +`http.request()` と同様のオプションが指定できます。 + + +例: + var https = require('https'); var options = { @@ -61,8 +96,15 @@ Example: console.error(e); }); + +`options` 引数は以下のオプションを持ちます。 + + +- `host`: リクエストするホストのIPまたはドメイン。デフォルトは `'localhost'` です。 +- `port`: リクエストするホストのポート。デフォルトは 443 です。 +- `path`: リクエストのパス。デフォルトは `'/'` です。 +- `method`: HTTP りくえすとのメソッド。デフォルトは `'GET'` です。 +- `key`: SSLで使用する秘密鍵。デフォルトは `null` です。 +- `cert`: x509公開証明書。デフォルトは `null` です。 +- `ca`: リモートホストをチェックする信頼できる認証局または認証局の配列。 ## https.get(options, callback) + +`http.get()` と同様ですが HTTPS です。 + + +例: + var https = require('https'); https.get({ host: 'encrypted.google.com', path: '/' }, function(res) { diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown old mode 100644 new mode 100755 index 30e06363f56a..b29a3df98fb3 --- a/doc/api/modules.markdown +++ b/doc/api/modules.markdown @@ -1,17 +1,64 @@ +## Standard Modules + + +Node は多くのコンパイル済みのモジュールを備えています。 +そのうちの多くは以降のドキュメントに記述されています。 +モジュールを使用するもっとも一般的な方法は、 `require('name')` を呼びその戻り値をモジュールと同名のローカル変数に代入することです。 + + +例: + + var util = require('util'); + + +標準モジュール以外のモジュールを用いて Node を拡張することがでいます。 `'Modules'` をご覧ください。 + ## Modules + +Node はシンプルなモジュールローディングシステムを持ちます。 +Node では、ファイルとモジュールは１対１に対応します。 +例として、 `foo.js` は、同じディレクトリにある `circle.js` をロードしています。 + + +`foo.js` の内容: + var circle = require('./circle.js'); console.log( 'The area of a circle of radius 4 is ' + circle.area(4)); + +`circle.js` の内容: + var PI = Math.PI; exports.area = function (r) { @@ -22,6 +69,8 @@ The contents of `circle.js`: return 2 * PI * r; }; + +`circle.js` モジュールは `area()` と `circumference()` をエクスポートしています。 +オブジェクトをエクスポートするには、 `exports` という特別なオブジェクトに加えます。 +モジュールのローカル変数はプライベートです。 +この例の場合、変数 `PI` は `circle.js` のプライベート変数です。 + ### Core Modules + +Node にはバイナリにコンパイル済みのいくつかのモジュールがあります。 +これらのモジュールについては、このドキュメントの他の場所でより詳しく記述されています。 + +コアモジュールは、 Node のソースの `lib/` フォルダにて定義されています。 + +`require()` では常にコアモジュールの識別名を優先的に解釈します。 +例えば `require('http')` は、例え同名のファイルが存在していたとしても、常にビルトイインの HTTP モジュールを返します。 + ### File Modules + +指定された名前のファイルが見つからなかったら、 Node は指定されたファイル名に `.js` を付けたものと `.node` を付けたものを読み込もうとします。 + +`.js` ファイルは JavaScript ファイルとして解釈されます。 +一方 `.node` ファイルはコンパイル済みのアドオンモジュールとして解釈され、 `dlopen` を使って読み込まれます。 + +`'/'` から始まるモジュールは、ファイルへの絶対パスと見なされます。 +例えば、 `require('/home/marco/foo.js')` は `/home/macro/foo.js` を読み込みます。 + +`'./'` から始まるモジュールは、 `require()` を呼んだファイルからの相対パスになります。 +すなわち、 `foo.js` から `require('./circle')` によって `circle.js` を読み込むには、 `circle.js` は `foo.js` と同じディレクトリに存在していなければなりません。 + +'/' や './' が先頭になければ、モジュールは "コアモジュール" であるかもしくは `node_modules` フォルダから読み込まれることになります。 + ### Loading from `node_modules` Folders + +もし `require()` に渡されたモジュール識別子がネイティブモジュールではなく、かつ `'/'` や `'../'` や `'./'` から始まらないならば、 Node は現在のモジュールの親ディレクトリに `'/node_modules'` を付与してそこからモジュールを読み込もうとします。 + +そこに見つからない場合はさらに親ディレクトリに移動し、モジュールが見つかるか root ディレクトリに到達するまで同様のことを繰り返していきます。 + +例えば `'/home/ry/projects/foo.js'` の中で `require('bar.js')` を呼んでいた場合、 Node は下記の位置を上から順番に見ていきます。 + * `/home/ry/projects/node_modules/bar.js` * `/home/ry/node_modules/bar.js` * `/home/node_modules/bar.js` * `/node_modules/bar.js` + +この仕組みによって、プログラムはクラッシュを避けるために依存関係を上書きすることができるのです。 + ### Folders as Modules + +プログラムとライブラリをディレクトリ内にまとめて、そのエントリポイントを提示するという便利な方法もあります。 +それには `require()` に引数として何を渡すかによって3通りの方法があります。 + +1つ目は、 `package.json` というファイルをフォルダ直下に作成し、 `main` モジュールを指定するという方法です。 +例えば、 package.json は以下のようなファイルになります: + { "name" : "some-library", "main" : "./lib/some-library.js" } + +もし `./some-library` フォルダ内にこのファイルがあれば、 `require('./some-library')` は `./some-library/lib/some-library.js` を読みにいきます。 + +これは、 Node が package.json の存在に気づくことによってもたらされます。 + +もし package.json がディレクトリに存在していなければ、 Node はそのディレクトリで `index.js` もしくは `index.node` を探します。 +例えば、もし上の例で package.json がいるが存在しないとすると、 `require('./some-library')` は以下のファイルを読み込もうとします: + * `./some-library/index.js` * `./some-library/index.node` ### Caching + +モジュールは初めて読み込まれたときにキャッシュされます。 +すなわち（他のキャッシュと同様に） `require('foo')` を呼ぶたびに、もし引数の意味するものが同一のファイルであったなら全く同一のオブジェクトが返されます。 + + +`require('foo')` が複数回呼び出されても、モジュールが複数回実行されることにはなりません。 +これは重要な特徴です。 +そのため、「部分的に完了した」オブジェクトを返すことで、 +推移的な依存関係が循環していてもロードすることができます。 + + +もしモジュールを複数回実行したければ、関数を公開して、 +その関数を呼び出してください。 + #### Module Caching Caveats + +モジュールは解決されたファイル名に基づいてキャッシュされます。 +異なる場所にあるモジュールから呼び出されたモジュールは、 +(`node_module` フォルダからロードされるため) 異なったファイル名で +解決されることがあるため、 `require('foo')` が常に同じオブジェクトを返す +*保証*はなく、異なるファイルとして解決されます。 + ### module.exports + +`exports` オブジェクトはモジュールシステムによって作成されます。 +時々これは受け入れられず、多くのモジュールは何らかのクラスのインスタンスであることを望みます。 +それには公開したいオブジェクトを `module.exports` に割り当てます。 +例えば `a.js` と呼ばれるモジュールを作るとしたら + + var EventEmitter = require('events').EventEmitter; module.exports = new EventEmitter(); @@ -149,17 +302,28 @@ were making a module called `a.js` module.exports.emit('ready'); }, 1000); + +そして別のファイルで + var a = require('./a'); a.on('ready', function() { console.log('module a is ready'); }); + +`module.exports` への代入はすぐに行わなければなりません。 +コールバックの中ではできません。以下は動きません。 + x.js: setTimeout(function() { @@ -174,23 +338,46 @@ y.js: ### module.require + +`module.require` メソッドは、元のモジュールが `require()` +を呼び出したかのようにモジュールをロードするために提供されています。 + + +それには `module` オブジェクトの参照が必要なことに注意してください。 +`require()` が `exports` を返した後、一般的に `module` +はそのモジュールのコードで *のみ* 利用可能です。 +それが使われるようにするには、明示的にエクスポートする必要があります。 ### All Together... + +`require()` が呼び出されると、正確なファイル名を得るために `require.resolve()` が使われます。 + + +上で述べたことをまとめると、 require.resolve は以下の擬似コードで記述されるようなハイレベルなアルゴリズムに則っています: + require(X) from module at path Y 1. If X is a core module, a. return the core module @@ -233,19 +420,32 @@ in pseudocode of what require.resolve does: ### Loading from the `require.paths` Folders + +`require.paths` は、指定されたモジュール名が `'/'` や `'./'` や `'../'` から始まっていないときにモジュールを探しにいくパスを文字列として保持している配列です。 +例えば、require.pathsが次のように設定されているとします: + [ '/home/micheil/.node_modules', '/usr/local/lib/node_modules' ] + +そして、 `require('baz/baz.js')` を呼ぶと次の場所を探しにいきます: + * 1: `'/home/micheil/.node_modules/bar/baz.js'` * 2: `'/usr/local/lib/node_modules/bar/baz.js'` + +これらの動作を修正することができるよう、 `require.paths` 配列は実行時に変更することができます。 + +`require.paths` は `NODE_PATH` という環境変数の値によって初期化されます。 +`NODE_PATH` にはコロンで区切った複数のパスを記述することができます。 +上の例では、 `NODE_PATH` には次のような値がセットされていたものと考えられます: + /home/micheil/.node_modules:/usr/local/lib/node_modules + +`require.paths` からロードされるのは、モジュールが前述の `node_modules` アルゴリズムで見つけられなかった場合だけです。 +グローバルモジュールはバンドルされた依存性よりも低プライオリティです。 + #### **Note:** Please Avoid Modifying `require.paths` + +将来のバージョンでは `require.paths` は無くなる予定です。 + +実装当時はよいアイデアだと思われ実験的に使う分にはとても有用でしたが、実際に使いだしてみると変更可能な `require.paths` のリストというものはやっかいな混乱と頭痛の種になることがしばしばあったのです。 + ##### Setting `require.paths` to some other value does nothing. + +次のコードは、希望通りには動きません: + require.paths = [ '/usr/lib/node' ]; + +これは、 *実際の* Node モジュールへの参照パスを消滅させ、使われることのないパスに対する新たな参照を作り出しています。 + ##### Putting relative paths in `require.paths` is... weird. + +次のようにするとします: + require.paths.push('./lib'); + +これは、ファイルシステム上の `./lib` のある場所への絶対パスを追加する *わけではありません* 。 +代わりに、文字通り `'./lib'` を追加します。 +すなわち、もし `/a/b/x.js` ファイル内で `require('y.js')` した場合、 `/a/b/lib/y.js` を探しにいきます。 +同様に `/l/m/n/o/p.js` ファイル内で `require('y.js')` した場合は、 `/l/m/n/o/lib/y.js` を探しにいきます。 + + +実際に、これらはアドホックな依存性をバンドルするために用いられています。 +しかしこれらのテクニックはとても不安定です。 + ##### Zero Isolation + +（残念なことに）たった一つの `require.paths` 配列が全てのモジュールによって使われるという設計になっています。 + +その結果、もしある Node プログラムが上記の挙動を行っていたら、同じプロセス上にいる他の全ての Node プログラムの動作も永遠にそして微妙に変化させてしまいます。 +アプリケーションが成長するにつれ、私たちは機能をまとめていきますが、 +それらがどのように影響するかを予測するのが難しくなります。 + ### Accessing the main module + +ファイルがNodeによって直接実行される場合、その `module` が +`require.main` に設定されます。 +これは、ファイルが直接実行されたかを決定できることを意味します。 + require.main === module + +`foo.js` ファイルの場合、`node foo.js` と実行された場合にこれは `true` +になりますが、`require('./foo')` で実行された場合は `false` になります。 + +`module` は `filename` プロパティ (通常 `__filename` と同じです) +を提供するため、現在のアプリケーションのエントリポイントは +`require.main.filename` をチェックすることで得ることができます。 + ## AMD Compatibility + +Node のモジュールは `define` という名前の関数にアクセスできます。 +それはモジュールの戻り値を指定するために使われます。 +これは node プログラムには必要ありませんが、Asynchronous Module Definition +パターンを使用するモジュールローダとの互換性を提供するために +node API に存在しています。 + + +上記の例のモジュールは次のように構築することが出来ます。 + define(function (require, exports, module) { var PI = Math.PI; @@ -340,6 +629,8 @@ The example module above could be structured like so: }; }); + +* `define()` の最後の引数だけが重要です。他のモジュールローダによっては + `define(id, [deps], cb)` パターンを使用しますが、 + node プログラムには関係がないので、その他の引数は無視されます。 +* `define` のコールバックが `undefined` 以外の値を返した場合、 + その値は `module.exports` に割り当てられます。 +* **重要**: "AMD" と呼ばれるにも関わらず、node のモジュールローダは + **実際には同期的です**。`define()` を使用してもこの事実は変わりません。 + Node はコールバックをすぐに実行します。 + それに応じてプログラムを設計してください。 ### Accessing the main module + +ファイルが Node によって直接実行される場合、そのファイルの `module` が +`require.main` に設定されます。 +これは、ファイルが直接実行されているかテストできることを意味します。 + require.main === module + +`foo.js` ファイルでは、`node foo.js` と実行された場合これは `true` +となりますが、`require('./foo')` の場合は `false` となります。 + + +`module` は `filename` プロパティ (通常 `__filename` と同じです) +を提供するので、現在のアプリケーションのエントリポイントを +`require.main.filename` で得ることが出来ます。 ## Addenda: Package Manager Tips + +Node の `require()` は普通のディレクトリ構造をサポートできるよう汎用的に設計されています。 +`dpkg` や `rpm` や `npm` のようなパッケージ管理プログラムは修正なしに Node モジュールからネイティブパッケージを組み立てることができるでしょう。 + + +推奨するディレクトリ構造は次のようになります: + +例えば `/usr/lib/node//` フォルダに、あるパッケージの特定のバージョンを保持する形式です。 + + +パッケージは相互に依存しあうことがあります。 +`foo` パッケージをインストールするためにはある特定のバージョンの `bar` パッケージをインストールする必要があります。 +`bar` パッケージ自身も依存関係をもっているので、ときには依存関係が衝突したり循環したりすることがあります。 + + +Node はモジュールの `realpath` （シンボリックリンクを解釈します）を調べ、その依存関係を上述の `node_modules` フォルダの仕組みで探しにいきます。 +これによって次のような構造をとてもシンプルに解釈することができます。 + + +* `/usr/lib/node/foo/1.2.3/` - `foo` パッケージの中身。バージョン1.2.3。 +* `/usr/lib/node/bar/4.3.2/` - `bar` パッケージの中身。 `foo` が依存している。 +* `/usr/lib/node/foo/1.2.3/node_modules/bar` - `/usr/lib/node/bar/4.3.2/` へのシンボリックリンク。 +* `/usr/lib/node/bar/4.3.2/node_modules/*` - `bar` が依存しているパッケージへのシンボリックリンク。 + + +このようにして、もし仮に依存関係に循環や衝突が見つかったとしても、全てのモジュールは依存しているパッケージの特定のバージョンを取得することができます。 + +`foo` パッケージの中で `require('bar')` したら、 `/usr/lib/node/foo/1.2.3/node_modules/bar` からリンクされているバージョンを取得します。 +そして、 `bar` パッケージ内で `require('quux')` を呼んだら、 `/usr/lib/node/bar/4.3.2/node_modules/quux` からリンクされているバージョンを取得します。 + +さらに、モジュールを探索する過程をより最適化するために、 `/usr/lib/node` にパッケージを置くよりも `/usr/lib/node_modules//` に置くのをお勧めします。 +そうすることで Node は見つからない依存パッケージを `/usr/node_modules` や `/node_modules` に探しにいかなくてもようなります。 + +Node の REPL でモジュールを使えるようにするために、 `/usr/lib/node_modules` フォルダを `$NODE_PATH` 環境変数に追加するとよいでしょう。 +`node_modules` フォルダを使ったモジュール探索は全て相対的なものであり、 `require()` を呼び出したファイルの絶対パスを基準としているので、パッケージ自体はどこにでも配置することができます。 + diff --git a/doc/api/net.markdown b/doc/api/net.markdown index f808dfae53ab..cd345221a5e4 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -1,51 +1,112 @@ ## net + +`net` モジュールは非同期なネットワークのラッパーを提供します。 +それはサーバとクライアントの両方 (ストリームと呼ばれます) を作成するための方法を含みます。 +このモジュールは`require("net");`によって取り込むことができます。 + ### net.createServer([options], [connectionListener]) + +新しい TCP サーバを作成します。 +`connectionListener` 引数は `'connection'` +イベントに対するリスナーとして自動的に加えられます。 +`options` は以下のデフォルト値を持つオブジェクトです: + { allowHalfOpen: false } + +`allowHalfOpen` が `true` だと、反対側のソケットが FIN パケットを送信してきても自動的に FIN を送信しなくなります。 +ソケットは読み込み可能ではなくなりますが、書き込み可能のままです。 +明示的に `end()` を呼び出す必要があります。 +`'end'` イベントにより多くの情報があります。 + ### net.createConnection(arguments...) + +新しいソケットオブジェクトを構築し、与えられたロケーションへのソケットをオープンします。 +ソケットが確立されると、`'connect'` イベントが生成されます。 + + +このメソッドの引数はコネクションの種類によって変わります。 + * `net.createConnection(port, [host], [callback])` + + + `host` 上の `port` に対する TCP コネクションを作成します。 + `host` が省略されると `localhost` が仮定されます。 + * `net.createConnection(path, [callback])` + + + `path` に対する UNIX ドメインソケットを作成します。 + + +`callback` 引数は `connect` イベントのリスナとして追加されます。 + --- ### net.Server + +このクラスは TCP または UNIX ドメインのサーバを作成するために使われます。 + + +8124 番のポートへの接続を待ち受けるエコーサーバの例: + var net = require('net'); var server = net.createServer(function (c) { c.write('hello\r\n'); @@ -53,34 +114,74 @@ on port 8124: }); server.listen(8124, 'localhost'); + +`telnet` を使ってテストします: + telnet localhost 8124 + +`'/tmp/echo.sock'` へのソケットを待ち受けるには、最後の行をこのように変更します。 + server.listen('/tmp/echo.sock'); + +`nc` を使って UNIX ドメインソケットサーバへ接続します: + nc -U /tmp/echo.sock + +`net.Server` は以下のイベントを持つ `EventEmitter` です: + #### server.listen(port, [host], [callback]) + +指定された `port` と `host` でコネクションの受け入れを開始します。 +`host` が省略されると、サーバはどんな IPv4 アドレスへの接続も受け入れます +(`INADDR_ANY`)。 + + +この関数は非同期です。最後の引数の `callback` はサーバがバインドすると呼び出されます。 + + +一部のユーザが陥る問題の一つは、`EADDRINUSE` エラーです。 +これは、他のサーバが要求されたポートを使っているという意味です。 +これに対照する方法の一つは、1秒待機してリトライすることです。 +これは次のようになります + server.on('error', function (e) { if (e.code == 'EADDRINUSE') { console.log('Address in use, retrying...'); @@ -91,45 +192,100 @@ would be to wait a second and the try again. This can be done with } }); + +注意: Node の全てのソケットは SO_REUSEADDR が設定されます) + #### server.listen(path, [callback]) + +与えられた `path` へのコネクションを待ち受けるする UNIX ドメインソケットのサーバを開始します。 + + +この関数は非同期です。 +最後の引数の `callback` はサーバがバインドすると呼び出されます。 + #### server.listenFD(fd) + +与えられたファイル記述子上のコネクションを待ち受けるサーバを開始します。 + + +このファイル記述子は既に `bind(2)` および +`listen(2)` システムコールが呼び出されていなければなりません。 +加えて、ノンブロッキングに設定されていなければなりません。 +`fcntl(fd, F_SETFL, O_NONBLOCK)` を試してください。 + #### server.pause(msecs) + +接続の待ち受けをミリ秒で与えられた時間だけ中断します (デフォルトは 1 秒です)。 +これは、新しい接続を抑えることで DoS 攻撃やその他の加入超過に対抗するために +役立ちます。 + #### server.close() + +サーバが新しいコネクションを受け付けるのを終了します。 +この関数は非同期で、サーバは最終的に `'close'` イベントを生成した時にクローズされます。 + #### server.address() + +オペレーティングシステムから報告された、サーバにバインドされたアドレスとポートを返します。 +OSによって割り当てられたアドレスが渡された時に、どのポートに割り当てられたものかを調べるのに便利です。 +返されるオブジェクトは二つのプロパティを持ちます。 +例えば `{"address":"127.0.0.1", "port":2121}` + + +例: + var server = net.createServer(function (socket) { socket.end("goodbye\n"); }); @@ -143,74 +299,158 @@ Example: #### server.maxConnections + +サーバの接続数が大きくなった時に接続を拒否するためにこのプロパティを設定します。 + #### server.connections + +このサーバ上の並行コネクションの数です。 + #### Event: 'connection' `function (socket) {}` + +新しいコネクションが作成されると生成されます。 +`socket` は `net.Socket` のインスタンスです。 + #### Event: 'close' `function () {}` + +サーバがクローズした時に生成されます。 + --- ### net.Socket + +このオブジェクトは TCP または UNIX ドメインのソケットを抽象化したものです。 +`net.Socket` のインスタンスは双方向のストリームインタフェースを実装します。 +それらはユーザによって (`connect()` によって) 作成されてクライアントとして使われるか、 +Node によって作成されてサーバの `'connection'` イベントを通じてユーザに渡されます。 + + +`net.Socket` のインスタンスは以下のイベントを持つ EventEmitter です: + #### new net.Socket([options]) + +新しいソケットオブジェクトを構築します。 + + +`options` は以下のデフォルト値を持つオブジェクトです。 + { fd: null type: null allowHalfOpen: false } + +`fd` に既存のソケットのファイル記述子を指定することができます。 +`type` にはプロトコルを指定することができます。 +指定できるのは `'tcp4'`、`'tcp6'` または `'unix'` のいずれかです。 +`allowHalfOpen` については `createServer()` および `'end'` イベントを参照してください。 + #### socket.connect(port, [host], [callback]) #### socket.connect(path, [callback]) + +与えられたソケットでコネクションをオープンします。 +`port` と `host` が与えられた場合、 +ソケットは TCP ソケットとしてオープンされます。 +`host` が省略された場合は `localhost` が仮定されます。 +`path` が与えられた場合は、 +ソケットはそのパスへの UNIX ドメインソケットとしてオープンされます。 + + +通常このメソッドは必要なく、`net.createConnection` でソケットをオープンします。 +これを使うのは、カスタマイズされたソケットを実装している場合や、 +ソケットがクローズされた後にコネクションを再利用して別のサーバに接続する場合だけです。 + + +この関数は非同期です。ソケットが確立されると `'connect'` イベントが生成されます。 +接続で問題があった場合は `'connect'` イベントは生成されず、 +例外とともに `'error'` イベントが生成されます。 + + +`callback` 引数は 'connect' イベントのリスナに加えられます。 + #### socket.bufferSize + +`net.Socket` には、`socket.write()` と常に協調するプロパティがあります。 +これはユーザが実行速度を向上させる手助けになります。 +コンピュータはソケットに書き込まれるデータ量と必ずしも同じ速度で進むわけではありません - ネットワーク接続は、単純に遅すぎます。 +Node は、ソケットに書き込まれるデータを内部のキューに入れ、可能になった時にワイヤ上に送信します (内部ではソケットのファイル記述子が書き込み可能になるのをポーリングします)。 + +内部的なバッファリングの結果、メモリ消費が増大するかもしれません。 +このプロパティは、現在書き込みのためにバッファリングされている文字数を示します。 +(文字数は書き込まれるバイト数とほぼ同じですが、バッファが文字列を含んでいる場合、文字列は遅延的にエンコードされるため、正確なバイト数は分かっていません) + +大きな、あるいは増大する `bufferSize` を体験したユーザは、そのプログラムで `pause()` および `resume()` を使ってデータフローを「抑えよう」としなければなりません。 #### socket.setEncoding(encoding=null) + +受信したデータのエンコーディングを設定します (`'ascii'`、`'utf8'`、 +あるいは `'base64'` のいずれかです)。 + #### socket.setSecure() + +この関数は v0.3 で削除されました。 +これはコネクションを SSL/TLS にアップグレードするために使われていました。 +新しい API である [TLS の章](tls.html#tLS_) を参照してください。 #### socket.write(data, [encoding], [callback]) + +ソケットにデータを送信します。 +文字列の場合、第 2 引数はエンコーディングを指定します － デフォルトは UTF-8 です。 + + +データ全体のカーネルバッファへのフラッシュが成功すると `true` を返します。 +データ全体または一部がユーザメモリ内のキューに入れられた場合は `false` を返します。 +再びバッファが空いた場合は `'drain'` イベントが生成されます。 + + +オプションの `callback` 引数はデータが最終的に出力された時に実行されます +－ これはすぐには起きないでしょう。 + #### socket.write(data, [encoding], [fileDescriptor], [callback]) + +UNIX ソケットの場合、ファイル記述子をソケットに送信することができます。 +単純に `fileDescriptor` 引数を加えることで、相手側には `'fd'` イベントが生成されます。 + #### socket.end([data], [encoding]) + +ソケットをハーフクローズします。例えば FIN パケットを送信します。 +サーバはまだデータを送り続けてくることができます。 + + +`data` が指定された場合は、 +`socket.write(data, encoding)` に続けて `socket.end()` を呼び出すのと等価です。 + #### socket.destroy() + +このソケット上でどんな I/O も起こらないことを保証します。 +(パースエラーなどの) エラーの場合にだけ必要です。 + #### socket.pause() + +データの読み込みを中断します。つまり、`'data'` イベントは生成されません。 +アップロード速度を落とすために便利です。 + #### socket.resume() + +`pause()` を呼び出した後で読み込みを再開します。 + #### socket.setTimeout(timeout, [callback]) + + + +アイドルタイムアウトが引き起こされると、ソケットは `'timeout'` イベントを受信しますが、 +コネクションは切断されません。 +ユーザは手動で `end()` または `destroy()` を呼び出す必要があります。 + + +`timeout` が 0 の場合、アイドルタイムアウトは無効にされます。 + + +オプションの `callback` 引数は、`timeouot` イベントの一回限りのリスナを追加します。 + #### socket.setNoDelay(noDelay=true) + +Nagle アルゴリズムを無効にします。 +デフォルトでは TCP コネクションは Nagle アルゴリズムを使用し、データを送信する前にバッファリングします。 +`noDelay` に設定すると、データは `socket.write()` を呼び出す度に即座に送信されます。 + #### socket.setKeepAlive(enable=false, [initialDelay]) + +キープアライブ機能を有効/無効にします。 +オプションで最初の keepalive probe がアイドルソケットに送信されるまでの初期遅延を設定します。 +`initialDelay` (ミリ秒) が設定されると、 +最後にデータパケットを受信してから最初の keepalive probe までの遅延が設定されます。 +初期遅延に 0 が設定されると、デフォルト設定から値を変更されないようにします。 + #### socket.address() + +オペレーティングシステムから報告された、ソケットにバインドされたアドレスとポートを返します。 +返されるオブジェクトは二つのプロパティを持ちます。 +例えば `{"address":"192.168.57.1", "port":62053}` + #### socket.remoteAddress + +リモートの IP アドレスを表現する文字列です。 +例えば、`'74.125.127.100'` あるいは `'2001:4860:a005::68'`。 + + +このメンバはサーバサイドのコネクションにのみ与えられます。 + #### socket.remotePort + + +リモートポートの数値表現です。 +たとえば、`80` や `21`。 #### Event: 'connect' `function () { }` + +ソケットコネクションの確立が成功した場合に生成されます。 +`connect()` を参照してください。 + #### Event: 'data' `function (data) { }` + +データを受信した場合に生成されます。 +`data` 引数は `Buffer` または `String` です。 +データのエンコーディングは `socket.setEncoding()` で設定されます。 +(より詳しい情報は [Readable Stream](streams.html#readable_Stream) を参照してください)。 + #### Event: 'end' `function () { }` + +ソケットの相手側が FIN パケットを送信した場合に生成されます。 + + +デフォルト (`allowHalfOpen == false`) では、 +保留されていた書き込みキューが出力されるとソケットはファイル識別子を破棄します。 +しかし、`allowHalfOpen == true` が設定されていると、 +ユーザがデータを書き込めるようにしておくために、ソケットは自動的に `end()` を呼び出さないので、 +ユーザが `end()` を呼び出す必要があります。 + #### Event: 'timeout' `function () { }` + +ソケットがタイムアウトして非アクティブになった場合に生成されます。 +これはソケットがアイドルになったことを通知するだけです。 +利用者は手動でコネクションをクローズする必要があります。 + See also: `socket.setTimeout()` @@ -367,38 +784,68 @@ See also: `socket.setTimeout()` `function () { }` + +書き込みバッファが空になった場合に生成されます。アップロード速度を落とすために使うことができます。 + #### Event: 'error' `function (exception) { }` + +エラーが発生した場合に生成されます。`'close'` イベントはこのイベントの後に直接呼び出されます。 + #### Event: 'close' `function (had_error) { }` + +ソケットが完全にクローズした場合に生成されます。 +引数 `had_error` は boolean で、ソケットが転送エラーでクローズされたのかどうかを示します。 + --- ### net.isIP #### net.isIP(input) + + #### net.isIPv4(input) + +input が バージョン 4 の IP アドレスなら true、そうでなければ false を返します。 + #### net.isIPv6(input) + +input が バージョン 6 の IP アドレスなら true、そうでなければ false を返します。 + diff --git a/doc/api/os.markdown b/doc/api/os.markdown index eff85200ddb4..78e42bcd3b09 100644 --- a/doc/api/os.markdown +++ b/doc/api/os.markdown @@ -1,49 +1,111 @@ ## os Module + +`require('os')` によってこのモジュールにアクセスします。 + ### os.hostname() + +オペレーティングシステムのホスト名を返します。 + ### os.type() + +オペレーティングシステムの名前を返します。 + ### os.platform() + +プラットフォームのオペレーティングシステムを返します。 + ### os.arch() + +オペレーティングシステムの CPU アーキテクチャを返します。 + ### os.release() + +オペレーティングシステムのリリースを返します。 + ### os.uptime() + + +システムが起動してからの秒数を返します。 + ### os.loadavg() + +1 分、5 分、15 分間のロードアベレージを含んだ配列を返します。 + ### os.totalmem() + +システム全体が使用しているメモリのバイト数を返します。 + ### os.freemem() + +システム全体で空いているメモリのバイト数を返します。 + ### os.cpus() + +インストールされている CPU/ コアごとの情報を含んだオブジェクトの配列を返します。 +情報はモデル、スピード (MHz)、そして時間 (CPU が使用した user, nice, sys, idle, irq 時間を含んだオブジェクト) です。 + + +os.cpus の例: + [ { model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', speed: 2926, times: @@ -111,8 +173,13 @@ Example inspection of os.cpus: ### os.getNetworkInterfaces() + +ネットワークインタフェースの一覧を取得します。 + { lo0: [ { address: '::1', family: 'IPv6', internal: true }, { address: 'fe80::1', family: 'IPv6', internal: true }, diff --git a/doc/api/path.markdown b/doc/api/path.markdown index a074ed59b2d5..bec681adec2d 100644 --- a/doc/api/path.markdown +++ b/doc/api/path.markdown @@ -1,29 +1,64 @@ ## Path + +このモジュールはファイルパスを扱うユーティリティを含みます。 +利用するには`require('path')`を呼び出してください。 +このモジュールは以下のメソッドを提供します。 + ### path.normalize(p) + +文字列によるパスを正規化します。`'..'` と `'.'` の要素には注意してください。 + + +複数のスラッシュが見つかると、それらは一つに置換されます; +パスの最後にスラッシュが含まれていると、それは維持されます。 +Windows ではバックスラッシュが使われます。 + + +例: + path.normalize('/foo/bar//baz/asdf/quux/..') // returns '/foo/bar/baz/asdf' ### path.join([path1], [path2], [...]) + +全ての引数を一つに結合し、結果として得られるパスを正規化します。 +文字列でない引数は無視されます。 + + +例: + path.join('/foo', 'bar', 'baz/asdf', 'quux', '..') // returns '/foo/bar/baz/asdf' @@ -34,31 +69,70 @@ Example: ### path.resolve([from ...], to) + +`to` の絶対パスを解決します。 + + +もし `to` が既に絶対パスでなければ、絶対パスが見つかるまで `from` 引数を右から左の順で先頭に加えます。 +全ての `from` を加えた後、パスがまだ絶対パスでなければ、カレントワーキングディレクトリが同様に使われます。 +結果のパスは正規化され、解決されたパスがルートディレクトリでない限り末尾のスラッシュは削除されます。 +文字列でない引数は無視されます。 + + +それはシェルにおける `cd` コマンドの列だと考えることができます。 + + +例: + path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile') + +これは以下と同様です。 + cd foo/bar cd /tmp/file/ cd .. cd a/../subfile pwd + +違いは、それぞれのパスが必ずしも存在する必要がないことと、ファイルでも構わないことです。 + + +例: + path.resolve('/foo/bar', './baz') // returns '/foo/bar/baz' @@ -73,20 +147,40 @@ Examples: ### path.dirname(p) + +パスに含まれるディレクトリ名を返します。Unixの `dirname` コマンドと同様です。 + + +例: + path.dirname('/foo/bar/baz/asdf/quux') // returns '/foo/bar/baz/asdf' ### path.basename(p, [ext]) + +パスの最後の要素を返します。Unixの `basename` コマンドと同様です。 + + +例: + path.basename('/foo/bar/baz/asdf/quux.html') // returns 'quux.html' @@ -97,10 +191,18 @@ Example: ### path.extname(p) + +パスの拡張子を返します。 +パスの最後の要素について、最後の '.' から後にある文字列が対象になります。 +最後の要素に '.' が含まれていなかった場合、もしくは '.' が最初の文字だった場合は、空の文字列を返します。 +例: + path.extname('index.html') // returns '.html' @@ -111,9 +213,16 @@ the first character, then it returns an empty string. Examples: ### path.exists(p, [callback]) + +与えられたパスが存在するかどうか検査します。 +そして引数の `callback` を真か偽か検査の結果とともに呼び出します。 +例: + path.exists('/etc/passwd', function (exists) { util.debug(exists ? "it's there" : "no passwd!"); }); @@ -121,4 +230,9 @@ with either true or false. Example: ### path.existsSync(p) + +同期版の `path.exists` です。 diff --git a/doc/api/process.markdown b/doc/api/process.markdown index 04d2a164a012..9ff29bc8ddc5 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -1,20 +1,39 @@ ## process + +`process` はグローバルオブジェクトで、どこからでもアクセスすることができます。 +それは `EventEmitter` のインスタンスです。 + ### Event: 'exit' `function () {}` + +プロセスが終了しようとしている時に生成されます。 +これは (ユニットテストのように) モジュールの状態を一定の時間でチェックするのに適したフックとなります。 +メインのイベントループは 'exit' コールバックが終了するともはや動作しないので、 +タイマーはスケジュールされないかもしれません。 + + +`exit` を監視する例: + process.on('exit', function () { process.nextTick(function () { console.log('This will not run'); @@ -26,12 +45,24 @@ Example of listening for `exit`: `function (err) { }` + +発生した例外がイベントループまでたどり着いた場合に生成されます。 +もしこの例外に対するリスナーが加えられていれば、 +デフォルトの動作 (それはスタックトレースをプリントして終了します) は起こりません。 + + +`uncaughtException` を監視する例: + process.on('uncaughtException', function (err) { console.log('Caught exception: ' + err); }); @@ -44,21 +75,40 @@ Example of listening for `uncaughtException`: nonexistentFunc(); console.log('This will not run.'); + +`uncaughtException` は例外を扱うとても荒削りなメカニズムであることに注意してください。 +プログラムの中で try / catch を使えばもっとプログラムの流れをうまく制御できるでしょう。 +特にサーバプログラムはいつまでも実行し続けるように設計されるので、 +`uncaughtException` は有益で安全なメカニズムになり得ます。 + ### Signal Events `function () {}` + +プロセスがシグナルを受信した場合に生成されます。 +SIGINT、SIGUSR1、その他の POSIX 標準シグナル名の一覧について は sigaction(2) を参照してください。 + + +`SIGINT`を監視する例: + // Start reading from stdin so we don't exit. process.stdin.resume(); @@ -66,16 +116,31 @@ Example of listening for `SIGINT`: console.log('Got SIGINT. Press Control-D to exit.'); }); + +多くの端末プログラムで簡単に `SIGINT` を送る方法は `Control-C` を押すことです。 + ### process.stdout + +`stdout` に対する `Writable Stream` です。 + + +例: `console.log` の定義 + console.log = function (d) { process.stdout.write(d + '\n'); }; @@ -83,16 +148,34 @@ Example: the definition of `console.log` ### process.stderr + +`stderr` に対する `Writable Stream` です。 +このストリームへの書き込みはブロックします。 + ### process.stdin + +標準入力に対する `Readable Stream` です。 +デフォルトでは、標準入力に対するストリームは中断されているため、 +読み込みのためには `process.stdin.resume()` を呼び出さなければなりません。 + + +標準入力をオープンして二つのイベントを監視する例: + process.stdin.resume(); process.stdin.setEncoding('utf8'); @@ -107,17 +190,29 @@ Example of opening standard input and listening for both events: ### process.argv + +コマンドライン引数を含む配列です。 +最初の要素は 'node'、2 番目の要素は JavaScript ファイルの名前になります。 +その後の要素はコマンドラインの追加の引数になります。 + // print process.argv process.argv.forEach(function (val, index, array) { console.log(index + ': ' + val); }); + +このように出力されます: + $ node process-2.js one two=three four 0: node 1: /Users/mjr/work/node/process-2.js @@ -128,17 +223,33 @@ This will generate: ### process.execPath + +プロセスによって開始された実行可能ファイルの絶対パスです。 + + +例: + /usr/local/bin/node ### process.chdir(directory) + +プロセスのカレントワーキングディレクトリを変更します。 +もし失敗した場合は例外をスローします。 + console.log('Starting directory: ' + process.cwd()); try { process.chdir('/tmp'); @@ -152,42 +263,81 @@ Changes the current working directory of the process or throws an exception if t ### process.cwd() + +プロセスのカレントワーキングディレクトリを返します。 + console.log('Current directory: ' + process.cwd()); ### process.env + +ユーザの環境を含むオブジェクトです。environ(7) を参照してください。 + ### process.exit(code=0) + +指定の `code` でプロセスを終了します。 +もし省略されると、「成功」を示すコード `0` を使って終了します。 + + +「失敗」を示すコードで終了する例: + process.exit(1); + +node を実行したシェルで終了コードが 1 であることを見ることができるでしょう。 + ### process.getgid() + +プロセスのグループ識別子を取得します (getgid(2) 参照)。 +これは数値によるグループ ID で、グループ名ではありません。 + console.log('Current gid: ' + process.getgid()); ### process.setgid(id) + +プロセスのグループ識別子を設定します (setgid(2) 参照)。 +これは数値による ID もグループ名の文字列のどちらも受け入れます。 +もしグループ名が指定されると、数値による ID が解決できるまでこのメソッドはブロックします。 + console.log('Current gid: ' + process.getgid()); try { process.setgid(501); @@ -200,18 +350,31 @@ blocks while resolving it to a numerical ID. ### process.getuid() + +プロセスのユーザ識別子を取得します (getuid(2) 参照)。 +これは数値によるユーザ ID で、ユーザ名ではありません。 + console.log('Current uid: ' + process.getuid()); ### process.setuid(id) + +プロセスのユーザ識別子を設定します (setuid(2) 参照)。 +これは数値による ID もユーザ名の文字列のどちらも受け入れます。 +もしユーザ名が指定されると、数値による ID が解決できるまでこのメソッドはブロックします。 + console.log('Current uid: ' + process.getuid()); try { process.setuid(501); @@ -224,30 +387,61 @@ blocks while resolving it to a numerical ID. ### process.version + +`NODE_VERSION` を提示するコンパイル済みプロパティです。 + console.log('Version: ' + process.version); ### process.installPrefix + +`NODE_PREFIX` を提示するコンパイル済みプロパティです。 + console.log('Prefix: ' + process.installPrefix); ### process.kill(pid, signal='SIGTERM') + +プロセスにシグナルを送ります。 +`pid` はプロセス ID で `signal` は送信されるシグナルを文字列で記述したものです。 +シグナルの名前は 'SIGINT' や 'SIGUSR1' のような文字列です。 +省略すると、シグナルは 'SIGTERM' となります。 +詳細は kill(2) を参照してください。 + + +この関数の名前が `process.kill` であるとおり、 +これは `kill` システムコールのように本当にシグナルを送信することに注意してください。 +対象のプロセスを殺すだけでなく、他のシグナルも送信されます。 + + +自身にシグナルを送信する例: + process.on('SIGHUP', function () { console.log('Got SIGHUP signal.'); }); @@ -262,53 +456,95 @@ Example of sending a signal to yourself: ### process.pid + + console.log('This process is pid ' + process.pid); ### process.title + +'ps' でどのよう表示されるかを設定するための getter/setter です。 + ### process.arch + +実行しているプロセッサのアーキテクチャ: `'arm'`、`'ia32'`、または +`'x64'`。 + console.log('This processor architecture is ' + process.arch); ### process.platform + +どのプラットフォームで動いているかです。`'linux2'`、`'darwin'`、など。 + console.log('This platform is ' + process.platform); ### process.memoryUsage() + +Node プロセスのメモリ使用状況を記述したオブジェクトを返します。 + var util = require('util'); console.log(util.inspect(process.memoryUsage())); + +このように生成されます: + { rss: 4935680, vsize: 41893888, heapTotal: 1826816, heapUsed: 650472 } + +`heapTotal` と `heapUsed` は V8 のメモリ使用状況を参照します。 + ### process.nextTick(callback) + +イベントループの次以降のループでコールバックを呼び出します。 +これは `setTimeout(fn, 0)` の単純なエイリアス*ではなく*、 +はるかに効率的です。 + process.nextTick(function () { console.log('nextTick callback'); }); @@ -316,10 +552,17 @@ efficient. ### process.umask([mask]) + +プロセスのファイルモード作成マスクを設定または読み込みます。 +子プロセスは親プロセスからマスクを継承します。 +`mask` 引数が与えられると元のマスクが返され、そうでなければ現在のマスクが返されます。 + var oldmask, newmask = 0644; oldmask = process.umask(newmask); @@ -329,4 +572,9 @@ given, otherwise returns the current mask. ### process.uptime() + +Node が実行されてからの秒数です。 diff --git a/doc/api/querystring.markdown b/doc/api/querystring.markdown index edb6d64c11d8..32bf12a91cd8 100644 --- a/doc/api/querystring.markdown +++ b/doc/api/querystring.markdown @@ -1,15 +1,30 @@ ## Query String + +このモジュールはクエリ文字列を処理するユーティリティを提供します。 以下のメソッドから成ります: + ### querystring.stringify(obj, sep='&', eq='=') + +クエリオブジェクトを文字列へ直列化します。オプションとしてデフォルトの区切り文字と代入文字を上書き指定できます。 + + +例: + querystring.stringify({foo: 'bar'}) // returns 'foo=bar' @@ -20,21 +35,41 @@ Example: ### querystring.parse(str, sep='&', eq='=') + +クエリ文字列をオブジェクトに復元します。オプションとしてデフォルトの区切り文字と代入文字を上書き指定できます。 + + +例: + querystring.parse('a=b&b=c') // returns { a: 'b', b: 'c' } ### querystring.escape + +escape 関数は `querystring.stringify` で使用されていて、必要な場合にオーバーライドできるよう提供されています。 + ### querystring.unescape + +unescape関数は `querystring.parse` で使用されていて、必要な場合にオーバーライドできるよう提供されています。 diff --git a/doc/api/readline.markdown b/doc/api/readline.markdown index 661ad945d78b..52eca709c043 100644 --- a/doc/api/readline.markdown +++ b/doc/api/readline.markdown @@ -1,10 +1,20 @@ ## Readline + +このモジュールはストリーム (たとえば標準入力) +を行ごとに読み込むことを可能にします。 + +このモジュールを一度起動すると、このインタフェースと +(標準入力などの) ストリームをクローズするまで node +プログラムは終了しないことに注意してください。 +きれいに終了する方法を以下に示します: 
 var readline = require('readline');
@@ -20,8 +30,12 @@ i.question("What do you think of node.js?", function(answer) {
 
 ### createInterface(input, output, completer)
 
+
+`input` を読み込み、`output` へ書き込むインターフェースオブジェクトを返します。
+TODO: `completer` は TAB による補完に使われると思いますが、確かではありません。
 
 ### interface.setPrompt(prompt, length)
 
@@ -29,14 +43,23 @@ TODO
 
 ### interface.prompt()
 
+
+TODO: プロンプトを表示するために呼び出されると思われる。
 
 ### interface.question(query, cb)
 
+
+`query` を表示しして、ユーザが応答をタイプするとコールバックが呼び出されます。
 
+
+使用例:
 
 
 interface.question("What is your favorite food?", function(answer) {
diff --git a/doc/api/readline.md b/doc/api/readline.md
index ea2a7f2e4a32..ad71b22d5b9c 100644
--- a/doc/api/readline.md
+++ b/doc/api/readline.md
@@ -1,11 +1,20 @@
 ## Readline
 
+
+このモジュールを使うには、`require('readline')`します。
+Readlineはストリーム (標準入力など) から行単位に読み込む基礎となります。
 
+
+一度このモジュールを起動すると、インタフェースまたは標準入力をクローズするまで
+node プログラムは終了しないことに注意してください。
+プログラムをきれいに終了する方法を以下に示します:
 
     var rl = require('readline');
 
@@ -22,35 +31,64 @@ to allow your program to gracefully terminate:
 
 ### rl.createInterface(input, output, completer)
 
+
+二つのストリームを受け取って readline のインタフェースを作成します。
+`completer` 関数は補完のために使われます。
+部分文字列が与えられると、`[[substr1, substr2, ...], originalsubstring]`
+を返します。
 
+
+`createInterface` は一般的に、ユーザ入力を受け取るために `process.stdin`
+および `process.stdout` とともに使われます:
 
     var readline = require('readline'),
       rl = readline.createInterface(process.stdin, process.stdout);
 
 ### rl.setPrompt(prompt, length)
 
+
+プロンプトを設定します。
+たとえば `node` をコマンドラインで実行すると、node のプロンプト `> `
+を目にします。
 
 ### rl.prompt()
 
+
+ユーザからの入力を準備します。
+新しいライン上に現在の (`setPrompt` で設定された) プロンプトを表示し、
+ユーザが新たに書き込む位置を与えます。
 
 
 
 ### rl.question(query, callback)
 
+
+`query` をプロンプトとして先頭に出力し、ユーザの応答を引数として
+`callback` を呼び出します。
+`query` をユーザに表示し、ユーザが応答をタイプすると `callback` 
+が起動されます。
 
+
+使用例:
 
     interface.question('What is your favorite food?', function(answer) {
       console.log('Oh, so your favorite food is ' + answer);
@@ -58,28 +96,49 @@ Example usage:
 
 ### rl.close()
 
+
+
+  tty をクローズします。
 
 ### rl.pause()
 
+
+  tty を一時中断します。
 
 ### rl.resume()
 
+
+  tty を再開します。
 
 ### rl.write()
 
+
+  tty に出力します。
 
 ### Event: 'line'
 
 `function (line) {}`
 
+
+入力ストリームが `\n` を受け取ると常に生成されます。
+通常、ユーザがエンターキーを打つと受信します。
+これは、ユーザ入力を受け取るよいフックとなります
 
+
+`line` イベントを監視する例:
 
     rl.on('line', function (cmd) {
       console.log('You just typed: '+cmd);
@@ -89,19 +148,30 @@ Example of listening for `line`:
 
 `function () {}`
 
+
+入力ストリームから `^C` または `^D` を受け取ると生成されます。
+それぞれ `SIGINT` および `EOT` として知られています。
+これは、ユーザがプログラムを終了しようとしていることを知るよい方法です。
 
+
+`close` を監視して、その後プログラムを終了する例:
 
     rl.on('close', function() {
       console.log('goodbye!');
       process.exit(0);
     });
 
+
+全てを同時に使用する方法を示す、小さなコマンドラインインタフェースの例:
 
     var readline = require('readline'),
       rl = readline.createInterface(process.stdin, process.stdout),
@@ -126,8 +196,13 @@ line interface:
     rl.setPrompt(prefix, prefix.length);
     rl.prompt();
 
-
+
+
+少しだけ複雑な[例](https://gist.github.com/901104)を見てください。
+[http-console](http://github.com/cloudhead/http-console) 
+は実際的なユースケースです。
diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown
index fe2c8b7c823c..78f65d5bdec8 100644
--- a/doc/api/repl.markdown
+++ b/doc/api/repl.markdown
@@ -1,13 +1,26 @@
 ## REPL
 
+
+Read-Eval-Print-Loop (REPL) は単独のプログラムとしても他のプログラムに手軽に取り込む形でも利用することができます。
+REPL は対話的に JavaScript を実行して結果を確認する手段を提供します。 
+デバッグやテストやその他の様々なことを試す用途で利用されます。
+
+
+コマンドラインから `node` を引数無しで実行することで、REPL プログラムに入ります。
+REPL は Emacs 風の簡易な行編集機能を備えています。
+
     mjr:~$ node
     Type '.help' for options.
     > a = [ 1, 2, 3];
@@ -19,25 +32,54 @@ dropped into the REPL. It has simplistic emacs line-editing.
     2
     3
 
+
+より進んだ行編集を行うには、環境変数に `NODE_NO_READLINE=1` を設定してnodeを起動してください。
+これによって正規の端末設定で REPL を起動し、`rlwrap` を有効にした状態でREPLを利用することができます。
+
+
+例として、bashrc ファイルに以下のように設定を追加します:
+
     alias node="env NODE_NO_READLINE=1 rlwrap node"
 
 
 ### repl.start(prompt='> ', stream=process.stdin)
 
+
+`prompt` でプロンプト記号を、 `stream` で I/O を引数に取って REPL を起動します。
+`prompt` は省略可能で、 デフォルトは `> ` です。
+`stream` は省略可能で、 デフォルトは `process.stdin` です。
+
+
+複数の REPL を起動した場合、同一の node インスタンスが実行されないことがあります。
+それぞれの REPL はグローバルオブジェクトを共有しますが、I/O は固有のものを持ちます。
+
+
+REPL を標準入力、Unix ドメインソケット、TCP ソケットのもとで起動する例を示します:
+
     var net = require("net"),
         repl = require("repl");
 
@@ -55,21 +97,45 @@ Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:
       repl.start("node via TCP socket> ", socket);
     }).listen(5001);
 
+
+このプログラムをコマンドラインから実行すると、標準入力のもとで REPL が起動します。
+他の REPL クライアントは Unix ドメインソケットか TCP ソケットを介して接続することができます。
+`telnet` が TCP ソケットへの接続に便利です。
+`socat` は Unix ドメイン /TCP 両方のソケットへの接続に利用できます。
+
+
+標準入力の代わりに Unix ドメインソケットをベースとしたサーバから REPL を起動することによって、
+再起動することなく node の常駐プロセスへ接続することができます。
+
 
 ### REPL Features
 
+
+REPL の中で Control+D を実行すると終了します。複数行に渡る式を入力とすることができます。
+
+
+特別な変数である `_` (アンダースコア) は一番最後の式の結果を保持します。
+
     > [ "a", "b", "c" ]
     [ 'a', 'b', 'c' ]
     > _.length
@@ -77,24 +143,42 @@ The special variable `_` (underscore) contains the result of the last expression
     > _ += 1
     4
 
+
+REPL はグローバルスコープに存在する全ての変数にアクセス可能です。
+それぞれの `REPLServer` に紐づく `context` オブジェクトに変数を付与することで、
+明示的に変数を公開させることが可能です。 例:
+
     // repl_test.js
     var repl = require("repl"),
         msg = "message";
 
     repl.start().context.m = msg;
 
+
+`context` オブジェクトに設定された変数は、REPL の中ではローカルな変数として現れます:
+
     mjr:~$ node repl_test.js
     > m
     'message'
 
+
+
+
+  - `.break` - 複数行に渡って式を入力している間に、途中で分からなくなったり完了させなくても良くなることがあります。`.break` で最初からやり直します。
+  - `.clear` - `context` オブジェクトを空の状態にリセットし、複数行に入力している式をクリアします。
+  - `.exit` - I/Oストリームを閉じ、REPLを終了させます。
+  - `.help` - このコマンドの一覧を表示します。
+
+
+REPL では、以下のキーコンビネーションは特別な効果を持ちます
+
+
+  - `C` - `.break` キーワードと同様です。
+  現在のコマンドを終了します。
+  強制的に終了したkれば空の行で 2 回押してください。
+  - `D` - `.exit` キーワードと同様です。
diff --git a/doc/api/stdio.markdown b/doc/api/stdio.markdown
index d4153934e451..75cdfc8ba8dd 100644
--- a/doc/api/stdio.markdown
+++ b/doc/api/stdio.markdown
@@ -1,38 +1,64 @@
 ## console
 
+
+標準出力と標準エラー出力に対するブラウザライクなオブジェクトです。
 
 ### console.log()
 
+
+改行を伴って標準出力へプリントします。
+この関数は `printf()` のように複数の引数を受け付けます。
 
     console.log('count: %d', count);
 
+
+最初の引数文字列からフォーマット要素が見つからなかった場合は、
+`util.inspect` が各引数に使われます。
 
 ### console.info()
 
+
+`console.log` と同じです。
 
 ### console.warn()
 ### console.error()
 
+
+`console.log` と同様ですが、標準エラー出力にプリントします。
 
 ### console.dir(obj)
 
+
+`util.inspect` を使って `obj` を文字列化した結果を標準エラー出力にプリントします。
 
 ### console.time(label)
 
+
+タイマを作成します。
 
 
 ### console.timeEnd(label)
 
+
+タイマを終了し、結果を出力します。例
 
     console.time('100-elements');
     for (var i = 0; i < 100; i++) {
@@ -43,9 +69,15 @@ Finish timer, record output. Example
 
 ### console.trace()
 
+
+現在のスタックトレースを標準エラー出力にプリントします。
 
 ### console.assert()
 
+
+`assert.ok()` と同じです。
 
diff --git a/doc/api/streams.markdown b/doc/api/streams.markdown
old mode 100644
new mode 100755
index 01a841a1c312..9f40a4d10c6e
--- a/doc/api/streams.markdown
+++ b/doc/api/streams.markdown
@@ -1,97 +1,209 @@
 ## Streams
 
+
+ストリームは Node の様々なオブジェクトで実装される抽象的なインタフェースです。
+例えば HTTP サーバへのリクエストは標準出力と同様にストリームです。
+ストリームは読み込み可能、書き込み可能、またはその両方です。
+全てのストリームは `EventEmitter` のインスタンスです。
+
 ## Readable Stream
 
+
+`Readable Stream` には以下のメソッド、メンバー、そしてイベントがあります。
+
 ### Event: 'data'
 
 `function (data) { }`
 
+
+`'data'` イベントは `Buffer` (デフォルト) または、
+`setEncoding()` された場合は文字列のどちらかを生成します
+
 ### Event: 'end'
 
 `function () { }`
 
+
+ストリームが EOF (TCP 用語では FIN) を受信した時に生成されます。
+`'data'` イベントがもう発生しないことを示します。
+ストリームがもし書き込み可能でもあるなら、書き込みを続けることは可能かもしれません。
+
 ### Event: 'error'
 
 `function (exception) { }`
 
+
+データ受信でエラーがあると生成されます。
+
 ### Event: 'close'
 
 `function () { }`
 
+
+下層でファイル記述子がクローズされた時に生成されます。
+全てのストリームがこのイベントを発生するわけではありません。
+(例えば、インカミングの HTTP リクエストは `'close'` イベントを生成しません。)
+
 ### Event: 'fd'
 
 `function (fd) { }`
 
+
+ストリームに関するファイル記述子を受け取った時に生成されます。
+UNIX ストリームだけがこの機能をサポートしています;
+その他の全てのストリームはこのイベントを生成しません。
+
 ### stream.readable
 
+
+デフォルトでは `true` ですが、`'error'` が発生した後、
+ストリームが `'end'` に達した後、または `destroy()` が呼ばれた後で、
+`false` に設定される boolean です。
+
 ### stream.setEncoding(encoding)
+
+data イベントが `Buffer` ではなく文字列を生成するようにします。
+`encoding` には `'utf8'`、`'ascii'`、
+または `'base64'` を指定することができます。
+
 ### stream.pause()
 
+
+`'data'` イベントの到着を中断します。
+
 ### stream.resume()
 
+
+`pause()` の後で `'data'` イベントの到着を再開します。
+
 ### stream.destroy()
 
+
+下層のファイル記述子をクローズします。ストリームはそれ以上イベントを生成しなくなります。
 
 ### stream.destroySoon()
 
+
+書き込みキューが空になった後、ファイル記述子をクローズします。
+
 ### stream.pipe(destination, [options])
 
+
+これは全ての `Stream` で利用可能な `Stream.prototype` メソッドです。
+
+
+読み込みストリームを `destination` の書き込みストリームに接続します。
+このストリームに入ってきたデータは `destination` に書き込まれます。
+接続先と接続元のストリームは、必要に応じて中断と再開することで同期を保ちます。
+
+
+この関数は `destination` ストリームを返します。
+
+
+Unix の `cat` コマンドのエミュレート:
+
     process.stdin.resume();
     process.stdin.pipe(process.stdout);
 
 
+
+デフォルトでは接続元ストリームで `end` イベントが生成されると、
+接続先の `end()` が呼ばれるので、もう書き込みはできません。
+`option` に `{ end: false }` を渡すと接続先はストリームはオープンされたままとなります。
+
+
+これは `process.stdout` をオープンしたままにして最後に "Goodbye" と出力します。
+
     process.stdin.resume();
 
     process.stdin.pipe(process.stdout, { end: false });
@@ -100,81 +212,170 @@ This keeps `process.stdout` open so that "Goodbye" can be written at the end.
       process.stdout.write("Goodbye\n");
     });
 
+
+注意: もし接続元ストリームが `pauses()` と `resume()` をサポートしない場合、
+この関数は単に `'pause'` と `'resume'` イベントを接続もとストリームで生成します。
+
 ## Writable Stream
 
+
+`Writable Stream` には以下のメソッド、メンバー、そしてイベントがあります。
+
 ### Event: 'drain'
 
 `function () { }`
 
+
+呼び出された `write()` メソッドが `false` で戻った後に生成され、
+再び安全に書き込むことができるようになったことを示します。
+
 ### Event: 'error'
 
 `function (exception) { }`
 
+
+`exception`例外によるエラーについて生成されます。
+
 ### Event: 'close'
 
 `function () { }`
 
+
+下層でファイル記述子がクローズされた時に生成されます。
+
 ### Event: 'pipe'
 
 `function (src) { }`
 
+
+このストリームが読み込み可能ストリームの pipe メソッドに渡された時に生成されます。
+
 ### stream.writable
 
+
+デフォルトでは `true` ですが、`'error'` が発生した後、
+`end()` / `destroy()` が呼ばれた後で `false` に設定される boolean です。
+
 ### stream.write(string, encoding='utf8', [fd])
 
+
+与えられた `encoding` で `string` を書き込みます。
+文字列がカーネルバッファにフラッシュされた場合は `true` が返ります。
+カーネルバッファがいっぱいの場合は、データが将来カーネルバッファに送られることを示すために、
+`false` が返ります。
+`'drain'` イベントがカーネルバッファが再び空いたことを示します。
+`encoding` のデフォルトは `'utf8'` です。
+
+
+オプションの `fd` 引数が指定されると、
+ストリームに送信するための基礎となるファイル記述子として解釈されます。
+これは UNIX ストリームでのみサポートされており、その他では黙って無視されます。
+このようにファイル記述子に書き込む場合、ストリームが流れきる前にファイル記述子をクローズすると、
+データが不正な (クローズされた) ファイル記述子に送られるリスクがあります。
+
 ### stream.write(buffer)
 
+
+生のバッファを使うこと以外は上記と同じです。
+
 ### stream.end()
 
+
+ストリームを EOF または FIN で終了します。
+
 ### stream.end(string, encoding)
 
+
+与えられた `encoding` で `string` を送信してからEOFまたはFINでストリームを終了します。
+これは送信するパケットの数を減らすために便利です。
+
 ### stream.end(buffer)
 
+
+`buffer` であること以外は上記と同じです。
+
 ### stream.destroy()
 
+
+下層のファイル記述子をクローズします。ストリームはそれ以上イベントを生成しなくなります。
+
 ### stream.destroySoon()
 
+
+
+出力キューが空になった後、ファイル記述子をクローズします。
+出力キューにデータが存在しない場合、`destroySoon()` はすぐに破棄します。
+
diff --git a/doc/api/synopsis.markdown b/doc/api/synopsis.markdown
index 53efb86fa9b2..0e138ef67980 100644
--- a/doc/api/synopsis.markdown
+++ b/doc/api/synopsis.markdown
@@ -1,8 +1,13 @@
 ## Synopsis
 
+
+'Hello World' と返答する Node で書かれたWebサーバの例:
+
     var http = require('http');
 
     http.createServer(function (request, response) {
@@ -12,10 +17,21 @@ World':
 
     console.log('Server running at http://127.0.0.1:8124/');
 
+
+このサーバを実行するには、コードを `example.js` というファイルに保存し、
+node コマンドで実行してください。
+
     > node example.js
     Server running at http://127.0.0.1:8124/
 
+
+このドキュメントの全てのサンプルは同じように実行することができます。
diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown
index 2ac02369947b..eb888782be81 100644
--- a/doc/api/timers.markdown
+++ b/doc/api/timers.markdown
@@ -2,20 +2,44 @@
 
 ### setTimeout(callback, delay, [arg], [...])
 
+
+`delay` ミリ秒が経過した後で `callback` が実行されるようにスケジュールします。
+`clearTimeout()` で使うことができる `timeoutId` を返します。
+オプションとして、コールバックへの引数を渡すこともできます。
+
 ### clearTimeout(timeoutId)
 
+
+タイムアウトがトリガーされるのを止めます。
+
 ### setInterval(callback, delay, [arg], [...])
 
+
+`delay` ミリ秒が経過するごとに繰り返し `callback` が実行されるようにスケジュールします。
+`clearInterval()` で使うことができる `intervalId` を返します。
+オプションとして、コールバックへの引数を渡すこともできます。
+
 ### clearInterval(intervalId)
 
+
+インターバルがトリガーされるのを止めます。
diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown
index e4ded41a775f..7511b4e385d6 100644
--- a/doc/api/tls.markdown
+++ b/doc/api/tls.markdown
@@ -1,37 +1,89 @@
 ## TLS (SSL)
 
+
+`require('tls')` でこのモジュールにアクセスします。
+
+
+`tls` モジュールは OpenSSL を使用することで Transport Layer Security および
+Secure Socket Layer: 暗号化されたストリーム通信を提供します。
+
+
+TLS/SSL は公開／秘密鍵を基礎とします。
+どのクライアントとサーバも秘密鍵が必要です。
+秘密鍵は次のように作成します
+
     openssl genrsa -out ryans-key.pem 1024
 
+
+全てのサーバと一部のクライアントは証明書を必要とします。
+証明書は認証局の公開鍵または自身によって署名されます。
+証明書を作成する最初のステップは「証明書署名要求 (CSR)」ファイルです。
+次のようにします:
+
     openssl req -new -key ryans-key.pem -out ryans-csr.pem
 
+
+CSR から自己署名証明書を作成するには次のようにします:
+
     openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
 
+
+他に CSR を認証局に送って署名してもらうこともできます。
+
+
+(TODO: CA を作るドキュメント、現在は興味あるユーザは Node のソースコードから
+`test/fixtures/keys/Makefile` を見る必要がある)
+
 
 ### s = tls.connect(port, [host], [options], callback)
 
+
+与えられた `port` と `host` で新しいクライアントコネクションを作成します
+(`host` のデフォルトは `localhost` です)。
+`options` は以下を指定したオブジェクトです。
+
+
+
+  - `key`: PEM フォーマットによるサーバの秘密鍵を持つ文字列または `Buffer` です (必須)。
+
+  - `cert`: PEM フォーマットによる証明書の鍵を持つ文字列または `Buffer` です。
+
+  - `ca`: 信頼できる証明書の文字列または `Buffer` の配列です。
+    省略された場合、ベリサインなどのよく知られた「ルート」認証局が使われます。
+    これらはコネクションの認証に使われます。
+
+
+`tls.connect()` は平文の `CryptoStream` オブジェクトを返します。
+
+
+TLS/SSL ハンドシェークの後で `callback` が呼び出されます。
+`callback` は証明書がサーバに認証されたかどうかに関わらず呼び出されます。
+サーバ証明書が指定した認証局に承認されたかチェックするために
+`s.authorized` を確認するかはユーザ次第です。
+`s.authorized === false`の場合、`s.authorizationError` からエラーを見つけることができます。
 
 ### STARTTLS
 
+
+v0.4 ブランチでは、既に存在する TCP コネクション上で TLS セッションを開始する機能はありません。
+それには少しの作業が必要となります。
+そのテクニックは `tls.createSecurePair()` が返す二つのストリーム:
+暗号化されたストリームと平文のストリームを使います。
+暗号化されたストリームは既存のソケットにつながれ、
+平文のストリームはその後ユーザとのインタラクションで使われます。
 
-
+[ここにそのコードがあります。](http://gist.github.com/848444)
 
 ### tls.Server
 
+
+このクラスは `net.Server` のサブクラスで、同じメソッドを持っています。
+生の TCP コネクションを受け入れる代わりに、
+TLS または SSL を使った暗号化されたコネクションを受け付けます。
+
+
+これはシンプルなエコーサーバの例です。
+
     var tls = require('tls');
     var fs = require('fs');
 
@@ -86,17 +181,30 @@ Here is a simple example echo server:
     }).listen(8000);
 
 
+
+このサーバをテストするために `openssl s_client` で接続することができます。
+
 
     openssl s_client -connect 127.0.0.1:8000
 
 
 #### tls.createServer(options, secureConnectionListener)
 
+
+`tls.Server` クラスのコンストラクタです。
+オプションのオブジェクトは以下を持つことができます。
+
+
+  - `key`: PEM フォーマットによるサーバの秘密鍵を持つ文字列または `Buffer` です (必須)。
+
+  - `cert`: PEM フォーマットによる証明書の鍵を持つ文字列または `Buffer` です (必須)。
+
+  - `ca`: 信頼できる証明書の文字列または `Buffer` の配列です。
+    省略された場合、ベリサインなどのよく知られた「ルート」認証局が使われます。
+    これらはコネクションの認証に使われます。
+
+  - `requestCert`: `true` の場合、サーバは接続しようとするクライアントからの証明書を要求します
+    デフォルトは `false` です。
+
+  - `rejectUnauthorized`: `true` の場合、
+    サーバは提供された認証局のリストによって認証されていないコネクションを破棄します．
+    このオプションは `requestCert` が `true` の場合だけ効果があります。
+    デフォルトは `false` です。
+
 
 #### Event: 'secureConnection'
 
 `function (cleartextStream) {}`
 
+
+このイベントは、新しい接続のハンドシェークが成功した場合に生成されます。
+引数は `stream.Stream` のインスタンスです。
+これはストリームに共通する全てのメソッドとイベントを持っています。
+
+
+`cleartextStream.authorized` は提供された認証局のいずれかによって認証されたかを示す boolean 値です。
+`cleartextStream.authorized` が false の場合、
+`cleartextStream.authorizationError` にはどのように認証が失敗したのかが設定されます。
+暗黙的ですが言及する価値のあること:
+TLS サーバの設定に依存しますが、認証されていないコネクションも受け入れられることがあります。
+
 
 #### server.listen(port, [host], [callback])
 
+
+指定の `port` と `host` で接続の受け入れを開始します。
+`host` が省略されると、サーバはどんな IPv4 アドレスからのコネクションも受け入れます (`INADDR_ANY`)。
+
+
+この関数は非同期です。
+最後の引数 `callback` はサーバがバインドされると呼び出されます。
+
+
+より詳細は `net.Server` を参照してください。
+
 
 #### server.close()
 
+
+サーバが新しい接続を受け入れることを終了します。
+この関数は非同期で、サーバが最終的にクローズされるとサーバは `'close'` イベントを生成します。
+
 
 #### server.maxConnections
 
+
+このプロパティを設定すると、サーバの接続数がこれを越えた場合に接続を破棄します。
+
 #### server.connections
 
+
+サーバの並行コネクションの数です。
diff --git a/doc/api/tty.markdown b/doc/api/tty.markdown
index 5ec5ee1538fe..99a03db04c7b 100644
--- a/doc/api/tty.markdown
+++ b/doc/api/tty.markdown
@@ -1,9 +1,19 @@
 ## TTY
 
+
+`require('tty')` でこのモジュールにアクセスします。
+
+
+例:
+
     var tty = require('tty');
     tty.setRawMode(true);
     process.stdin.resume();
@@ -15,36 +25,66 @@ Example:
     });
 
 
-
 ### tty.open(path, args=[])
 
+
+`path で指定された実行ファイルから新しいプロセスを新しい疑似端末のセッションリーダとして起動します。
+
+
+配列 `[slaveFD, childProcess]` を返します。
+`slaveFD` は疑似端末のスレーブ側のファイル記述子です。
+`childProcess` は子プロセスのオブジェクトです。
+
 
 ### tty.isatty(fd)
 
+
+`fd` が端末に関連づけられているかどうかを `true` または `false` で返します。
+
 
 ### tty.setRawMode(mode)
 
+
+`mode` は `true` または `false` です。
+これは現在のプロセスの標準入力ファイル記述子をローデバイスまたはデフォルトに振る舞うよう設定します。
+
 
 ### tty.setWindowSize(fd, row, col)
 
+
+ファイル記述子に関するウィンドウサイズの設定を `ioctl` します。
 
 ### tty.getWindowSize(fd)
 
+
+ファイル記述子に関連づけられた TTY の `[row, col]` を返します。
 
diff --git a/doc/api/url.markdown b/doc/api/url.markdown
index ac5b1444a309..b8d9750c5de8 100644
--- a/doc/api/url.markdown
+++ b/doc/api/url.markdown
@@ -1,14 +1,30 @@
 ## URL
 
+
+このモジュールはURLの解決や解析の為のユーティリティを持ちます。
+利用するには `require('url')` を呼び出してください。
+
+
+解析されたURLオブジェクトは、URL文字列の中に存在するかどうかに応じて
+次に示すフィールドをいくつかもしくは全てを持ちます。
+URL文字列に含まれないフィールドは解析結果のオブジェクトに含まれません。
+次のURLで例を示します。
+
 `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
 
+
+* `href`: 解析する前の完全な URL。protocol と host はどちらも小文字化されます。
+  
+  例: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
+* `protocol`: リクエストのプロトコル。小文字化されます。
+  
+  例: `'http:'`
+* `host`: URL の完全で小文字化されたホスト情報。認証情報を含みます。 
+  
+  例: `'user:pass@host.com:8080'`
+* `auth`: URL の認証情報。
+  
+  例: `'user:pass'`
+* `hostname`: ホスト情報の中の小文字化されたホスト名。
+
+  例: `'host.com'`
+* `port`: ホスト情報の中のポート番号。
+
+  例: `'8080'`
+* `pathname`: URL のパス部分。ホスト情報からクエリまでの間に位置し、最初にスラッシュが存在する場合はそれも含みます。
+
+  例: `'/p/a/t/h'`
+* `search`: URL のクエリ文字列。先頭の ? マークも含みます。
+
+  例: `'?query=string'`
+* `query`: クエリの変数部分の文字列、もしくはクエリ文字列を解析したオブジェクト。
+
+  例: `'query=string'` or `{'query':'string'}`
+* `hash`: URL の # マークを含む部分。
+
+  例: `'#hash'`
+
+
+以下のメソッドはURLモジュールにより提供されます:
+
 ### url.parse(urlStr, parseQueryString=false)
 
+
+URL文字列を引数に取り、解析結果のオブジェクトを返します。
+`querystring` モジュールを使ってクエリ文字列も解析したい場合は、
+第 2 引数に `true` を渡してください。
+
 ### url.format(urlObj)
 
+
+URL オブジェクトを引数に取り、フォーマットした URL 文字列を返します。
+
 ### url.resolve(from, to)
 
+
+ベースとなる URL と相対 URL を引数に取り、ブラウザがアンカータグに対して行うのと同様に URL を解決します。
diff --git a/doc/api/util.markdown b/doc/api/util.markdown
index fdeb5b0c4525..f0bb8a76a0bf 100644
--- a/doc/api/util.markdown
+++ b/doc/api/util.markdown
@@ -1,39 +1,85 @@
 ## util
 
+
+これらの関数はモジュール `'util'` 内にあります。
+`require('util')` を使うことでこれらにアクセスします。
+
 
 ### util.debug(string)
 
+
+同期的な出力関数です。プロセスをブロックして即座に `string` を `stderr` に出力します。
+
     require('util').debug('message on stderr');
 
 
 ### util.log(string)
 
+
+タイムスタンプとともに `stdout` へ出力します。
+
     require('util').log('Timestamped message.');
 
 
 ### util.inspect(object, showHidden=false, depth=2)
 
+
+デバッグで有用な、`object` の文字列表現を返します。
+
+
+`showHidden` が `true` の場合、
+オブジェクトの Enumerable でないプロパティも表示されます。
+
+
+`depth` が与えられた場合、
+オブジェクトをフォーマットするために何回再帰するかを `inspect` に伝えます。
+これは巨大で複雑なオブジェクトを調査する場合に便利です。
+
+
+デフォルトでは 2 回だけ再帰します。
+無限に再帰するには、`depth` に `null` を渡します。
+
+
+
+`util` オブジェクトの全てのプロパティを調査する例:
+
     var util = require('util');
 
     console.log(util.inspect(util, true, null));
@@ -41,25 +87,53 @@ Example of inspecting all properties of the `util` object:
 
 ### util.pump(readableStream, writableStream, [callback])
 
+
+実験的
+
+
+`readableStream` からデータを読み、それ を`writableStream` に送ります。
+`writableStream.write(data)` が `false` を返す場合、
+`writableStream` が `drain` イベントを生成するまで、
+`readableStream` は中断します。
+`writableStream` がクローズされるかエラーが発生すると、`callback` は error を唯一の引数として呼び出されます。
+
 
 ### util.inherits(constructor, superConstructor)
 
+
+ある
+[コンストラクタ](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor)
+からプロトタイプメソッドを継承します。
+`constructor` のプロトタイプは `superConstructor` から作られたオブジェクトに設定されます。
+
+
+さらなる利便性のために、`superConstructor` は `constructor.super_`
+プロパティを通じてアクセスすることができるようになります。
+
     var util = require("util");
     var events = require("events");
 
diff --git a/doc/api/vm.markdown b/doc/api/vm.markdown
index 2b7869da49f3..19ebe6b40741 100644
--- a/doc/api/vm.markdown
+++ b/doc/api/vm.markdown
@@ -1,19 +1,41 @@
 ## Executing JavaScript
 
+
+次のようにすることで、このモジュールにアクセスすることができます:
+
     var vm = require('vm');
 
+
+JavaScript コードは、コンパイルされてすぐに実行されるか、コンパイルおよび保存されて後から実行されます。
+
 
 ### vm.runInThisContext(code, [filename])
 
+
+`vm.runInThisContext()` は `code` を `filename` からロードされたかのようにコンパイルし、
+それを実行して結果を返します。実行されるコードはローカルスコープにアクセスしません。
+`filename` はオプションです。
+
+
+`vm.runInThisContext` と `eval` で同じコードを実行する例:
+
     var localVar = 123,
         usingscript, evaled,
         vm = require('vm');
@@ -29,23 +51,50 @@ Example of using `vm.runInThisContext` and `eval` to run the same code:
     // localVar: 123, usingscript: 1
     // localVar: 1, evaled: 1
 
+
+`vm.runInThisContext` はローカルスコープにアクセスしないので、`localVar` は変更されません。
+`eval` はローカルスコープにアクセスするので、`localVar` は変更されます。
+
+
+`code` が文法エラーとなるケースでは、`vm.runInThisContext` は標準エラーに文法エラーを出力し、
+例外をスローします。
+
 
 ### vm.runInNewContext(code, [sandbox], [filename])
 
+
+`vm.runInNewContext` は `code` を `filename` からロードされたかのようにコンパイルし、
+それを `sandbox` の中で実行して結果を返します。
+実行されるコードはローカルスコープにアクセスせず、
+`sandbox` が `code` にとってのグローバルオブジェクトとして使われます。
+`sandbox` および `filename` はオプションです。
+
+
+例: グローバル変数をインクリメントして新しい値をセットするコードをコンパイルおよび実行します。
+これらのグローバル変数はサンドボックスに含まれます。
+
     var util = require('util'),
         vm = require('vm'),
         sandbox = {
@@ -58,35 +107,79 @@ These globals are contained in the sandbox.
 
     // { animal: 'cat', count: 3, name: 'kitty' }
 
+
+慎重を要するビジネスでは、信頼できないコードの実行は細心の注意が求められることに注意してください。
+偶然グローバル変数が漏れてしまうことを防ぐために、`vm.runInNewContext` はとても役立ちますが、
+信頼できないコードを安全に実行するために別のプロセスを要求します。
+
+
+`code` が文法エラーとなるケースでは、
+`vm.runInNewContext` は標準エラーに文法エラーを出力し、例外をスローします。
+
 
 ### vm.createScript(code, [filename])
 
+
+`createScript` は `code` を
+`filename` からロードされたかのようにコンパイルしますが、実行はしません。
+代わりに、コンパイルされたコードを表現する `vm.Script` オブジェクトを返します。
+このスクリプトは後述のメソッドを使って後から何度でも実行することができます。
+返されるスクリプトはどのグローバルオブジェクトとも結びつけられていません。
+それぞれの実行前に結びつけることで、そのとおりに実行されます。
+`filename` はオプションです。
+
+
+`code` が文法エラーとなるケースでは、
+`createScript` は標準エラーに文法エラーを出力して例外をスローします。
+
 
 ### script.runInThisContext()
 
+
+`vm.runInThisContext` と同様ですが、
+こちらはプリコンパイル済みの `Script` オブジェクトのメソッドです。
+`script.runInThisContext` は `script` のコードを実行してその結果を返します。
+実行されるコードはローカルスコープにアクセスしませんが、
+`global` オブジェクト (v8: 実際のコンテキスト) にはアクセスします。
+
+
+`script.runInThisContext` を使ってコードを一度だけコンパイルし、複数回実行する例:
+
     var vm = require('vm');
 
     globalVar = 0;
@@ -104,13 +197,29 @@ Example of using `script.runInThisContext` to compile code once and run it multi
 
 ### script.runInNewContext([sandbox])
 
+
+`vm.runInNewContext` と同様ですが、
+こちらはプリコンパイル済みの `Script` オブジェクトのメソッドです。
+`script.runInNewContext` は `sandbox` がグローバルオブジェクトであるかのように
+`script` のコードを実行してその結果を返します。
+実行されるコードはローカルスコープにアクセスしません。
+`sandbox` はオプションです。
+
+
+例: グローバル変数をインクリメントしてセットするコードをコンパイルして、このコードを複数回実行します。
+これらのグローバル変数はサンドボックスに含まれます。
+
     var util = require('util'),
         vm = require('vm'),
         sandbox = {
@@ -128,6 +237,13 @@ These globals are contained in the sandbox.
 
     // { animal: 'cat', count: 12, name: 'kitty' }
 
+
+慎重を要するビジネスでは、信頼できないコードの実行は細心の注意が求められることに注意してください。
+偶然グローバル変数が漏れてしまうことを防ぐために、`script.runInNewContext` はとても役立ちますが、
+信頼できないコードを安全に実行するために別のプロセスを要求します。
diff --git a/doc/index.html b/doc/index.html
old mode 100644
new mode 100755
index 5819f6f78b46..2fd6399cf081
--- a/doc/index.html
+++ b/doc/index.html
@@ -21,6 +21,23 @@
     node.js
   
   
+    
+
+        
    
       
     
+-->
     
    
-
+      
+ 
       
       

    
       
 
+      
    
+        V8 JavaScript
+        を用いたイベント駆動I/Oの実現
+      
    
+
+      
    
+        全てのリクエストに対して"Hello World"と返答するNodeで書かれたWEBサーバの例です。
+      
    
+
 
       
     var http = require('http');
@@ -63,19 +98,31 @@
 console.log('Server running at http://127.0.0.1:1337/');
 
    
 
+      
    
+        このサーバを走らせるには、コードを
+        example.jsというファイル名で保存し、下記のように
+        nodeコマンドを実行してください。
+      
    
+
       
     % node example.js
 Server running at http://127.0.0.1:1337/
    
 
+      
    
+        また、ポート番号1337をリッスンし、何でもエコーするシンプルなTCPサーバは以下のようになります。
+      
    
+
 
       
     var net = require('net');
@@ -88,27 +135,61 @@
 server.listen(1337, "127.0.0.1");
 
    
 
+      
    
+        APIドキュメントにもっと多くのサンプルがあります。
+      
    
+
 
-
+      
    
+        Wikiにより多くの情報があります。
+      
    
+
 
+      
    紹介
    
+
 
       
 
+      
    ダウンロード
    
+
 
+      
    
+        gitリポジトリ
+      
    
+
+      
     2011.06.29 v0.4.9 (安定版)
+      
    
+
+      
     2011.07.14 v0.5.1 (開発版)
+      
    
+
+
+
+      
    過去のバージョン: 各バージョン, ドキュメント
    
+
 
+      
    
+        ビルドの方法は
+        https://github.com/joyent/node/wiki/Installation
+        を参照してください。
+      
    
+
 
-
+      
    概要
    
+
 
+      
    
+        Nodeの目標は、簡単にスケーラブルなネットワークプログラムを作成する方法を提供することです。
+        上記の"Hello World"WEBサーバの例では、多数のクライアントとの接続を同時に扱うことができます。
+        NodeはOSに、(epollやkqueue、
+        /dev/pollやselectを通じて)新しい接続が来たら知らせるように指示し、
+        スリープ状態になります。そして新しい接続があると、コールバックを実行します。
+        各接続にはほんの小さなヒープしか割り当てられません。
+      
    
+
+
+      
    
+        これは、OSのスレッドを用いる近頃のより一般的な同時実行モデルとは対照的です。
+        この手法に比べると、スレッドベースのネットワークプログラムは非効率的であり、またとても使いづらいのです。
+        ここや
+        ここをご覧ください。
 
+        Nodeは、1接続ごとに2MBのスタックメモリを割り当てるスレッドベースのシステムに比べて、
+        高負荷時にとても良いメモリ効率を実現します。
+        
+
+        さらに、Nodeのユーザはプロセスのデッドロックの心配から開放されました。Nodeにはロックがないのです。
+        Nodeには直接I/Oを実行する関数がほとんど無いため、プロセスは決してブロックされません。
+        ブロックがないため、エキスパートではないプログラマであっても高速なシステムを開発することができるのです。
+      
    
+
         
+
 
+      
    
+        Nodeは、RubyのEvent Machine
+        やPythonのTwistedの影響を受けており、
+        よく似たデザインになっています。
+        しかし、Nodeはイベントモデルをさらに推し進めています。
+        すなわち、イベントループをライブラリとして提供するのではなく、言語自体に組み込まれた構成として提供しています。
+        Node以外のシステムでは、イベントループを開始する際に必ずブロック呼び出しが存在します。
+        それらのシステムでは、一般的にスクリプトの先頭でコールバックを通じて行う動作を定義し、
+        スクリプトの最後でEventMachine::run()
+        のようなブロック呼び出しを行ってサーバを開始させています。
+        Nodeでは、そのような「イベントループの開始」呼び出しはありません。
+        Nodeは入力されたスクリプトを実行し終えるとそのままイベントループに入ります。
+        そして動作すべきコールバックがなくなるとイベントループから抜け出します。
+        こういった挙動は、ブラウザ上のJavaSciprtとおんなじです。
+        すなわち、イベントループはユーザからは隠匿されているのです。
+      
    
+
 
+      
    
+        HTTPはNodeにおける第一級のプロトコルです。NodeのHTTPライブラリは
+        作者のWEBサーバ開発における経験を脱却させました。例えば、
+        ほとんどのWEBフレームワークでは、データをストリーミングさせることができません。
+        Nodeはこの問題をHTTPパーサ
+        とAPIによって解決しようとしています。Nodeのイベント駆動な仕組みと連動させれば、
+        WEBライブラリやフレームワークのとてもよい基盤になることでしょう。
+      
    
+
 
+      
    
+        
+        でも、マルチプロセッサ環境ではどうなるんだ？
+        マルチコアのコンピュータ上でプログラムをスケールさせるためには、スレッドを使う必要があるんじゃないのか？
+        
+        マルチコアのコンピュータ上でスケールさせるのに必要なのは複数のプロセスであり、
+        共有メモリを利用するスレッドではありません。
+        スケーラブルなシステムの基本は高速なネットワーキングとブロックのないデザインであり、
+        あとはメッセージパッシングがあれば事足ります。
+        将来のバージョンで、Nodeは現在のデザインととてもよくフィットする形で子プロセスをforkする
+        ( Web Workers APIを使って)
+        ことができるようになる予定です。
+      
    
+
 
+      
    
+        これらもご覧ください:
+         
    
+      
    
+
 
 
     
    
@@ -228,10 +404,17 @@ 
    About
    
     
    
       Copyright 2010 Joyent, Inc
       
    
+
+      Node.js は Joyent, Inc の商標です。
+      詳しくは trademark policy
+      を参照してください。
     
    
+      
    
+      
    
 
     
     
     
diff --git a/doc/template.html b/doc/template.html
old mode 100644
new mode 100755
index 9127a0ddae6d..0a3ccb8b6081
--- a/doc/template.html
+++ b/doc/template.html
@@ -1,6 +1,7 @@
 
 
 
+  
   {{section}}Node.js v0.5.1 Manual & Documentation
   
   
diff --git a/doc/v0.4_announcement.html b/doc/v0.4_announcement.html
index 8ecda802cc11..d460bea9774a 100644
--- a/doc/v0.4_announcement.html
+++ b/doc/v0.4_announcement.html
@@ -14,17 +14,29 @@
     node v0.4 announcement
   
   
+    
+    
    Nodeの2番目の安定版リリース
    
 
     
    
+    
+    Wiki
+    ページに v0.2 から v0.4 の間の API の変更の詳細があります。
 
     
    
+    
+    v0.2 からの主な変更:
 
     
      
+      
+      
    •  TLS/SSL システムが大きくオーバーホールされました。
+      前のOpenSSLへのバインディングはソケットのコードに激しく混入していました。
+      このバインディングはコネクションを「ストリーム」のペアとして提示するために作り替えられました:
+      双方向の暗号化されたストリームと双方向の平文のストリームです。
+      暗号化されたストリームは、汎用目的の Stream.prototype.pipe()
+      メソッドによって生の TCP ソケットにつながれます。
+      機能は拡張されましたが、APIは単純化されました。
 
+      
+      
    • コネクションプールを備えた、よりシンプルな HTTP クライアント API。
 
+      
+      
    •  より低コストな Buffer の割り当て。
+      Node は多くの場所で Buffer オブジェクトを使用します -
+      それは割り当てが相対的に遅く、ガーベッジコレクションが困難です。
+      実装を ObjectWrap ではなく純粋な JavaScript 
+      オブジェクトに変更したことで、パフォーマンスが改善しました。
 
+      
+      
    •  多くのよい知見により、パッケージマネージャをよりよくサポートするために
+      モジュールのローディングシステムが変更されました。
+      特に NPM は、深いシンボリックリンクや require() 
+      に欠けていた機能に対処するために "shim" モジュールを強制されていました。
+      主な変更は:
       
        
+        
+        
      1. require() はリアルパスで呼び出します。
+        それはシンボリックリンクを解決します。
+        これはシンボリックリンクによるモジュールを相対的に要求することを可能にします。
 
+        
+        
      2. require() は今や最低限の package.json
+        を理解します。
+        それは main スクリプトを認識します。
+        これで require() はパッケージのディレクトリを直接扱えるようになりました。
 
+        
+        
      3. 特別な名前のディレクトリ node_modules/ は、
+        モジュールの現在のディレクトリから探されます。
+        これはグローバルな名前空間に頼るのではなく、モジュールを束にすることをプログラマに推奨します。
       
      
+      
+      この機能をより詳しく知るには モジュールのドキュメント
+      を参照してください。
 
+      
+      
    •  まだ未完成ですが、MinGW を使用したネイティブ Windows ビルドが Bert Builder によって始まりました。
+      ビルド手順は Wiki
+      にあります。
 
+      
+      
    •  Node は最新版の V8 v3.1.2 にアップグレードしました。
+      それには V8 の新しいコンパイラ・インフラストラクチャや Linux での GDB 
+      プラグインが含まれています。 
+        完全な V8 の変更履歴 を参照してください。
 
+      
+      
    • V8 デバッガの組み込みクライアントが Node に追加されました。
+      それは最低限のものですが、シンプルな作業には便利です。 紹介ビデオ
+      や ドキュメント
+      を参照してください。
 
+      
+      Brian White によって os モジュールが基本的ながら有益なシステム情報を提供するようになりました:
+      os.cpus(), os.freemem(), os.totalmem(), os.loadavg()
 
+      
+      
    • そしてもちろん、多くのバグが修正されました。
+      完全な
+        変更履歴 を参照してください。
 
     
    
 
diff --git a/tools/doctool/markdown.js b/tools/doctool/markdown.js
index 3caa2e295799..febbce5ba842 100644
--- a/tools/doctool/markdown.js
+++ b/tools/doctool/markdown.js
@@ -63,7 +63,7 @@ var Markdown = expose.Markdown = function Markdown(dialect) {
 expose.parse = function( source, dialect ) {
   // dialect will default if undefined
   var md = new Markdown( dialect );
-  return md.toTree( source );
+  return md.toTree( source.replace(//mg, '') );
 }
 
 /**