Console

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

1. ~IF［ %condition ~EQ ~T ］ ⇒ ~RET ◎ If condition is true, return.
2. %~message ~LET 整形~指定子を伴わない文字列であって， 表明の失敗を汎用的に指示するもの （例： `Assertion failed^l ） ◎ Let message be a string without any formatting specifiers indicating generically an assertion failure (such as "Assertion failed").
3. ~IF［ %data は`空$である ］ ⇒ %data に %~message を`付加する$ ◎ If data is empty, append message to data.

4. ~ELSE： ◎ Otherwise:

   1. %先頭 ~LET %data[ 0 ] ◎ Let first be data[0].
   2. ~IF［ %先頭 は `String$jt でない ］ ⇒ %data に %~message を`前付加する$ ◎ If first is not a String, then prepend message to data.
   3. ~ELSE ⇒ %data[ 0 ] ~SET 次を順に`連結する$ ⇒＃ %~message, `003A^U (:), `0020^U ~SPACE, %先頭 ◎ Otherwise: • Let concat be the concatenation of message, U+003A (:), U+0020 SPACE, and first. • Set data[0] to concat.
5. `Logger$A( `assert^l, %data ) ◎ Perform Logger("assert", data).

1.1.2. `clear()^m

1. 適切な`~group~stack$を`空にする$ ◎ Empty the appropriate group stack.
2. 環境にて可能なら，~consoleを~clearする（他の場合，何もしない） ◎ If possible for the environment, clear the console. (Otherwise, do nothing.)

1.1.3. `debug(...data)^m

1. `Logger$A( `debug^l, %data ) ◎ Perform Logger("debug", data).

1.1.4. `error(...data)^m

1. `Logger$A( `error^l, %data ) ◎ Perform Logger("error", data).

1.1.5. `info(...data)^m

1. `Logger$A( `info^l, %data ) ◎ Perform Logger("info", data).

1.1.6. `log(...data)^m

1. `Logger$A( `log^l, %data ) ◎ Perform Logger("log", data).

1.1.7. `table(tabularData, properties)^m

~tableを構築するよう試行した上で， `~log~level$【！%logLevel】 `log^l の下で~logする — ~tableの［ 各列は、 %tabularData の各~propからなる（または %properties を利用する）／ 各行は、 %tabularData からなる ］。 表構造として構文解析できなかった場合、 単に引数を~logすることに~fall-backする。 ◎ Try to construct a table with the columns of the properties of tabularData (or use properties) and rows of tabularData and log it with a logLevel of "log". Fall back to just logging the argument if it can’t be parsed as tabular.

未策定 — これには良い~algoが必要になる。 ◎ TODO: This will need a good algorithm.

1.1.8. `trace(...data)^m

1. %~trace ~LET ［ この関数を~callした所からの~callstack ］の表現 — `実装定義$な, 何らかの, 対話的にもなり得るような ◎ Let trace be some implementation-defined, potentially-interactive representation of the callstack from where this function was called.
2. 任意選択で ⇒ %~trace 用の~labelとして［ `Formatter$A( %data ) の結果 ］を組入れる ◎ Optionally, let formattedData be the result of Formatter(data), and incorporate formattedData as a label for trace.
3. `Printer$A( `trace^l, « %~trace » ) ◎ Perform Printer("trace", « trace »).

注記： ~stack~trace内に~printされる関数の識別子は、 `実装定義$である。 それはまた、 `new Error().stack^c 内に見られるものと同じ識別子になることは保証されない。 ◎ The identifier of a function printed in a stack trace is implementation-defined. It is also not guaranteed to be the same identifier that would be seen in new Error().stack.

1.1.9. `warn(...data)^m

1. `Logger$A( `warn^l, %data ) ◎ Perform Logger("warn", data).

1.1.10. `dir(item, options)^m

1. %~obj ~LET %item に`汎用~JS~objの整形$を適用した結果 ◎ Let object be item with generic JavaScript object formatting applied.
2. `Printer$A( `dir^l, « %~obj », %options ) ◎ Perform Printer("dir", « object », options).

1.1.11. `dirxml(...data)^m

1. %最終-~list ~LET 新たな`~list$ ◎ Let finalList be a new list, initially empty.

2. %data を成す ~EACH( %~item ) に対し： ◎ For each item of data:

   1. %変換-済み ~LET %~item の~DOM~tree表現が可能ならば それ ／ ~ELSE_ %~item に`最適に有用な整形$を適用した結果 ◎ Let converted be a DOM tree representation of item if possible; otherwise let converted be item with optimally useful formatting applied.
   2. %最終-~list に %変換-済み を付加する ◎ Append converted to finalList.
3. `Logger$A( `dirxml^l, %最終-~list ) ◎ Perform Logger("dirxml", finalList).

1.2.1. `count(label)^m

1. %~map ~LET コレの`計数~map$ ◎ Let map be the associated count map.
2. ~IF［ %~map[ %label ] ~NEQ ε ］ ⇒ %~map[ %label ] ~INCBY 1 ◎ If map[label] exists, set map[label] to map[label] + 1.
3. ~ELSE ⇒ %~map[ %label ] ~SET 1 ◎ Otherwise, set map[label] to 1.
4. %連結結果 ~LET 次を順に`連結する$ ⇒＃ %label, `003A^U (:), `0020^U ~SPACE, `ToString$A( %~map[ %label ] ) ◎ Let concat be the concatenation of label, U+003A (:), U+0020 SPACE, and ToString(map[label]).
5. `Logger$A( `count^l, « %連結結果 » ) ◎ Perform Logger("count", « concat »).

1.2.2. `countReset(label)^m

1. %~map ~LET コレの`計数~map$ ◎ Let map be the associated count map.
2. ~IF［ %~map[ %label ] ~NEQ ε ］ ⇒ %~map[ %label ] ~SET 0 ◎ If map[label] exists, set map[label] to 0.

3. ~ELSE： ◎ Otherwise:

   1. %~message ~LET 整形~指定子を伴わない文字列であって，［ %label【！the given label】 には計数は結付けられてないこと ］を汎用的に指示するもの ◎ Let message be a string without any formatting specifiers indicating generically that the given label does not have an associated count.
   2. `Logger$A( `countReset^l, « %~message » ) ◎ Perform Logger("countReset", « message »);

1.3.1. `group(...data)^m

1. %~group ~LET 新たな`~group$ ◎ Let group be a new group.
2. %~group~label ~LET ［ %data は`空$でないならば `Formatter$A( %data ) の結果 ／ ~ELSE_ 実装により選ばれる［ `~group$を表現する~label ］］ ◎ If data is not empty, let groupLabel be the result of Formatter(data). Otherwise, let groupLabel be an implementation-chosen label representing a group.
3. %~group~label を %~group 用の~labelとして組入れる ◎ Incorporate groupLabel as a label for group.
4. 任意選択で ⇒ ~IF［ 環境は対話的~groupを~supportする ］ ⇒ %~group は既定で展開されるべきである ◎ Optionally, if the environment supports interactive groups, group should be expanded by default.
5. `Printer$A( `group^l, « %~group » ) ◎ Perform Printer("group", « group »).
6. 適切な`~group~stack$に %~group を`~push$する ◎ Push group onto the appropriate group stack.

1.3.2. `groupCollapsed(...data)^m

1. %~group ~LET 新たな`~group$ ◎ Let group be a new group.
2. %~group~label ~LET ［ %data は空でないならば `Formatter$A( %data ) の結果 ／ ~ELSE_ 実装により選ばれる［ `~group$を表現する~label ］］ ◎ If data is not empty, let groupLabel be the result of Formatter(data). Otherwise, let groupLabel be an implementation-chosen label representing a group.
3. %~group~label を %~group 用の~labelとして組入れる ◎ Incorporate groupLabel as a label for group.
4. 任意選択で ⇒ ~IF［ 環境は対話的~groupを~supportする ］ ⇒ %~group は既定で畳まれるべきである ◎ Optionally, if the environment supports interactive groups, group should be collapsed by default.
5. `Printer$A( `groupCollapsed^l, « %~group » ) ◎ Perform Printer("groupCollapsed", « group »).
6. 適切な`~group~stack$に %~group を`~push$する ◎ Push group onto the appropriate group stack.

1.3.3. `groupEnd()^m

1. `~group~stack$から`~pop$する ◎ Pop the last group from the group stack.

1.4.1. `time(label)^m

1. %~timer~table ~LET コレの`~timer~table$ ◎ ↓

2. ~IF［ %~timer~table[ %label ] ~NEQ ε ］：

   1. 任意選択で ⇒ ［ ~label %label を伴う~timerは、 すでに開始された ］ことを指示する警告を~consoleに報告する
   2. ~RET
   ◎ If the associated timer table contains an entry with key label, return, optionally reporting a warning to the console indicating that a timer with label label has already been started.
3. ~ELSE ⇒ %~timer~table[ %label ] ~SET 現在の時刻 ◎ Otherwise, set the value of the entry with key label in the associated timer table to the current time.

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

1. %~timer~table ~LET コレの`~timer~table$ ◎ Let timerTable be the associated timer table.
2. %開始~時刻 ~LET %~timer~table[ %label ] ◎ Let startTime be timerTable[label].

3. %時間長 ~LET `実装定義$な書式で ( 現在の時刻 ~MINUS %開始~時刻 ) を表現している文字列 ◎ Let duration be a string representing the difference between the current time and startTime, in an implementation-defined format.

   `4650^l, `4650.69 ms^l, `5 seconds^l, `00:05^l は、 どれも 4650.69 ミリ秒間を表示する適理な仕方である。 ◎ "4650", "4650.69 ms", "5 seconds", and "00:05" are all reasonable ways of displaying a 4650.69 ms duration.

4. %連結結果 ~LET 次を順に`連結する$ ⇒＃ %label, `003A^U (:), `0020^U ~SPACE, %時間長 ◎ Let concat be the concatenation of label, U+003A (:), U+0020 SPACE, and duration.
5. %data に %連結結果 を`前付加する$ ◎ Prepend concat to data.
6. `Printer$A( `timeLog^l, %data ) ◎ Perform Printer("timeLog", data).

console.time("MyTimer");
console.timeLog("MyTimer", "Starting application up…");
/* 
何らかの
— たぶん，複階的な~appを~bootstrapするような —
~codeが走る。
◎
Perhaps some code runs to bootstrap a complex app
 */
// ...
console.timeLog("MyTimer", "UI is setup, making API calls now");
/* 
何らかの
— たぶん，~appを それ用の~dataで埋めるような —
`fetch()^c をここで行う。
◎
Perhaps some fetch()'s here filling the app with data
 */
// ...
console.timeEnd("MyTimer");

1.4.3. `timeEnd(label)^m

1. %~timer~table ~LET コレの`~timer~table$ ◎ Let timerTable be the associated timer table.
2. %開始~時刻 ~LET %~timer~table[ %label ] ◎ Let startTime be timerTable[label].
3. %~timer~table[ %label ] ~SET ε ◎ Remove timerTable[label].
4. %時間長 ~LET `実装定義$な書式で ( 現在の時刻 ~MINUS %開始~時刻 ) を表現している文字列 ◎ Let duration be a string representing the difference between the current time and startTime, in an implementation-defined format.
5. %連結結果 ~LET 次を順に`連結する$ ⇒＃ %label, `003A^U (:), `0020^U ~SPACE, %時間長 ◎ Let concat be the concatenation of label, U+003A (:), U+0020 SPACE, and duration.
6. `Printer$A( `timeEnd^l, « %連結結果 » ) ◎ Perform Printer("timeEnd", « concat »).

%~timer~table 内に所与の %label が存在しないときに， `timeEnd()$m, `timeLog()$m が正式に警告を~consoleに報告させる計画については、 課題 #134 を見よ。 ◎ See whatwg/console#134 for plans to make timeEnd() and timeLog() formally report warnings to the console when a given label does not exist in the associated timer table.

2.2.1. 各種 整形~指定子の要約

上の~algoにて処理される各種 整形-指定子を，以下に要約する（規範的でない）： ◎ The following is an informative summary of the format specifiers processed by the above algorithm.

2.3.1. ~logの厳しさ~levelの指示-法

`console$I の各~関数は、 各自に一意な値を［ `Printer^A の~call時の %logLevel ~parameter ］に利用する — それにより、 ~printする~messageを関数ごとに~custom化することを実装に許容する。 しかしながら、［ これらの関数を次の表tに要約される 4 ~groupに分けて， 同じ~groupに属する出力は同様に扱う ］ことも，共通的に実施されている： ◎ Each console function uses a unique value for the logLevel parameter when calling Printer, allowing implementations to customize each printed message depending on the function from which it originated. However, it is common practice to group together certain functions and treat their output similarly, in four broad categories. This table summarizes these common groupings:

この~group分けに意味されるのは，共通的な実施を文書化することであり、［ 各~関数~用に，次の例に見られるような特別な挙動を供すること ］に関して，実装を拘束することではない： ◎ These groupings are meant to document common practices, and do not constrain implementations from providing special behavior for each function, as in the following examples:

2.3.2. `Printer^A ~UX新機軸

`Printer$A は`実装定義$なので、 その実装には，~UX（利用者~体験）における新機軸も共通的に見られる。 ~UXの増補として，例えば次が挙げられるが、 これらに限られない： ◎ Since Printer is implementation-defined, it is common to see UX innovations in its implementations. The following is a non-exhaustive list of potential UX enhancements:

• ~spamを防止するため、 互いに一致する出力は一つに集約する。 ◎ De-duplication of identical output to prevent spam.

  この例の実装は、 互いに一致する複数の~messageを一括するのみならず， 何個の~messageが一緒に一括されたかも供する。 ◎ In this example, the implementation not only batches multiple identical messages, but also provides the number of messages that have been batched together.

• ~messageたちを~logの厳しさ~levelで絞込むことを利用者に許容するための、 脇に置かれる余分な~UI。 ◎ Extra UI off to the side allowing the user to filter messages by log level severity.

• ［ `~timer~table$, `~group~stack$, その他の内部に保守される~data ］の現在の状態を指示するための，脇に置かれる余分な~UI。 ◎ Extra UI off to the side indicating the current state of the timer table, group stack, or other internally maintained data.
• ~consoleのある部位を明滅して，利用者に何か重要なことを~alertする。 ◎ Flashing portions of the console to alert the user of something important.

2.3.3. 共通的な~obj整形-

~objは概して、 その文脈に相応しく整形されて~printされることになる。 この節では、 ~objたちが各自の文脈にて最も有用に整形されるような，共通的な仕方を述べる。 この節に述べる整形は、［ 最終的に `Printer$A に渡されることになる，`実装定義$な~obj表現 ］に適用されることに注意。 整形による実際の副作用は，そこで見えることになる。 ◎ Typically objects will be printed in a format that is suitable for their context. This section describes common ways in which objects are formatted to be most useful in their context. It should be noted that the formatting described in this section is applied to implementation-defined object representations that will eventually be passed into Printer, where the actual side effect of formatting will be seen.

`汎用~JS~objの整形@ を伴う~objとは、 汎用~JS~objの［ 展開-可能にもなり得る表現 ］である。 `最適に有用な整形@ を伴う~objとは、 ~objの［ 対話的にもなり得る`実装定義$な表現 ］であって，最大限に有用かつ参考になると判定されたものである。 ◎ An object with generic JavaScript object formatting is a potentially expandable representation of a generic JavaScript object. An object with optimally useful formatting is an implementation-defined, potentially-interactive representation of an object judged to be maximally useful and informative.

2.3.4. 例： Node.js における `Printer^A

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');
  }
}

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