Node.js API —— util（工具）

// 說明

    Node API 版本爲 v0.10.31。
    中文參考：http://nodeapi.ucdok.com/#/api/，http://blog.sina.com.cn/oleoneoy

    本段爲博主註解。

目錄

● 工具
    ○ util.format(format, [...])

    ○ util.debug(string)

    ○ util.error([...])

    ○ util.puts([...])

    ○ util.print([...])

    ○ util.log(string)

    ○ util.inspect(object, [options])

        ■ Customizing util.inspect colors

    ○ util.isArray(object)

    ○ util.isRegExp(object)

    ○ util.isDate(object)

    ○ util.isError(object)

    ○ util.pump(readableStream, writableStream, [callback])

    ○ util.inherits(constructor, superConstructor)

 工具

穩定性：4 - API 凍結

    這些函數在模塊 'util' 中。使用 require('util') 來訪問它們。

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

    返回一個格式化的字符串，第一個參數做爲 printf 形式的格式使用。

    第一個參數是一個包含0個或多個佔位符的字符串。每一個佔位符被它相應的參數轉換過來的值所替換。支持的佔位符：

      ● %s - 字符串。

      ● %d - 數值（包括整數和浮點數）。

      ● %j - JSON。

      ● % - 單個百分號（'%'）。這不會消耗一個參數。

    若是佔位符沒有相應的參數，它不會被替換。

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

    若是參數比佔位符更多，額外的參數均使用 util.inspect() 轉換成字符串，並將獲得的字符串使用空格分隔鏈接起來。

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

    若是第一個參數不是格式化字符串那麼 util.format() 返回一個將全部參數使用空格分隔鏈接起來的字符串。每一個參數使用 util.inspect() 轉換成字符串。

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

util.debug(string)

   一個同步輸出函數。將阻塞進程並當即向 stderr 輸出 string。

1 require('util').debug('message on stderr');

util.error([...])

   和 util.debug() 同樣，除了這將把全部參數當即輸出到 stderr。

util.puts([...])

   一個同步輸出函數。阻塞進程並將全部參數每一個都以換行符結束輸出到 stdout。

util.print([...])

   一個同步輸出函數。將阻塞進程，把全部參數鏈接成字符串而後輸出到 stdout。不在每一個參數後面添加換行符。

util.log(string)

   向 stdout 輸出時間戳。

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

util.inspect(object, [options])

    返回一個表示 object 的字符串，那對調試是頗有用的。

    能夠傳遞一個可選的 options 對象，用以改變格式化字符串的某些方面。

      ● showHidden - 若是爲 true，那麼對象的不可枚舉屬性將也能被顯示。默認爲 false。

      ● depth - 告訴 inspect 當格式化對象時遞歸多少次。這在查看很是複雜的對象時是頗有用的。默認爲2。想讓它無限遞歸傳遞 null。

      ● colors - 若是爲 true，那麼那麼輸出將使用 ANSI 顏色代碼風格。默認爲 false。顏色能夠定作，見下文。

      ● customInspect - 若是爲 false，那麼定義在正在被查看的對象上的定製 inspect() 函數將不會被調用。默認爲 true。

    查看 util 對象全部屬性的例子：

1 var util = require('util');
2 console.log(util.inspect(util, { showHidden: true, depth: null}));

    //注：

    當字符串長度大於60時會強行給每個子串換行，不然都在同一行。見reduceToSingleSgring。

Customizing util.inspect colors

    給 util.inspect 的輸出着色（若是被激活）是全局可定製的，只要經過 util.inspect.styles 和 util.inspect.colors 對象。

    util.inspect.styles 是一個爲每一個樣式分配一個 util.iinspect.colors 中的顏色的映射。高亮樣式和它們的默認值是：數值（黃色），布爾值（黃色），字符串（綠色），日期（洋紅），正則表達式（紅色），null（粗體），undefined（灰色），特殊狀況——這時候只會是函數（青色）* 屬性名（故意地不加樣式）

    預約義的顏色代號：白色，灰色，黑色，藍色，青色，綠色，洋紅和黃色。也有粗體，斜體，下劃線和反相代號。

    對象也能夠定義它們本身的 inspect(depth) 函數來讓 util.inspect() 調用並在查看對象時使用其返回結果。

1 var util = require('util');
2 
3 var obj = { name: 'nate' };
4 obj.inspect = function(depth) {
5   return '{' + this.name + '}';
6 };
7 
8 util.inspect(obj);
9   //"{nate}"

util.isArray(object)

    若是給出的「對象」是一個數組則返回 true。不然返回 false。

1 var util = require('util');
2 
3 util.isArray([])
4   // true
5 util.isArray(new Array)
6   // true
7 util.isArray({})
8   // false

util.isRegExp(object)

    若是給出的「對象」是一個正則表達式則返回 true。不然返回 false。

1 var util = require('util');
2 
3 util.isRegExp(/some regexp/)
4   // true
5 util.isRegExp(new RegExp('another regexp'))
6   // true
7 util.isRegExp({})
8   // false

util.isDate(object)

    若是給出的「對象」是一個日期則返回 true。不然返回 false。

1 var util = require('util');
2 
3 util.isDate(new Date())
4   // true
5 util.isDate(Date())
6   // false (without 'new' returns a String)
7 util.isDate({})
8   // false

util.isError(object)

    若是給出的「對象」是一個錯誤則返回 true。不然返回 false。

1 var util = require('util');
2 
3 util.isError(new Error())
4   // true
5 util.isError(new TypeError())
6   // true
7 util.isError({ name: 'Error', message: 'an error occurred' })
8   // false

util.pump(readableStream, writableStream, [callback])

穩定性：0 - 反對：使用 readableStream.pipe(writableStream)

    從 readableStream 讀取數據並將其發送到 writableStream。當 writableStream.write(data) 返回 false，readableStream 將暫停直到 writableStream 發生了 drain 事件。callback 有一個錯誤做爲它的惟一參數，且當 writableStream 關閉或錯誤發生時被調用。

util.inherits(constructor, superConstructor)

    從一個構造函數繼承原型上的方法到另外一個構造函數。constructor 的原型將設置爲一個從 superConstructor 建立的新對象。

    做爲一個附加的便利，superConstructor 能夠經過 constructor.super_ 屬性訪問。

 1 var util = require("util");
 2 var events = require("events");
 3 
 4 function MyStream() {
 5   events.EventEmitter.call(this);
 6 }
 7 
 8 util.inherits(MyStream, events.EventEmitter);
 9 
10 MyStream.prototype.write = function(data) {
11   this.emit("data", data);
12 }
13 
14 var stream = new MyStream();
15 
16 console.log(stream instance of events.EventEmitter); // true
17 console.log(MyStream.super_ === events.EventEmitter); // true
18 
19 stream.on("data", function(data) {
20   console.log('Reveived data: "' + data + '"');
21 })
22 stream.write("It works!"); // Received data: "It works!"