콘솔 표준

상태

이 명세는 아직 초기 작업 단계이며, 더욱 정밀하고 호환성 있는 정의로 다듬기 위해 피드백을 환영합니다. 또한 이 명세는 편집자들의 첫 번째 명세이므로, 친절하고 건설적인 의견을 부탁드립니다.

더 많은 논의를 원하시면 이슈 트래커에 참여해 주세요.

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 이 개발자 콘솔이 열리지 않았거나 존재하지 않더라도, 항상 스크립트에서 보이고 사용할 수 있도록 하는 것이 중요합니다.

웹 호환성을 위한 역사적 이유로, namespace object console 의 [[Prototype]]은 ObjectCreate(%ObjectPrototype%) 처럼 생성된 빈 객체여야 하며, %ObjectPrototype% 자체가 아닙니다.

1.1. 로깅 함수

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

condition이 true라면, 반환한다.
message를 서식 지정자가 없는 일반적인 단언 실패를 나타내는 문자열(예: "Assertion failed")로 설정한다.
data가 비어 있다면, append message를 data에 추가한다.
그렇지 않다면:
1. first를 data[0]으로 설정한다.
2. first가 문자열이 아닐 경우, prepend message를 data 앞에 추가한다.
3. 그 외의 경우:
  1. concat을 message, U+003A (:), U+0020 공백, 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의 속성들을 열로, tabularData를 행으로 하여 테이블을 만들려고 시도하고, properties를 사용할 수도 있다. 그리고 "log" logLevel로 출력한다. 만약 인수가 테이블로 해석될 수 없다면, 단순히 인수를 로그한다.

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로 설정한다.
그렇지 않다면, map[label]을 1로 설정한다.
concat을 label, U+003A (:), U+0020 공백, 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을 구현이 선택한 그룹을 나타내는 레이블로 설정한다.
groupLabel을 group의 레이블로 포함시킨다.
옵션으로, 환경이 상호작용 가능한 그룹을 지원한다면 group은 기본적으로 확장되어야 한다.
Printer("group", « group »)를 실행한다.
group을 적절한 그룹 스택에 푸시한다.

1.3.2. groupCollapsed(...`data`)

group을 새로운 그룹으로 설정한다.
data가 비어 있지 않으면 groupLabel을 Formatter(data)의 결과로 설정한다. 그렇지 않으면 groupLabel을 구현이 선택한 그룹을 나타내는 레이블로 설정한다.
groupLabel을 group의 레이블로 포함시킨다.
옵션으로, 환경이 상호작용 가능한 그룹을 지원한다면 group은 기본적으로 접혀 있어야 한다.
Printer("groupCollapsed", « group »)를 실행한다.
group을 적절한 그룹 스택에 푸시한다.

1.3.3. groupEnd()

마지막 그룹을 그룹 스택에서 팝한다.

1.4. 타이밍 함수

각 console 네임스페이스 객체는 연관된 타이머 테이블을 가지고 있으며, 이는 맵으로, 문자열에서 시간으로 매핑되며, 처음에는 비어 있다.

1.4.1. time(`label`)

연관된 타이머 테이블에 label 키가 존재하면, 반환하고, 옵션으로 이미 해당 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 공백, duration을 이어붙인 값으로 설정한다.
prepend concat을 data 앞에 추가한다.
Printer("timeLog", data)를 실행한다.

timeLog() 호출의 data 매개변수는 Logger 호출에 포함됨으로써, 사용자가 타이머 생명주기 동안 중간 타이머 로그에 추가 데이터를 쉽게 제공할 수 있도록 한다. 예시:

console.time("MyTimer");
console.timeLog("MyTimer", "Starting application up…");
// 예를 들어 복잡한 앱을 부트스트랩하는 코드가 실행될 수 있음
// ...
console.timeLog("MyTimer", "UI is setup, making API calls now");
// 여기서 여러 fetch()를 사용하여 앱에 데이터를 채울 수 있음
// ...
console.timeEnd("MyTimer");

1.4.3. timeEnd(`label`)

timerTable을 연관된 타이머 테이블로 설정한다.
startTime을 timerTable[label]로 설정한다.
timerTable[label]을 제거한다.
duration을 현재 시간과 startTime 사이의 차이를 구현 정의 형식의 문자열로 설정한다.
concat을 label, U+003A (:), U+0020 공백, duration을 이어붙인 값으로 설정한다.
Printer("timeEnd", « concat »)를 실행한다.

whatwg/console#134에서 timeEnd()와 timeLog()가 주어진 label이 연관된 타이머 테이블에 존재하지 않을 때 콘솔에 경고를 공식적으로 보고하도록 만드는 계획을 참고하세요.

2. 추상 연산 지원

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

logger 연산은 로그 레벨과 리스트 형태의 인자를 받는다. 주요 결과는 콘솔에 출력하는 구현 정의 부수 효과이다. 이 명세는 포맷 지정자를 처리하는 방법을 설명한다.

args가 비어 있다면, 반환한다.
first를 args[0]으로 설정한다.
rest를 args에서 first 다음의 모든 요소로 설정한다.
rest가 비어 있다면, Printer(logLevel, « first »)를 실행하고 반환한다.
그렇지 않으면 Printer(logLevel, Formatter(args))를 실행한다.
undefined를 반환한다.

출력은 알고리즘에서 반환하기 전에 반드시 발생해야 한다. 많은 개발자 콘솔은 마지막으로 입력된 연산의 결과를 출력한다. 이런 콘솔에서는 개발자가 console.log("hello!")를 입력하면 먼저 "hello!"를 출력하고, 그 다음 console.log 호출의 undefined 반환값을 출력한다.

Indicating that printing is done before return

2.2. Formatter(`args`)

formatter 연산은 첫 번째 인자를 나머지 인자들을 이용해 포맷하려고 시도한다. 입력 내의 포맷 지정자가 더 이상 남지 않거나 인자가 더 이상 남지 않을 때까지 포맷을 시도한다. 포맷 결과는 출력에 적합한 리스트로 반환한다.

args의 크기가 1이면 args를 반환한다.
target을 args의 첫 번째 요소로 설정한다.
current를 args의 두 번째 요소로 설정한다.
target에서 왼쪽부터 오른쪽으로 첫 번째 가능한 포맷 지정자 specifier를 찾는다.
포맷 지정자를 찾지 못했다면 args를 반환한다.
그렇지 않으면:
1. specifier가 %s면, converted를 Call(%String%, undefined, « current »)의 결과로 설정한다.
2. specifier가 %d 또는 %i면:
  1. current가 Symbol일 경우, converted를 NaN으로 설정한다.
  2. 그 외에는 converted를 Call(%parseInt%, undefined, « current, 10 »)의 결과로 설정한다.
3. specifier가 %f면:
  1. current가 Symbol일 경우, converted를 NaN으로 설정한다.
  2. 그 외에는 converted를 Call(%parseFloat%, undefined, « current »)의 결과로 설정한다.
4. specifier가 %o면, 선택적으로 converted를 current에 최적의 유용한 포맷팅을 적용한 결과로 설정한다.
5. specifier가 %O면, 선택적으로 converted를 current에 일반적인 JavaScript 객체 포맷팅을 적용한 결과로 설정한다.
6. TODO: %c 처리
7. 이전 단계에서 converted가 설정되었으면 target 내 specifier를 converted로 교체한다.
result를 리스트로, target과 args의 세 번째 이후 요소들을 포함시키도록 설정한다.
Formatter(result)를 반환한다.

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 파라미터에 고유 값을 사용하여, 함수에 따라 출력 메시지를 맞춤화할 수 있도록 한다. 그러나 일반적으로 함수들을 네 가지 범주로 묶어 출력이 비슷하게 처리된다. 이 표는 그 공통 분류를 요약한다:

분류	`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. 프린터 UX 혁신

Printer가 구현 정의이므로, 구현에서 UX 혁신이 흔하게 나타난다. 아래는 가능한 UX 개선 예시(비포괄적 목록):

동일한 출력의 중복 제거로 스팸 방지.

이 예시에서는 구현이 동일한 메시지를 묶어 배치할 뿐만 아니라, 몇 개의 메시지가 함께 배치됐는지 숫자도 제공한다.
로그 레벨 심각도로 메시지를 필터링할 수 있는 별도의 UI 제공.
별도의 UI에서 타이머 테이블, 그룹 스택 등 내부적으로 유지되는 데이터의 현재 상태 표시.
콘솔의 일부를 깜빡여서 사용자가 중요한 정보를 인지할 수 있게 함.

2.3.3. 공통 객체 형식

일반적으로 객체는 상황에 맞게 적합한 형식으로 출력된다. 이 섹션은 상황에 따라 객체가 가장 유용하게 포맷되는 일반적인 방법을 설명한다. 여기서 설명하는 포맷은 구현 정의 객체 표현에 적용되며, 최종적으로 Printer로 전달되어 실제 포맷의 부수 효과가 나타난다.

일반적인 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)