chore: more cleanups

.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

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

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

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;

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;

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;

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;

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`.

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';

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', '[email protected]');
+  logger.info('Fetched user', {Obj('user', user)});
+
+  return user;
+}

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);

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)});
+}

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;

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';

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';

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';

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: '[email protected]',
+///    email: '[email protected]',
 ///    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 {