Crate r3bl_simple_logger

Source
Expand description

§Why R3BL?

R3BL TUI library & suite of apps focused on developer productivity

We are working on building command line apps in Rust which have rich text user interfaces (TUI). We want to lean into the terminal as a place of productivity, and build all kinds of awesome apps for it.

  1. 🔮 Instead of just building one app, we are building a library to enable any kind of rich TUI development w/ a twist: taking concepts that work really well for the frontend mobile and web development world and re-imagining them for TUI & Rust.

    • Taking inspiration from things like React, SolidJS, Elm, iced-rs, Jetpack Compose, JSX, CSS, but making everything async (so they can be run in parallel & concurrent via Tokio).
    • Even the thread running the main event loop doesn’t block since it is async.
    • Using proc macros to create DSLs to implement something inspired by CSS & JSX.

  2. 🌎 We are building apps to enhance developer productivity & workflows.

    • The idea here is not to rebuild tmux in Rust (separate processes mux’d onto a single terminal window). Rather it is to build a set of integrated “apps” (or “tasks”) that run in the same process that renders to one terminal window.
    • Inside of this terminal window, we can implement things like “app” switching, routing, tiling layout, stacking layout, etc. so that we can manage a lot of TUI apps (which are tightly integrated) that are running in the same process, in the same window. So you can imagine that all these “app“s have shared application state. Each “app” may also have its own local application state.
    • Here are some examples of the types of “app“s we plan to build (for which this infrastructure acts as the open source engine):
      1. Multi user text editors w/ syntax highlighting.
      2. Integrations w/ github issues.
      3. Integrations w/ calendar, email, contacts APIs.

All the crates in the r3bl-open-core repo provide lots of useful functionality to help you build TUI (text user interface) apps, along w/ general niceties & ergonomics that all Rustaceans 🦀 can enjoy 🎉.

§Table of contents

§Introduction

The simplest way to use this crate to log things and simply use the logging facilities, is to use the r3bl_rs_utils_core crate, and not this crate directly.

  • Look at the r3bl_rs_utils_core::try_to_set_log_level function in the r3bl_rs_utils_core crate as the main entry point.
  • By default, logging is disabled even if you call all the functions in the file_logger module in the r3bl_rs_utils_core crate: log_debug, log_info, log_trace, etc.

§Changelog

Please check out the changelog to see how the library has evolved over time.

§Learn how these crates are built, provide feedback

To learn how we built this crate, please take a look at the following resources.

  • If you like consuming video content, here’s our YT channel. Please consider subscribing.
  • If you like consuming written content, here’s our developer site. Please consider subscribing to our newsletter.
  • If you have questions, please join our discord server.

§How to customize or change logging implementation

Under the hood the simplelog crate is forked and modified for use here.

The following are details for people who want to work on changing the underlying behavior of the logging engine itself, and not for folks who just want to use this crate.

r3bl_simple_logger provides a series of logging facilities, that can be easily combined.

  • SimpleLogger (very basic logger that logs to stdout)
  • TermLogger (advanced terminal logger, that splits to stdout/err and has color support) (can be excluded on unsupported platforms)
  • WriteLogger (logs to a given struct implementing Write, e.g. a file)
  • CombinedLogger (can be used to form combinations of the above loggers)
  • TestLogger (specialized logger for tests. Uses print!() / println!() for tests to be able to capture the output)

Only one Logger should be initialized of the start of your program through the Logger::init(...) method. For the actual calling syntax take a look at the documentation of the specific implementation(s) you want to use.

Macros§

debug
Logs a message at the debug level.
error
Logs a message at the error level.
format_description
info
Logs a message at the info level.
log
The standard logging macro.
log_enabled
Determines if a message logged at the specified level in that module will be logged.
trace
Logs a message at the trace level.
warn
Logs a message at the warn level.

Structs§

CombinedLogger
The CombinedLogger struct. Provides a Logger implementation that proxies multiple Loggers as one.
Config
Configuration for the Loggers
ConfigBuilder
Builder for the Logger Configurations (Config)
Metadata
Metadata about a log message.
MetadataBuilder
Builder for Metadata.
ParseLevelError
The type returned by from_str when the string doesn’t match any of the log levels.
Record
The “payload” of a log message.
RecordBuilder
Builder for Record.
SetLoggerError
The type returned by set_logger if set_logger has already been called.
SimpleLogger
The SimpleLogger struct. Provides a very basic Logger implementation
TermLogger
The TermLogger struct. Provides a stderr/out based Logger implementation
TestLogger
The TestLogger struct. Provides a very basic Logger implementation that may be captured by cargo.
WriteLogger
The WriteLogger struct. Provides a Logger implementation for structs implementing Write, e.g. File

Enums§

Color
The set of available colors for the terminal foreground/background.
ColorChoice
ColorChoice represents the color preferences of an end user.
FormatItem
A complete description of how to format and parse a type.
Level
An enum representing the available verbosity levels of the logger.
LevelFilter
An enum representing the available verbosity level filters of the logger.
LevelPadding
Padding to be used for logging the level
TargetPadding
Padding to be used for logging the thread id/name
TerminalMode
Specifies which streams should be used when logging
ThreadLogMode
Mode for logging the thread name or id or both.
ThreadPadding
Padding to be used for logging the thread id/name

Constants§

STATIC_MAX_LEVEL
The statically resolved maximum log level.

Traits§

Log
A trait encapsulating the operations required of a logger.
SharedLogger
Trait to have a common interface to obtain the Level of Loggers

Functions§

logger
Returns a reference to the logger.
max_level
Returns the current maximum log level.
set_boxed_logger
Sets the global logger to a Box<Log>.
set_logger
Sets the global logger to a &'static Log.
set_logger_racy⚠
A thread-unsafe version of set_logger.
set_max_level
Sets the global maximum log level.
set_max_level_racy⚠
A thread-unsafe version of set_max_level.