mirror of
https://github.com/denoland/std.git
synced 2024-11-21 20:50:22 +00:00
docs(log): document getLogger()
and Logger
This commit is contained in:
parent
ea8548602e
commit
999eaa8b9b
@ -77,6 +77,7 @@ const ENTRY_POINTS = [
|
||||
"../log/error.ts",
|
||||
"../log/info.ts",
|
||||
"../log/formatters.ts",
|
||||
"../log/get_logger.ts",
|
||||
"../media_types/mod.ts",
|
||||
"../msgpack/mod.ts",
|
||||
"../net/mod.ts",
|
||||
|
@ -4,7 +4,62 @@
|
||||
import { Logger } from "./logger.ts";
|
||||
import { state } from "./_state.ts";
|
||||
|
||||
/** Get a logger instance. If not specified `name`, get the default logger. */
|
||||
export type { Logger };
|
||||
|
||||
/**
|
||||
* Get a logger instance. If not specified `name`, get the default logger.
|
||||
*
|
||||
* @param name The name of the logger.
|
||||
* @returns The logger instance.
|
||||
*
|
||||
* @example Usage (without defined name and minimal setup)
|
||||
* ```ts
|
||||
* import { getLogger } from "@std/log/get-logger";
|
||||
* import "@std/log/setup";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* const logger = getLogger();
|
||||
* const result = logger.info("Hello world!"); // Prints "INFO Hello world!" in blue
|
||||
*
|
||||
* assertEquals(result, "Hello world!");
|
||||
* ```
|
||||
*
|
||||
* @example Usage (without defined name and custom setup)
|
||||
* ```ts
|
||||
* import { getLogger } from "@std/log/get-logger";
|
||||
* import { setup } from "@std/log/setup";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* setup({
|
||||
* handlers: {
|
||||
* console: new ConsoleHandler("DEBUG"),
|
||||
* },
|
||||
* loggers: {
|
||||
* default: {
|
||||
* level: "DEBUG",
|
||||
* handlers: ["console"],
|
||||
* },
|
||||
* },
|
||||
* });
|
||||
*
|
||||
* const logger = getLogger();
|
||||
*
|
||||
* const result = logger.info("Hello world!"); // Prints "INFO Hello world!" in blue
|
||||
*
|
||||
* assertEquals(result, "Hello world!");
|
||||
* ```
|
||||
*
|
||||
* @example Usage (with defined name)
|
||||
* ```ts
|
||||
* import { getLogger } from "@std/log/get-logger";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* const logger = getLogger("my-logger");
|
||||
* const result = logger.info("Hello world!");
|
||||
*
|
||||
* assertEquals(result, "Hello world!");
|
||||
* ```
|
||||
*/
|
||||
export function getLogger(name?: string): Logger {
|
||||
if (!name) {
|
||||
const d = state.loggers.get("default");
|
||||
|
107
log/logger.ts
107
log/logger.ts
@ -220,15 +220,39 @@ export class LogRecord {
|
||||
}
|
||||
}
|
||||
|
||||
/** Options for {@linkcode Logger}. */
|
||||
export interface LoggerOptions {
|
||||
/** The handlers to use for the logger. */
|
||||
handlers?: BaseHandler[];
|
||||
}
|
||||
|
||||
/**
|
||||
* A logger that can log messages at different levels.
|
||||
*
|
||||
* @example Usage
|
||||
* ```ts
|
||||
* import { Logger } from "@std/log/logger";
|
||||
* import { LogLevels } from "@std/log/levels";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* const logger = new Logger("example", LogLevels.INFO);
|
||||
* const result = logger.info("Hello, world!");
|
||||
*
|
||||
* assertEquals(result, "Hello, world!");
|
||||
* ```
|
||||
*/
|
||||
export class Logger {
|
||||
#level: LogLevel;
|
||||
handlers: BaseHandler[];
|
||||
readonly #loggerName: string;
|
||||
|
||||
/**
|
||||
* Constructs a new instance.
|
||||
*
|
||||
* @param loggerName The name of the logger.
|
||||
* @param levelName The name of the log level.
|
||||
* @param options The options to create a new logger.
|
||||
*/
|
||||
constructor(
|
||||
loggerName: string,
|
||||
levelName: LevelName,
|
||||
@ -239,12 +263,42 @@ export class Logger {
|
||||
this.handlers = options.handlers ?? [];
|
||||
}
|
||||
|
||||
/** Use this to retrieve the current numeric log level. */
|
||||
/**
|
||||
* Getter for the log level.
|
||||
*
|
||||
* @returns The log level.
|
||||
*
|
||||
* @example Usage
|
||||
* ```ts
|
||||
* import { Logger } from "@std/log/logger";
|
||||
* import { LogLevels } from "@std/log/levels";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* const logger = new Logger("example", LogLevels.INFO);
|
||||
* assertEquals(logger.level, LogLevels.INFO);
|
||||
* ```
|
||||
*/
|
||||
get level(): LogLevel {
|
||||
return this.#level;
|
||||
}
|
||||
|
||||
/** Use this to set the numeric log level. */
|
||||
/**
|
||||
* Setter for the log level.
|
||||
*
|
||||
* @param level The log level to set.
|
||||
*
|
||||
* @example Usage
|
||||
* ```ts
|
||||
* import { Logger } from "@std/log/logger";
|
||||
* import { LogLevels } from "@std/log/levels";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* const logger = new Logger("example", LogLevels.INFO);
|
||||
* logger.level = LogLevels.DEBUG;
|
||||
*
|
||||
* assertEquals(logger.level, LogLevels.DEBUG);
|
||||
* ```
|
||||
*/
|
||||
set level(level: LogLevel) {
|
||||
try {
|
||||
this.#level = getLevelByName(getLevelName(level));
|
||||
@ -253,13 +307,62 @@ export class Logger {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Getter for the name of the log level.
|
||||
*
|
||||
* @returns The name of the log level.
|
||||
*
|
||||
* @example Usage
|
||||
* ```ts
|
||||
* import { Logger } from "@std/log/logger";
|
||||
* import { LogLevels } from "@std/log/levels";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* const logger = new Logger("example", LogLevels.INFO);
|
||||
* assertEquals(logger.levelName, "INFO");
|
||||
* ```
|
||||
*/
|
||||
get levelName(): LevelName {
|
||||
return getLevelName(this.#level);
|
||||
}
|
||||
|
||||
/**
|
||||
* Setter for the name of the log level.
|
||||
*
|
||||
* @param levelName The name of the log level to set.
|
||||
*
|
||||
* @example Usage
|
||||
* ```ts
|
||||
* import { Logger } from "@std/log/logger";
|
||||
* import { LogLevels } from "@std/log/levels";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* const logger = new Logger("example", LogLevels.INFO);
|
||||
* logger.levelName = "DEBUG";
|
||||
*
|
||||
* assertEquals(logger.level, LogLevels.DEBUG);
|
||||
* ```
|
||||
*/
|
||||
set levelName(levelName: LevelName) {
|
||||
this.#level = getLevelByName(levelName);
|
||||
}
|
||||
|
||||
/**
|
||||
* Getter for the name of the logger.
|
||||
*
|
||||
* @returns The name of the logger.
|
||||
*
|
||||
* @example Usage
|
||||
* ```ts
|
||||
* import { Logger } from "@std/log/logger";
|
||||
* import { LogLevels } from "@std/log/levels";
|
||||
* import { assertEquals } from "@std/assert/equals";
|
||||
*
|
||||
* const logger = new Logger("example", LogLevels.INFO);
|
||||
*
|
||||
* assertEquals(logger.loggerName, "example");
|
||||
* ```
|
||||
*/
|
||||
get loggerName(): string {
|
||||
return this.#loggerName;
|
||||
}
|
||||
|
Loading…
Reference in New Issue
Block a user