コンソール標準

ステータス

この仕様は初期段階の作業であり、より正確かつ互換性のある定義に向けて改良するためのフィードバックを歓迎します。また、これは編集者にとって初めての仕様でもあるため、ご親切かつ建設的なご意見をお願いします。

さらなる議論のため、issue trackerにご参加ください。

1. 名前空間 `console`

[Exposed=*]
namespace console { // 下記の名前空間オブジェクト要件も参照
  // ロギング
  undefined assert(optional boolean condition = false, any... data);
  undefined clear();
  undefined debug(any... data);
  undefined error(any... data);
  undefined info(any... data);
  undefined log(any... data);
  undefined table(optional any tabularData, optional sequence<DOMString> properties);
  undefined trace(any... data);
  undefined warn(any... data);
  undefined dir(optional any item, optional object? options);
  undefined dirxml(any... data);

  // カウント
  undefined count(optional DOMString label = "default");
  undefined countReset(optional DOMString label = "default");

  // グループ化
  undefined group(any... data);
  undefined groupCollapsed(any... data);
  undefined groupEnd();

  // タイミング
  undefined time(optional DOMString label = "default");
  undefined timeLog(optional DOMString label = "default", any... data);
  undefined timeEnd(optional DOMString label = "default");
};

歴史的な理由により、console は小文字になっています。

console は、開発者コンソールが開かれていない、もしくは存在しない場合でも、スクリプトから常に見えて使用可能であることが重要です。

歴史的なウェブ互換性の理由により、consoleの namespace object の[[Prototype]]は、 ObjectCreate(%ObjectPrototype%)で作成された空のオブジェクトでなければならず、 %ObjectPrototype%そのものではありません。

1.1. ロギング関数

1.1.1. assert(`condition`, ...`data`)

conditionがtrueの場合、returnする。
messageを、書式指定子を含まない一般的なアサーション失敗（例："Assertion failed"）を示す文字列とする。
dataが空の場合、append でmessageをdataに追加する。
それ以外の場合：
1. firstをdata[0]とする。
2. firstが文字列でない場合、prependでmessageをdataの先頭に追加する。
3. それ以外の場合：
  1. concatをmessage、U+003A（:）、U+0020 SPACE、およびfirstの連結とする。
  2. data[0]にconcatをセットする。
Logger("assert", data)を実行する。

1.1.2. clear()

適切なgroup stackを空にする。
環境で可能ならば、コンソールをクリアする。（不可能な場合は何もしない。）

1.1.3. debug(...`data`)

Logger("debug", data)を実行する。

1.1.4. error(...`data`)

Logger("error", data)を実行する。

1.1.5. info(...`data`)

Logger("info", data)を実行する。

1.1.6. log(...`data`)

Logger("log", data)を実行する。

1.1.7. table(`tabularData`, `properties`)

tabularDataのプロパティの列（もしくはproperties）とtabularDataの行でテーブルを構築し、logLevelを「log」として記録しようと試みる。引数が表形式として解析できない場合は、そのまま記録する。

TODO: ここは良いアルゴリズムが必要。

1.1.8. trace(...`data`)

trace は、この関数が呼び出された場所からのコールスタックの、実装定義であり、対話型の可能性もある表現であるとする。
必要に応じて、formattedData を Formatter(data) の結果とし、trace のラベルとして formattedData を組み込む。
Printer("trace", « trace ») を実行する。

スタックトレースに出力される関数の識別子は実装定義です。また、new Error().stack で表示される識別子と同じである保証はありません。

1.1.9. warn(...`data`)

Logger("warn", data)を実行する。

1.1.10. dir(`item`, `options`)

objectをitemに汎用JavaScriptオブジェクト形式を適用したものとする。
Printer("dir", « object », options)を実行する。

1.1.11. dirxml(...`data`)

finalListを新しいリスト（初期状態は空）とする。
各dataのitemについて：
1. convertedを、可能ならitemのDOMツリー表現とし、できない場合は最適な有用形式を itemに適用したものとする。
2. convertedをfinalListに追加する。
Logger("dirxml", finalList)を実行する。

1.2. カウント関数

各console 名前空間オブジェクトには、カウントマップが関連付けられている。これは、マップであり、文字列から数値への対応付けで、初期状態は空である。

1.2.1. count(`label`)

mapを関連付けられたカウントマップとする。
map[label]が存在する場合、set でmap[label]をmap[label] + 1にする。
そうでない場合、setでmap[label]を1にする。
concatをlabel、U+003A（:）、U+0020 SPACE、および ToString(map[label])の連結とする。
Logger("count", « concat »)を実行する。

1.2.2. countReset(`label`)

mapを関連付けられたカウントマップとする。
map[label]が存在する場合、set でmap[label]を0にする。
そうでない場合：
1. messageを、書式指定子を含まない「指定されたラベルに関連付けられたカウントが存在しない」ことを示す一般的な文字列とする。
2. Logger("countReset", « message »)を実行する。

1.3. グループ化関数

グループは、実装定義であり、インタラクティブである可能性のある、Printerによって生成された出力のビューであり、親よりもインデントが一段階深くなる。各console 名前空間オブジェクトには、グループスタックが関連付けられている。これはスタックであり、初期状態は空。グループスタック内の最後のグループのみがPrinterによって生成された出力を保持する。

1.3.1. group(...`data`)

groupを新しいグループとする。
dataが空でない場合、groupLabelを Formatter(data)の結果とし、空の場合は実装依存のグループラベルとする。
groupLabelをgroupのラベルとして組み込む。
任意で、環境がインタラクティブグループをサポートする場合は、groupをデフォルトで展開する。
Printer("group", « group »)を実行する。
Pushでgroupを適切なグループスタックに追加する。

1.3.2. groupCollapsed(...`data`)

groupを新しいグループとする。
dataが空でない場合、groupLabelを Formatter(data)の結果とし、空の場合は実装依存のグループラベルとする。
groupLabelをgroupのラベルとして組み込む。
任意で、環境がインタラクティブグループをサポートする場合は、groupをデフォルトで折りたたむ。
Printer("groupCollapsed", « group »)を実行する。
Pushでgroupを適切なグループスタックに追加する。

1.3.3. groupEnd()

Popでグループスタックから最後のグループを取り除く。

1.4. タイミング関数

各console 名前空間オブジェクトには、タイマーテーブルが関連付けられている。これはマップであり、文字列から時刻への対応付けで、初期状態は空である。

1.4.1. time(`label`)

関連付けられたタイマーテーブルにlabelキーのエントリが存在する場合、returnし、必要に応じてlabelのタイマーが既に開始されていることを示す警告をコンソールに表示してもよい。
そうでない場合、setで関連付けられたタイマーテーブルのlabelキーの値を現在時刻にする。

1.4.2. timeLog(`label`, ...`data`)

timerTableを関連付けられたタイマーテーブルとする。
startTimeをtimerTable[label]とする。
durationを現在時刻とstartTimeの差分を表す文字列とする。形式は実装定義とする。

"4650", "4650.69 ms", "5 seconds", "00:05" などが4650.69 msの持続時間を表示する合理的な方法例。
concatをlabel、U+003A（:）、U+0020 SPACE、およびdurationの連結とする。
Prependでconcatをdataの先頭に追加する。
Printer("timeLog", data)を実行する。

timeLog()呼び出し時のdataパラメータは Logger呼び出しに含まれるため、ユーザーがタイマーの途中経過ログに追加データを簡単に渡せます。例：

console.time("MyTimer");
console.timeLog("MyTimer", "アプリケーション起動中…");
// ここで複雑なアプリの初期化コードが走るかも
// ...
console.timeLog("MyTimer", "UIセットアップ完了、APIコール開始");
// ここでfetch()などでアプリにデータ投入
// ...
console.timeEnd("MyTimer");

1.4.3. timeEnd(`label`)

timerTableを関連付けられたタイマーテーブルとする。
startTimeをtimerTable[label]とする。
RemoveでtimerTable[label]を削除する。
durationを現在時刻とstartTimeの差分を表す文字列とする。形式は実装定義とする。
concatをlabel、U+003A（:）、U+0020 SPACE、およびdurationの連結とする。
Printer("timeEnd", « concat »)を実行する。

whatwg/console#134参照。 timeEnd()およびtimeLog()が、指定したlabelが関連付けられたタイマーテーブルに存在しない場合、コンソールに警告を正式に報告する計画。

2. 抽象操作の補助

2.1. Logger(`logLevel`, `args`)

logger操作はログレベルとリスト型の追加引数を受け取ります。主な出力は、実装定義の副作用としてコンソールに結果を表示することです。本仕様では、これを行う際の書式指定子の処理方法について説明します。

argsが空の場合、returnする。
firstをargs[0]とする。
restをargs内のfirst以降の全要素とする。
restが空の場合、 Printer(logLevel, « first »)を実行し、returnする。
それ以外の場合、Printer(logLevel, Formatter(args))を実行する。
return undefined。

印字はアルゴリズムからreturnする前に行われることが重要です。多くの開発者コンソールでは、最後に入力した操作の結果が出力されます。そうしたコンソールでconsole.log("hello!")と入力すると、まず"hello!"が表示され、その後console.log呼び出しの戻り値undefinedが表示されます。

Indicating that printing is done before return

2.2. Formatter(`args`)

formatter操作は、最初の引数を他の引数を使ってフォーマットしようとします。書式指定子が最初の引数に残っていないか、追加引数がなくなるまでフォーマットを試みます。印字に適したリスト型オブジェクトを返します。

argsのサイズが1の場合、argsをreturnする。
targetをargsの最初の要素とする。
currentをargsの2番目の要素とする。
target内の最初の書式指定子specifierを左から右へ探す。
書式指定子が見つからなければ、argsをreturnする。
それ以外の場合：
1. specifierが%sなら、 Call(%String%, undefined, « current »)の結果をconvertedとする。
2. specifierが%dまたは%iの場合：
  1. currentがSymbol型なら、convertedをNaNとする。
  2. それ以外なら、 Call(%parseInt%, undefined, « current, 10 »)の結果をconvertedとする。
3. specifierが%fの場合：
  1. currentがSymbol型なら、convertedをNaNとする。
  2. それ以外なら、 Call(%parseFloat%, undefined, « current »)の結果をconvertedとする。
4. specifierが%oなら、任意でconvertedをcurrentに最適な有用形式を適用したものとする。
5. specifierが%Oなら、任意でconvertedをcurrentに汎用JavaScriptオブジェクト形式を適用したものとする。
6. TODO: %cの処理
7. 上記のいずれかでconvertedがセットされた場合、target内のspecifierをconvertedで置換する。
resultをtargetとargsの3番目以降の要素を含むリストとする。
Formatter(result)をreturnする。

2.2.1. 書式指定子の概要

上記アルゴリズムで処理される書式指定子の概要（参考）です。

指定子	目的	型変換
`%s`	置換される要素を文字列に変換	%String%(`element`)
`%d` または `%i`	置換される要素を整数に変換	%parseInt%(`element`, 10)
`%f`	置換される要素を浮動小数点数に変換	%parseFloat%(`element`, 10)
`%o`	最適な有用形式で要素を表示	n/a
`%O`	汎用JavaScriptオブジェクト形式で要素を表示	n/a
`%c`	指定されたCSSを適用	n/a

2.3. Printer(`logLevel`, `args`[, `options`])

printer操作は実装定義です。ログレベル（深刻度）、印字する引数リスト、実装依存の書式オプションオブジェクト（任意）を受け取ります。 argsの要素は以下のいずれかです：

任意の型のJavaScriptオブジェクト
実装依存のスタックトレースやグループなどの印字可能なものの表現
汎用JavaScriptオブジェクト形式または最適な有用形式が適用されたオブジェクト

optionsオブジェクトが渡され、undefinedでもnullでもない場合、実装はoptionsを使ってargs内の要素に実装定義の書式を適用してもよいです。

実装がargsをどう印字するかは実装次第ですが、オブジェクト同士はスペースなどで区切るのが一般的です。

printer操作が呼ばれる時点で全ての書式指定子は処理済みであり、書式指定子に消費される引数はargsに含まれていません。実装の役割は単純にリストを印字することです。Printerの出力は、グループスタックが空でなければ適切なスタックの最後のグループ内にのみ表示され、空の場合はコンソールの他の場所に表示されます。

printer操作呼び出し時にコンソールが開いていない場合、実装は典型的には100件以上の範囲で実装定義の制限までメッセージをバッファし、後で表示するべきです。

2.3.1. `logLevel`の深刻度の指示

各console 関数はPrinter呼び出し時に固有のlogLevel値を使い、印字されたメッセージを関数ごとにカスタマイズできるようにします。ただし、一般的には関数を4つのカテゴリにまとめ、それぞれの出力を同様に扱う慣習があります。表はその一般的なグループ分けのまとめです：

グループ	`console` 関数	説明
log	`log()`, `trace()`, `dir()`, `dirxml()`, `group()`, `groupCollapsed()`, `debug()`, `timeLog()`	一般的なログ
info	`count()`, `info()`, `timeEnd()`	情報的なログ
warn	`warn()`, `countReset()`	ユーザーに何らかの警告を示すログ
error	`error()`, `assert()`	ユーザーにエラーを示すログ

これらのグループ分けは一般的な慣習を文書化するものであり、実装が各関数ごとに特別な挙動を提供することを制約するものではありません。以下はその例です：

ここでは、ある実装がtimeEnd()の出力を青色にし、info()はよりニュートラルな色にした例です。

A demonstration of timeEnd and info formatting differences

count()の呼び出しは常に新しい出力を表示するとは限らず、以前に出力されたカウントを更新することもあります。

A demonstration of count behavior

2.3.2. プリンターのユーザー体験の革新

Printerは実装定義なので、実装には多様なUXイノベーションが見られます。次はUX強化の一例（網羅的ではありません）：

同一出力の重複排除によるスパム防止

この例では、実装は複数の同一メッセージをまとめてバッチ処理し、まとめられたメッセージ数も表示しています。
ログレベルの深刻度ごとにメッセージをフィルタできるUIをサイドに追加
サイドUIでタイマーテーブルやグループスタックなどの内部状態を表示
重要な通知時にコンソールの一部を点滅させてユーザーに警告

2.3.3. 一般的なオブジェクト形式

通常、オブジェクトはその文脈に適した形式で印字されます。本節では、オブジェクトが文脈に合わせて最も有用になるようにフォーマットされる一般的な方法を説明します。ここで説明するフォーマットは、実装定義のオブジェクト表現に適用され、最終的にはPrinterに渡され、実際の副作用（フォーマット）が現れます。

汎用JavaScriptオブジェクト形式のオブジェクトは、汎用JavaScriptオブジェクトの展開可能な表現です。最適な有用形式のオブジェクトは、実装定義の、最大限有用かつ情報量の多いインタラクティブな表現です。

2.3.4. Node.jsでのプリンター実装例

Node.jsプラットフォームでprinter操作を最も簡単に実装する方法は、事前にフォーマットした引数をスペース区切りで結合し、stdoutやstderrへ出力することです。

[ECMASCRIPT]を用いたNode.jsでの実装例：

const util = require('util');

function print(logLevel, ...args) {
  const message = util.format(...args);

  if (logLevel === 'error') {
    process.stderr.write(message + '\n');
  } else if (logLevel === 'log' || logLevel === 'info' || logLevel === 'warn') {
    process.stdout.write(message + '\n');
  }
}

ここでは多くの処理をutil.format関数が担当します。ネストされたオブジェクトの文字列化や、非文字列引数の可読な文字列への変換（例：undefinedは"undefined"、falseは"false"）も行います：

print('log', 'duck', [{foo: 'bar'}]);     // prints: duck [ { foo: 'bar' } ]\n on stdout
print('log', 'duck', false);              // prints: duck false\n on stdout
print('log', 'duck', undefined);          // prints: duck undefined\n on stdout

2.4. コンソールへの警告の報告

コンソールへの警告を報告するには、警告の一般的な説明 descriptionが与えられたとき、実装は次の手順を実行する：

warningをdescriptionから導出した実装定義の文字列とする。
Printer("reportWarning", « warning »)を実行する。

謝辞

編集者は、この仕様への貢献に感謝します： Boris Zbarsky、 Brent S.A. Cowgill、 Brian Grinstead、 Corey Farwell、 Ian Kilpatrick、 Jeff Carpenter、 Joseph Pecoraro、 Justin Woo、 Luc Martin、 Noah Bass、 Paul Irish、 Raphaël、 Victor Costan ― みなさん本当にありがとうございました！

本標準は Terin Stock (terin@terinstock.com)、 Robert Kowalski (rok@kowalski.gd)、 Dominic Farolino (domfarolino@gmail.com) によって執筆され、 Domenic Denicola (Google, d@domenic.me) の大きな協力を得ています。

知的財産権

これは現行標準です。特許審査版に関心がある場合は現行標準審査ドラフトをご覧ください。

コンソール

概要

ステータス

1. 名前空間 console

1.1. ロギング関数

1.1.1. assert(condition, ...data)

1.1.2. clear()

1.1.3. debug(...data)

1.1.4. error(...data)

1.1.5. info(...data)

1.1.6. log(...data)

1.1.7. table(tabularData, properties)

1.1.8. trace(...data)

1.1.9. warn(...data)

1.1.10. dir(item, options)

1.1.11. dirxml(...data)

1.2. カウント関数

1.2.1. count(label)

1.2.2. countReset(label)

1.3. グループ化関数

1.3.1. group(...data)

1.3.2. groupCollapsed(...data)