chore: more cleanups

segfaultmedaddy · segfaultmedaddy · commit 17b52fa53f4c · 2024-11-05T01:52:09.000+02:00
diff --git a/.envrc.local b/.envrc.local
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,4 @@
 # Created by https://www.toptal.com/developers/gitignore/api/dart,linux,macos,direnv
-# Edit at https://www.toptal.com/developers/gitignore?templates=dart,linux,macos,direnv
 
 ### Dart ###
 # See https://www.dartlang.org/guides/libraries/private-files
@@ -15,9 +14,6 @@ pubspec.lock
 # If you don't generate documentation locally you can remove this line.
 doc/api/
 
-# dotenv environment variables file
-.env*
-
 # Avoid committing generated Javascript files:
 *.dart.js
 *.info.json      # Produced by the --dump-info flag.
@@ -30,10 +26,6 @@ doc/api/
 .flutter-plugins
 .flutter-plugins-dependencies
 
-### Dart Patch ###
-# dotenv environment variables file
-.env
-
 ### direnv ###
 .direnv
 .envrc
@@ -85,5 +77,3 @@ Temporary Items
 ### macOS Patch ###
 # iCloud generated files
 *.icloud
-
-# End of https://www.toptal.com/developers/gitignore/api/dart,linux,macos,direnv
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019-present Roman Vanesyan <roman@vanesyan.com>
+Copyright (c) 2019-present Roman Vanesyan <me@romanvanesyan.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/example/.gitignore b/example/.gitignore
diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,10 @@
+- `console_example.dart` - Shows how to set up a logger to log to the console
+- `file_example.dart` - Demonstrates how to configure log records to be written to a file
+- `file_rotation_periodic_example.dart` - Shows how to set up file logging with a time-based rotation policy
+- `file_rotation_periodic_sized_example.dart` - Shows how to set up logging to a file with size-based rotation policy
+- `global_logger_example.dart` - Demonstrates how to use a global logger
+- `global_logger_override_example.dart` - Demonstrates how to replace the default global logger
+- `hierarchy/` - Demonstrates a simple hierarchy of loggers
+- `pretty_console_example.dart` - Shows how to setup a prettified console logger with colors
+- `simple_example.dart` - Shows how to simply log to the console
+- `stdout_stderr_example.dart` - Demonstrates how to filter log records and direct them to stdout/stderr based on severity
diff --git a/example/console_example.dart b/example/console_example.dart
@@ -1,4 +1,4 @@
-/// This example shows how to setup a logger to log to console.
+/// This example shows how to set up a logger to log to the console.
 library;
 
 import 'package:strlog/formatters.dart' show TextFormatter;
diff --git a/example/file_example.dart b/example/file_example.dart
@@ -1,3 +1,4 @@
+/// This example demonstrates how to configure log records to be written to a file. The log file is never rotated.
 library;
 
 import 'package:strlog/formatters.dart' show TextFormatter;
diff --git a/example/file_rotation_periodic_example.dart b/example/file_rotation_periodic_example.dart
@@ -1,3 +1,5 @@
+/// This example shows how to set up file logging with a time-based
+/// log rotation policy.
 library;
 
 import 'dart:math' show Random;
diff --git a/example/file_rotation_periodic_sized_example.dart b/example/file_rotation_periodic_sized_example.dart
@@ -1,3 +1,5 @@
+/// This example shows how to set up logging to a file with rotation policy
+/// based on file size.
 library;
 
 import 'package:strlog/formatters.dart' show TextFormatter;
diff --git a/example/global_logger_example.dart b/example/global_logger_example.dart
@@ -1,4 +1,4 @@
-/// This example shows how to use a global logger.
+/// This example demonstrates how to use a global logger.
 library;
 
 // Import global logger as `log`.
diff --git a/example/global_logger_override_example.dart b/example/global_logger_override_example.dart
@@ -1,4 +1,4 @@
-// Examples shows how to replace the default global logger.
+// This example demonstrates how to replace the default global logger.
 library;
 
 import 'package:strlog/formatters.dart';
diff --git a/example/hierarchy/get_user.dart b/example/hierarchy/get_user.dart
@@ -0,0 +1,23 @@
+import 'package:strlog/strlog.dart'
+    show Logger, Loggable, Str, Obj, Field, DefaultLog;
+
+// A child logger of logger with namespace `strlog.example.hierarchy`.
+final logger = Logger.getLogger('strlog.example.hierarchy.get_user');
+
+class User implements Loggable {
+  const User(this.name, this.email);
+
+  final String name;
+  final String email;
+
+  @override
+  Iterable<Field> toFields() => ({Str('email', email), Str('name', name)});
+}
+
+User getUser() {
+  logger.info('Fetching user...');
+  final user = User('Roman', 'me@romanvanesyan.com');
+  logger.info('Fetched user', {Obj('user', user)});
+
+  return user;
+}
diff --git a/example/hierarchy/logger.dart b/example/hierarchy/logger.dart
@@ -0,0 +1,7 @@
+import 'package:strlog/strlog.dart' show Logger;
+import 'package:strlog/handlers.dart' show ConsoleHandler;
+import 'package:strlog/formatters.dart' show TextFormatter;
+
+// Define logger namespace
+final logger = Logger.getLogger('strlog.example.hierarchy')
+  ..handler = ConsoleHandler(formatter: TextFormatter.withDefaults().call);
diff --git a/example/hierarchy/main.dart b/example/hierarchy/main.dart
@@ -0,0 +1,20 @@
+/// This example demonstrates a simple hierarchy of loggers.
+/// All child loggers of the logger with the `strlog.example.hierarchy` namespace
+/// should propagate records to it, resulting in all records from child loggers
+/// being logged to the console.
+library;
+
+import 'package:strlog/strlog.dart' show Logger, DefaultLog, Str;
+import 'package:strlog/handlers.dart' show ConsoleHandler;
+import 'package:strlog/formatters.dart' show TextFormatter;
+import './get_user.dart';
+
+void main() {
+  // Define logger namespace
+  final logger = Logger.getLogger('strlog.example.hierarchy')
+    ..handler = ConsoleHandler(formatter: TextFormatter.withDefaults().call);
+
+  final user = getUser();
+
+  logger.info('User email', {Str('user_email', user.email)});
+}
diff --git a/example/pretty_console_example.dart b/example/pretty_console_example.dart
@@ -1,4 +1,4 @@
-/// This examples show how to setup prettified console logger.
+/// This example shows how to setup a prettified console logger.
 library;
 
 import 'dart:math' show Random;
diff --git a/example/simple_example.dart b/example/simple_example.dart
@@ -1,3 +1,6 @@
+/// This example shows how to simply log to the console.
+library;
+
 import 'dart:io' show pid;
 
 import 'package:strlog/formatters.dart';
diff --git a/example/stdout_stderr_example.dart b/example/stdout_stderr_example.dart
@@ -1,3 +1,7 @@
+/// This example demonstrates how to filter log records and direct them to stdout
+/// or stderr based on severity level.
+library;
+
 import 'dart:io' show stderr, stdout;
 import 'package:strlog/formatters.dart';
 import 'package:strlog/handlers.dart';
diff --git a/lib/handlers.dart b/lib/handlers.dart
@@ -1,5 +1,6 @@
 /// This package library provides a set of logging record handlers such as
-/// [ConsoleHandler], [MemoryHandler], [StreamHandler] and [MultiHandler].
+/// [ConsoleHandler], [MemoryHandler], [StreamHandler], [FileHandler], and
+///  [MultiHandler].
 ///
 /// To use this library in your code:
 ///
@@ -9,8 +10,7 @@
 library;
 
 export 'src/handlers/console_handler.dart';
-export 'src/handlers/file_handler/noop.dart'
-    if (dart.library.io) 'src/handlers/file_handler/io.dart';
+export 'src/handlers/file_handler/io.dart';
 export 'src/handlers/file_handler/policy.dart';
 export 'src/handlers/memory_handler.dart';
 export 'src/handlers/multi_handler.dart';
diff --git a/lib/src/fields/obj.dart b/lib/src/fields/obj.dart
@@ -10,7 +10,7 @@ final class _LazyObj extends _LazyField<Iterable<Field>?> implements Obj {
       : super(name: name, producer: producer, kind: FieldKind.object);
 }
 
-/// A field with value of custom type (i.e. class that implements
+/// A field with a value of a custom type (i.e., a class that implements 
 /// [Loggable]).
 abstract class Obj extends Field<Iterable<Field>?> {
   factory Obj(String name, Loggable? value) => _StaticObj(name, value);
@@ -19,7 +19,7 @@ abstract class Obj extends Field<Iterable<Field>?> {
       _LazyObj(name, () => producer()?.toFields());
 }
 
-/// [Loggable] provides the ability to object to be logged as part of
+/// [Loggable] provides the ability for an object to be logged as part of a
 /// logging context field set.
 ///
 /// Example:
@@ -42,11 +42,11 @@ abstract class Obj extends Field<Iterable<Field>?> {
 ///
 /// final user = User(
 ///    name: 'Roman Vanesyan',
-///    email: 'roman@vanesyan.me',
+///    email: 'me@romanvanesyan.com',
 ///    createdAt: DateTime.now());
 ///
 ///  logger
-///      .bind(Obj('user', user), DTM('authenticatedAt', DateTime.now()))
+///      .bind(Obj('user', user), DTM('authenticated_at', DateTime.now()))
 ///      .info('successfully authenticated');
 /// ```
 abstract class Loggable {
diff --git a/lib/src/handlers/file_handler/noop.dart b/lib/src/handlers/file_handler/noop.dart

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/// This example shows how to setup a logger to log to console.`
	`1`	`+/// This example shows how to set up a logger to log to the console.`
`2`	`2`	`library;`
`3`	`3`
`4`	`4`	`import 'package:strlog/formatters.dart' show TextFormatter;`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/// This example demonstrates how to configure log records to be written to a file. The log file is never rotated.`
`1`	`2`	`library;`
`2`	`3`
`3`	`4`	`import 'package:strlog/formatters.dart' show TextFormatter;`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+/// This example shows how to set up file logging with a time-based`
	`2`	`+/// log rotation policy.`
`1`	`3`	`library;`
`2`	`4`
`3`	`5`	`import 'dart:math' show Random;`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+/// This example shows how to set up logging to a file with rotation policy`
	`2`	`+/// based on file size.`
`1`	`3`	`library;`
`2`	`4`
`3`	`5`	`import 'package:strlog/formatters.dart' show TextFormatter;`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/// This example shows how to use a global logger.`
	`1`	`+/// This example demonstrates how to use a global logger.`
`2`	`2`	`library;`
`3`	`3`
`4`	`4`	// Import global logger as `log`.