//===-- Logger.h ------------------------------------------------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_CLANG_ANALYSIS_FLOWSENSITIVE_LOGGER_H

#define LLVM_CLANG_ANALYSIS_FLOWSENSITIVE_LOGGER_H

#include "clang/Analysis/CFG.h"

#include "llvm/Support/raw_ostream.h"

#include <memory>

namespace clang::dataflow {

// Forward declarations so we can use Logger anywhere in the framework.

class ControlFlowContext;

class TypeErasedDataflowAnalysis;

struct TypeErasedDataflowAnalysisState;

/// A logger is notified as the analysis progresses.

/// It can produce a report of the analysis's findings and how it came to them.

///

/// The framework reports key structural events (e.g. traversal of blocks).

/// The specific analysis can add extra details to be presented in context.

class Logger {

public:

  /// Returns a dummy logger that does nothing.

  static Logger &null();

  /// A logger that simply writes messages to the specified ostream in real

  /// time.

  static std::unique_ptr<Logger> textual(llvm::raw_ostream &);

  /// A logger that builds an HTML UI to inspect the analysis results.

  /// Each function's analysis is written to a stream obtained from the factory.

  static std::unique_ptr<Logger>

      html(std::function<std::unique_ptr<llvm::raw_ostream>()>);

  virtual ~Logger() = default;

  /// Called by the framework as we start analyzing a new function or statement.

  /// Forms a pair with endAnalysis().

  virtual void beginAnalysis(const ControlFlowContext &,

                             TypeErasedDataflowAnalysis &) {}

  virtual void endAnalysis() {}

  // At any time during the analysis, we're computing the state for some target

  // program point.

  /// Called when we start (re-)processing a block in the CFG.

  /// The target program point is the entry to the specified block.

  /// Calls to log() describe transferBranch(), join() etc.

  virtual void enterBlock(const CFGBlock &) {}

  /// Called when we start processing an element in the current CFG block.

  /// The target program point is after the specified element.

  /// Calls to log() describe the transfer() function.

  virtual void enterElement(const CFGElement &) {}

  /// Records the analysis state computed for the current program point.

  virtual void recordState(TypeErasedDataflowAnalysisState &) {}

  /// Records that the analysis state for the current block is now final.

  virtual void blockConverged() {}

  /// Called by the framework or user code to report some event.

  /// The event is associated with the current context (program point).

  /// The Emit function produces the log message. It may or may not be called,

  /// depending on if the logger is interested; it should have no side effects.

  void log(llvm::function_ref<void(llvm::raw_ostream &)> Emit) {

    if (!ShouldLogText)

      return;

    std::string S;

    llvm::raw_string_ostream OS(S);

    Emit(OS);

    logText(S);

  }

protected:

  /// ShouldLogText should be false for trivial loggers that ignore logText().

  /// This allows log() to skip evaluating its Emit function.

  Logger(bool ShouldLogText = true) : ShouldLogText(ShouldLogText) {}

private:

  bool ShouldLogText;

  virtual void logText(llvm::StringRef) {}

};

} // namespace clang::dataflow

#endif