Chronicle

The chronicle package provides a convenient way to log messages and objects along with detailed information about their origin in your Dart code. It helps you track the file, class, function, line number, and column number where the log was called.

Definition

verb: record (a series or events) in a factual and detailed way.

Installation

dart pub install chronicle

Usage

To log messages and objects with detailed information, you can create an instance of the Chronicle class and pass the log message and the object you want to log. By default, the log is printed with the file, function, and line number of the Chronicle instantiation. You can customize the level of detail by using the NameDepth enum.

import 'package:chronicle/chronicle.dart';

int add(int a, int b) => a + b;

void main() {
  // Log a function as well, it will evaluate the value on runtime.
  Chronicle(StackTrace.current, "2+3", [add(2, 3)]);

  // Log a message and an object with default name depth (deep)
  Chronicle(StackTrace.current, "This is a log message", [1, 2, 3]);

  // Log with custom name depth (deeper)
  Chronicle(
    StackTrace.current,
    "This is another log message",
    [
      {'key1': 'value1', 'key2': 'value2'}
    ],
    nameDepth: NameDepth.deeper,
  );

  // Log with custom name depth (deepest)
  Chronicle(
    StackTrace.current,
    "Yet another log message",
    [
      {"name": "John Doe", "age": 30}
    ],
    nameDepth: NameDepth.deepest,
  );
}

Options

The Chronicle class accepts the following options:

• StackTrace stackTrace: The stack trace obtained from StackTrace.current method.
• String message: The log message you want to print.
• List<Object> object: A list of objects that you want to log along with the message.
• bool isError: If set to true, the log will be printed in red color, indicating an error. (Default: false)
• NameDepth nameDepth: Specifies the level of detail you want in the log name. It can be NameDepth.deep, NameDepth.deeper, or NameDepth.deepest. (Default: NameDepth.deep)
• String delimiter: The delimiter used in the log name. (Default: ':')

Customization

You can customize the level of detail in the log name by using the NameDepth enum. The options are as follows:

• NameDepth.deep: Includes the class name (if available), function name, and line number.
• NameDepth.deeper: Includes the file name, class name (if available), function name, line number, and column number.
• NameDepth.deepest: Includes the absolute file path, class name (if available), function name, line number, and column number.

Example Output

[my_file.dart:_MyClass:myFunction:42] This is a log message: 1, 2, 3
[my_file.dart:_MyClass:myFunction:69] 2+3: 5
[my_file.dart:myFunction:45] This is another log message: {key1: value1, key2: value2}
[/full/path/to/my_file.dart:_MyClass:myFunction:48] Yet another log message: {name: John Doe, age: 30}

Contribution

If you have any suggestions, improvements, or bug reports, please feel free to open an issue or submit a pull request on our GitHub repository

License

This package is released under the MIT License. Feel free to use it in your projects!