src/logger.ts

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.



/**
 *  The logger module encapsulates capturing information for logging activity done in the
 * extension and proving uniform methods for presenting information and notifications to
 * the user.
 *
 * There are methods for logging at the different levels, trace, debug,info,warn,error.
 *
 * The log level can be set using the "Developer: Set Log Level" command from the Command
 * Palette.
 *
 * There are also methods to show info,warning, and error messages to the user.
 * These are separate from the log messages since it is common to have log messages
 * containing more information that is reasonable to show to the user.
 */


import * as vscode from 'vscode';


/**
 * Internal method for formatting logging category
 */
function formatCategory(category?: string) {
  return category ? `(${category})` : '';
}

/**
  * Logging class.
  *
  * Use the exported methods from this module unless you're in a test doing ~~things~~.
  *
  * This exists (as opposed to a singleton output channel) because provides *readonly* view
  * of the exports, so things like sinon.spy will break if we try to spy on module methods.
  * Instead, we can spy on the instance of this.
  */
export class Logger {
  /// the output channel to which this logger writes
  private output: vscode.LogOutputChannel;

  constructor(output: vscode.LogOutputChannel) {
    this.output = output;
  }


  /**
   * Log a message at the vscode.LogLevel.Trace level.
   * @param message data.
   * @param category optional category for the message.
   */
  trace(message: string, category?: string, ...args: any[]) {
    this.output.trace(formatCategory(category), message, ...args);
  }

  /**
   * Log a message at the vscode.LogLevel.Debug level.
   * @param message data.
   * @param category optional category for the message.
   */
  debug(message: string, category?: string, ...args: any[]) {
    this.output.debug(formatCategory(category), message, ...args);
  }

  /**
   * Log a message at the vscode.LogLevel.Info level.
   * @param message data.
   * @param category optional category for the message.
   */
  info(message: string, category?: string, ...args: any[]) {
    this.output.info(formatCategory(category), message, ...args);
  }


  /**
   * Log warning message.
   * @param message data.
   * @param category optional category for the message.
   */
  warn(message: string, category?: string, ...args: any[]) {
    this.output.warn(formatCategory(category), message, ...args);
  }


  /**
   * Log error message.
   * @param message data.
   * @param category optional category for the message.
   */
  error(message: string, category?: string, ...args: any[]) {
    this.output.error(formatCategory(category), message, ...args);
  }

  /**
   * Show Fuchsia output channel in vscode
   */
  show() {
    this.output.show();
  }
}

/**
  * Logging instance.
  *
  * Use the exported methods from this module unless you're in a test doing ~~things~~.
  *
  * This exists (as opposed to a singleton output channel) because provides *readonly* view
  * of the exports, so things like sinon.spy will break if we try to spy on module methods.
  * Instead, we can spy on the instance of this.
  */
export let logger: Logger;

/** Intializes the logger output channel to use for displaying messages to the user in the Output tab. */
export function initLogger(channel: vscode.LogOutputChannel) {
  logger = new Logger(channel);
}


/**
 * Log a message at the vscode.LogLevel.Trace level.
 * @param message data.
 * @param category optional category for the message.
 */
export function trace(message: string, category?: string, ...args: any[]) {
  logger.trace(message, category, ...args);
}

/**
 * Log a message at the vscode.LogLevel.Debug level.
 * @param message data.
 * @param category optional category for the message.
 */
export function debug(message: string, category?: string, ...args: any[]) {
  logger.debug(message, category, ...args);
}

/**
 * Log a message at the vscode.LogLevel.Info level.
 * @param message data.
 * @param category optional category for the message.
 */
export function info(message: string, category?: string, ...args: any[]) {
  logger.info(message, category, ...args);
}

/**
 * Log warning message.
 * @param message data.
 * @param category optional category for the message.
 */
export function warn(message: string, category?: string, ...args: any[]) {
  logger.warn(message, category, ...args);
}

/**
 * Log error message.
 * @param message data.
 * @param category optional category for the message.
 */
export function error(message: string, category?: string, ...args: any[]) {
  logger.error(message, category, ...args);
}

/**
 * Show output channel
 */
export function show() {
  logger.show();
}