Node.js v0.11.11 マニュアル & ドキュメンテーション

Index | View on single page | View as JSON

util

util#

Stability: 4 - API Frozen

これらの関数はモジュール 'util' 内にあります。 require('util') を使うことでこれらにアクセスします。

util モジュールは、主に Node 自身の内部 API によるニーズを満たすために設計されています。これらのユーティリティの多くはあなたのプログラムでも役に立つでしょう。しかしながら、もしこれらの機能にあなたの目的とするものが欠けているとしたら、その時はあなた自身のユーティリティを作成する時です。私たちは Node 内部の機能のために不必要などんな特性も util モジュールに加えることに関心がありません。

util.debuglog(section)#

section {String} デバッグするプログラムのセクション
Returns: {Function} ロギング関数

これは、NDOE_DEBUG 環境変数の有無に基づいて標準エラー出力に条件付きで出力する関数を作成して返します。もし section 名が環境変数に出現するなら、返される関数は console.error() と同じです。そうでなければ、何もしない関数が返されます。

例:

var debuglog = util.debuglog('foo');

var bar = 123;
debuglog('hello from foo [%d]', bar);

もしプログラムが環境 NODE_DEBUG=foo で実行されると、これは次のように出力します。

FOO 3245: hello from foo [123]

3245 はプロセス ID です。環境を設定することなく実行すると、これは出力されません。

NODE_DEBUG 環境変数はカンマ区切りで複数の値を設定することができます。たとえば、NODE_DEBUG=fs,net,tls 。

util.format(format, [...])#

最初の引数を printf のようなフォーマットとして使用して、フォーマット化された文字列を返します。

第一引数は文字列で、0 個以上の プレースホルダ を含みます。それぞれのプレースホルダは対応する引数を変換した値で置換されます。サポートするプレースホルダは:

%s - 文字列。
%d - 数値 (整数と浮動小数点数の両方)。
%j - JSON。もし引数が循環した参照を含む場合、それは'[Circular]' に置換されます。
%% - 一つのパーセント記号 ('%')。これは引数を消費しません。

プレースホルダに対応する引数が無い場合、そのプレースホルダは置換されません。

util.format('%s:%s', 'foo'); // 'foo:%s'

プレースホルダより多くの引数がある場合、余った引数は util.inspect() によって文字列化され、それらはスペース区切りで連結されます。

util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'

第一引数がフォーマット文字列ではない場合、util.format() は全ての引数をスペース区切りで連結して返します。ここの引数は util.inspect() で文字列に変換されます。

util.format(1, 2, 3); // '1 2 3'

util.log(string)#

タイムスタンプとともに stdout へ出力します。

require('util').log('Timestamped message.');

util.inspect(object, [options])#

デバッグで有用な、object の文字列表現を返します。

オプションの options オブジェクトは、フォーマット化された文字列の特定の側面を変更するために渡すことができます。

showHidden - true の場合、オブジェクトの Enumerable でないプロパティも表示されます。デフォルトは false です。

depth - オブジェクトをフォーマットするために何回再帰するかを inspect に伝えます。これは巨大で複雑なオブジェクトを調査する場合に便利です。デフォルトは 2 です。無限に再帰するには、null を渡します。

colors - true の場合、出力は ANSI カラーコードで色づけされます。デフォルトは false です。後述するように、色はカスタマイズ可能です。

customInspect - false の場合、オブジェクト独自の inspect(depth, opts) 関数は呼び出されません。デフォルトは false です。

util オブジェクトの全てのプロパティを調査する例:

var util = require('util');

console.log(util.inspect(util, { showHidden: true, depth: null }));

値はそれ自身のカスタム inspect(depth, opts) 関数を提供するかもしれません。それは呼び出される時、現在の再帰的な深さおよび util.inspect() に渡された options オブジェクトを受け取ります。

Customizing `util.inspect` colors#

util.inspect が出力する色は、(有効であれば) util.inspect.styles および util.inspect.colors オブジェクトを通じてグローバルにカスタマイズすることが可能です。

util.inspect.styles は各スタイルと util.inspect.colors に定義された色を割り当てたマッピングです。強調されるスタイルとそれらのデフォルト値は:

number (黄)
boolean (黄)
string (緑)
date (紫)
regexp (赤)
null (太字)
undefined (灰)
special - only function at this time (水色)
name (意図的にスタイル無し)

事前に定義された色は: white、grey、black、blue、cyan、 green、magenta、red、および yellow です。 bold、italic、underline、および inverse コードを使うこともできます。

オブジェクトは util.inspect() から呼び出される自前の inspect(depth) 関数を持つことができ、その結果はオブジェクトを調査するために使われます。

var util = require('util');

var obj = { name: 'nate' };
obj.inspect = function(depth) {
  return '{' + this.name + '}';
};

util.inspect(obj);
  // "{nate}"

全く別のオブジェクトを返すこともできます。戻り値の文字列は、そのオブジェクトに従ってフォーマットされます。これは JSON.stringify() の動作とよく似ています。

var obj = { foo: 'this will not show up in the inspect() output' };
obj.inspect = function(depth) {
  return { bar: 'baz' };
};

util.inspect(obj);
  // "{ bar: 'baz' }"

util.isArray(object)#

object が配列なら true を、それ以外は false を返します。

var util = require('util');

util.isArray([])
  // true
util.isArray(new Array)
  // true
util.isArray({})
  // false

util.isRegExp(object)#

object が RegExp なら true を、それ以外なら false を返します。

var util = require('util');

util.isRegExp(/some regexp/)
  // true
util.isRegExp(new RegExp('another regexp'))
  // true
util.isRegExp({})
  // false

util.isDate(object)#

object が Date なら true を、それ以外なら false を返します。

var util = require('util');

util.isDate(new Date())
  // true
util.isDate(Date())
  // false (without 'new' returns a String)
util.isDate({})
  // false

util.isError(object)#

object が Error なら true を、それ以外なら false を返します。

var util = require('util');

util.isError(new Error())
  // true
util.isError(new TypeError())
  // true
util.isError({ name: 'Error', message: 'an error occurred' })
  // false

util.inherits(constructor, superConstructor)#

あるコンストラクタからプロトタイプメソッドを継承します。 constructor のプロトタイプは superConstructor から作られたオブジェクトに設定されます。

さらなる利便性のために、superConstructor は constructor.super_ プロパティを通じてアクセスすることができるようになります。

var util = require("util");
var events = require("events");

function MyStream() {
    events.EventEmitter.call(this);
}

util.inherits(MyStream, events.EventEmitter);

MyStream.prototype.write = function(data) {
    this.emit("data", data);
}

var stream = new MyStream();

console.log(stream instanceof events.EventEmitter); // true
console.log(MyStream.super_ === events.EventEmitter); // true

stream.on("data", function(data) {
    console.log('Received data: "' + data + '"');
})
stream.write("It works!"); // Received data: "It works!"

util.debug(string)#

Stability: 0 - Deprecated: use console.error() instead.

console.error() に置き換えられて廃止予定です。

util.error([...])#

Stability: 0 - Deprecated: Use console.error() instead.