sapphire-logging

A simple logging libary with a logbook for Mark-Marks/sapphire

Installation

1. Install it with wally

[dependencies]
sapphire_logging = "mark-marks/sapphire-logging@LATEST"

2. wally install
3. Extend sapphire with it

local sapphire_logging = require("@pkg/sapphire_logging")

sapphire
    :use(sapphire_logging)

API

Types

signal<T...>

type signal<T...> = {
    Root: signal_node<T...>?,

    Connect: (self: signal<T...>, Callback: (T...) -> ()) -> () -> (),
    Wait: (self: signal<T...>) -> T...,
    Once: (self: signal<T...>, Callback: (T...) -> ()) -> () -> (),
    Fire: (self: signal<T...>, T...) -> (),
    DisconnectAll: (self: signal<T...>) -> (),
}

log_type

type log_type = "info" | "debug" | "warn" | "error" | "fatal"

log

type log = {
    --- Timestamps representing when the log took place
    timestamp: {
        --- CPU time at the time of log
        clock: number,
        --- Seconds passed since the start of the UNIX epoch at the time of log
        unix: number,
    },
    --- Type of the log
    type: log_type,
    --- Message passed to the log
    msg: string,
    --- Full traceback of all function calls leading to this log
    trace: string,
}

sink

type sink = (log) -> ()

logger

type logger = {
    _debug: boolean,
    msg_out: signal<log>,
    logbook: { log },

    new: (debug: boolean?) -> logger,
    write: (self: logger, log_type: log_type, msg: string, trace: string) -> log,
    debug: (self: logger, msg: string) -> log?,
    warn: (self: logger, msg: string) -> log,
    error: (self: logger, msg: string) -> log,
    fatal: (self: logger, msg: string) -> (),

    connect_sink: (self: logger, sink: sink) -> () -> (),
}

Exports

.identifier

Readonly, extension identifier required by sapphire.

type identifier = string

.methods

Readonly

type methods = {}

.cache

Readonly, cache for sapphire_logging.get()

type cache = { [string]: logger }

.default

A default, uncached logger

type default = logger

.sinks

Default sinks, connectable with logger:connect_sink()

type sinks = {
    --- Roblox logging sink.
    roblox: sink,
}

Registered Methods

N/A

Functions

.extensions()

Readonly, required by sapphire for extension startup.

() -> ()

.get()

Gets an existing cached logger or creates a new one.

(
    identifier: string,
    debug: boolean?, -- Only applied if the logger doesn't exist
) -> logger

logger

._debug

Readonly - log debug messages?

type _debug = boolean

.msg_out

Readonly - on log signal, connect with :connect_sink()

type msg_out = signal<log>

.logbook

Readonly logbook of all logs that happened

type logbook = { log }

.new()

Creates a new logger.

(
    debug: boolean? --  Should debug messages be logged? Defaults to false
) -> logger

:write()

Writes a message to the logger. Prefer to use the logging methods instead of this.

(
    self: logger,
    log_type: log_type,
    msg: string,
    trace: string -- Full traceback of all function calls leading to this
) -> log

:info()

Writes an info to the logger.

(
    self: logger,
    msg: string
) -> log

:debug()

Writes a debug to the logger, IF logger is in debug mode.

(
    self: logger,
    msg: string
) -> log?

:warn()

Writes a warn to the logger.

(
    self: logger,
    msg: string
) -> log

:error()

Writes an error to the logger, continues execution.

(
    self: logger,
    msg: string
) -> log

:fatal()

Kills the current thread after writing a fatal to the logger.

(
    self: logger,
    msg: string
)

:connect_sink()

Connects the given sink to the loggers msg_out signal. Returns a disconnect function.

(
    self: logger,
    sink: sink
) -> () -> ()