Merge pull request #3 from mitchtreece/dev

1.3.0 Release

Author: mitchtreece

Demo/Demo/AppDelegate.swift

@@ -15,7 +15,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
                      didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
 
         // Lumberjack
-                
+                        
         Lumberjack.buildAndRegister(loggerWithId: "custom") { logger in
 
             logger.symbol = .just("📱")

Demo/Demo/CustomHook.swift

@@ -9,7 +9,8 @@ import Lumberjack
 
 struct CustomHook: MessageHook {
 
-    func hook(_ message: Message) -> MessageHookResult {
+    func hook(message: Message,
+              from logger: Logger) -> MessageHookResult {
 
         if ((0...10).randomElement() ?? 0) == 10 {
             print("🎲 [LUCKY] Custom hook says: \"you feelin lucky punk?\" 🤠")

README.md

@@ -65,6 +65,8 @@ as-well-as equivalent logger instance counterparts:
 
 ```swift
 LOG(...)    → logger.log(...)
+PROXY(...)  → logger.proxy(...)
+TRACE(...)  → logger.trace(...)
 DEBUG(...)  → logger.debug(...)
 INFO(...)   → logger.info(...)
 NOTICE(...) → logger.notice(...)
@@ -81,7 +83,7 @@ The top-level `Lumberjack` object houses several global settings, as-well-as eas
 
 ```swift
 Lumberjack
-    .verbosity = .just(.error)
+    .verbosityOverride = .just(.error)
 
 Lumberjack
     .defaultLogger
@@ -153,6 +155,7 @@ class CustomViewController: UIViewController {
 
         self.logger = Logger { make in
 
+            make.verbosity = .full
             make.symbol = .just("📱")
             make.category = "CustomView"
             make.components = .simple
@@ -245,7 +248,8 @@ import Lumberjack
 
 struct SaveMessageHook: MessageHook {
 
-    func hook(_ message: Message) -> MessageHookResult {
+    func hook(message: Message, 
+              from logger: Logger) -> MessageHookResult {
 
         save(message)
         return .next
@@ -292,7 +296,8 @@ import Lumberjack
 
 struct PrintMessageHook: MessageHook {
 
-    func hook(_ message: Message) -> MessageHookResult {
+    func hook(message: Message, 
+              from logger: Logger) -> MessageHookResult {
 
         if shouldPrint(message) {
 

Sources/Lumberjack/Hooks/Hooks/GuardHook.swift

@@ -24,8 +24,11 @@ public struct GuardHook: MessageHook {
         self.condition = condition
     }
 
-    public func hook(_ message: Message) -> MessageHookResult {
+    public func hook(message: Message,
+                     from logger: Logger) -> MessageHookResult {
+        
         return self.condition(message) ? .next : .stop
+        
     }
 
 }

Sources/Lumberjack/Hooks/Hooks/_PrintHook.swift

@@ -13,10 +13,14 @@ internal struct _PrintHook: MessageHook {
         return "Print"
     }
 
-    func hook(_ message: Message) -> MessageHookResult {
+    func hook(message: Message,
+              from logger: Logger) -> MessageHookResult {
 
-        if shouldPrint(message) {
+        if shouldPrint(message, from: logger) {
 
+            // TODO: Migrate to OSLog, or let the user decide
+            // between a logging system: print _or_ OSLog
+            
             print(message.body(formatted: true))
 
             return .next
@@ -27,9 +31,14 @@ internal struct _PrintHook: MessageHook {
 
     }
 
-    private func shouldPrint(_ message: Message) -> Bool {
+    private func shouldPrint(_ message: Message,
+                             from logger: Logger) -> Bool {
+        
+        let verbosity = (Lumberjack.verbosityOverride != nil) ?
+            Lumberjack.verbosityOverride! :
+            logger.configuration.verbosity
 
-        switch Lumberjack.verbosity {
+        switch verbosity {
         case .none:
 
             return false

Sources/Lumberjack/Hooks/MessageHook.swift

@@ -19,11 +19,13 @@ public protocol MessageHook {
     ///
     /// - Parameters:
     ///   - message: The hooked message.
+    ///   - logger: The source logger instance.
     ///
     /// - Returns: A continuation result that either passes the
     /// message onto additional hooks, _or_ stops the chain and
     /// prevents the message from being logged.
-    func hook(_ message: Message) -> MessageHookResult
+    func hook(message: Message,
+              from logger: Logger) -> MessageHookResult
 
 }
 

Sources/Lumberjack/LogLevel.swift

@@ -14,23 +14,26 @@ public enum LogLevel: Int, Identifiable, Comparable, CaseIterable {
         return lhs.rawValue < rhs.rawValue
     }
 
+    /// A trace log level.
+    case trace    = 0
+    
     /// A debug log level.
-    case debug    = 0
+    case debug    = 1
 
     /// An info log level.
-    case info     = 1
+    case info     = 2
 
     /// A notice log level.
-    case notice   = 2
+    case notice   = 3
 
     /// A warning log level.
-    case warning  = 3
+    case warning  = 4
 
     /// An error log level.
-    case error    = 4
+    case error    = 5
 
     /// A fatal log level.
-    case fatal    = 5
+    case fatal    = 6
 
     /// The log level's identifier.
     public var id: Int {
@@ -40,6 +43,7 @@ public enum LogLevel: Int, Identifiable, Comparable, CaseIterable {
     internal var name: String {
 
         switch self {
+        case .trace:    return "trace"
         case .debug:    return "debug"
         case .info:     return "info"
         case .notice:   return "notice"
@@ -53,6 +57,7 @@ public enum LogLevel: Int, Identifiable, Comparable, CaseIterable {
     internal var symbol: String {
 
         switch self {
+        case .trace:   return "🟤"
         case .debug:   return "⚪️"
         case .info:    return "🟣"
         case .notice:  return "🟡"
@@ -66,12 +71,13 @@ public enum LogLevel: Int, Identifiable, Comparable, CaseIterable {
     internal var systemImageName: String {
 
         switch self {
-        case .debug:   return "0.circle"
-        case .info:    return "1.circle"
-        case .notice:  return "2.circle"
-        case .warning: return "3.circle"
-        case .error:   return "4.circle"
-        case .fatal:   return "5.circle"
+        case .trace:   return "0.circle"
+        case .debug:   return "1.circle"
+        case .info:    return "2.circle"
+        case .notice:  return "3.circle"
+        case .warning: return "4.circle"
+        case .error:   return "5.circle"
+        case .fatal:   return "6.circle"
         }
 
     }

Sources/Lumberjack/LogVerbosity.swift

@@ -0,0 +1,35 @@
+//
+//  File.swift
+//  
+//
+//  Created by Mitch Treece on 12/7/23.
+//
+
+import Foundation
+
+/// Representation of the various logger verbosity modes.
+public enum LogVerbosity {
+    
+    /// An empty (none) verbosity mode.
+    case none
+    
+    /// A verbosity mode over a single log level.
+    case just(LogLevel)
+    
+    /// A verbosity mode up-to (and including) a log level.
+    ///
+    /// ```
+    /// .upTo(.notice) == [.trace, .debug, .info, .notice]
+    /// ```
+    case upTo(LogLevel)
+    
+    /// A verbosity mode up-from (and including) a log level.
+    /// ```
+    /// .upFrom(.warning) == [.warning, .error]
+    /// ```
+    case upFrom(LogLevel)
+    
+    /// A full verbosity mode.
+    case full
+    
+}

Sources/Lumberjack/Logger/Logger+Builder.swift

@@ -13,6 +13,9 @@ public extension Logger /* Builder */ {
     /// configurable components of a logger.
     struct Builder {
 
+        /// The logger's verbosity mode.
+        public var verbosity: LogVerbosity?
+        
         /// The logger's symbol.
         public var symbol: LogSymbol?
 
@@ -55,6 +58,7 @@ public extension Logger /* Builder */ {
         let defaultConfig = Configuration()
 
         var config = Configuration()
+        config.verbosity = builder.verbosity ?? defaultConfig.verbosity
         config.symbol = builder.symbol ?? defaultConfig.symbol
         config.category = builder.category ?? defaultConfig.category
         config.components = builder.components ?? defaultConfig.components

Sources/Lumberjack/Logger/Logger+Configuration.swift

@@ -13,6 +13,9 @@ public extension Logger /* Configuration */ {
     /// configurable components of a logger.
     struct Configuration {
 
+        /// The logger's verbosity mode.
+        public var verbosity: LogVerbosity
+        
         /// The logger's symbol.
         public var symbol: LogSymbol
 
@@ -22,32 +25,35 @@ public extension Logger /* Configuration */ {
         /// The logger's message components.
         public var components: MessageComponentSet
 
+        /// The logger's message hooks.
+        public var hooks = [any MessageHook]()
+        
         /// The logger's timestamp format.
         public var timestampFormat: String {
             didSet {
                 updateDateFormatter()
             }
         }
 
-        /// The logger's hooks.
-        public var hooks = [any MessageHook]()
-        
         internal let dateFormatter = DateFormatter()
 
         /// Initializes a logger configuration.
         ///
         /// - Parameters:
+        ///   - verbosity: The logger's verbosity mode.
         ///   - symbol: The logger's symbol.
         ///   - category: The logger's category.
         ///   - components: The logger's message components.
         ///   - timestampFormat: The logger's timestamp format.
-        ///   - hooks: The logger's hooks.
-        public init(symbol: LogSymbol = .default,
+        ///   - hooks: The logger's message hooks.
+        public init(verbosity: LogVerbosity = .full,
+                    symbol: LogSymbol = .default,
                     category: String? = nil,
                     components: MessageComponentSet = .default,
                     timestampFormat: String = "yyyy-MM-dd'T'HH:mm:ss.SSS",
                     hooks: [any MessageHook] = []) {
 
+            self.verbosity = verbosity
             self.symbol = symbol
             self.category = category
             self.components = components

Sources/Lumberjack/Logger/Logger.swift

@@ -113,8 +113,10 @@ public class Logger: Equatable {
 
         for hook in hooks {
 
-            let result = hook
-                .hook(_message)
+            let result = hook.hook(
+                message: _message,
+                from: self
+            )
 
             _message.append(
                 hook: hook.name,
@@ -167,6 +169,37 @@ public class Logger: Equatable {
 
     }
 
+    /// Logs a trace message.
+    ///
+    /// - Parameters:
+    ///   - message: The message to log.
+    ///   - symbol: An override symbol to use for the message.
+    ///   - category: An override category to use for the message.
+    ///   - file: The calling function.
+    ///   - function: The calling function.
+    ///   - line: The calling line number.
+    ///
+    /// - Returns: The logged message.
+    @discardableResult
+    public func trace(_ message: String,
+                      symbol: String? = nil,
+                      category: String? = nil,
+                      file: String = #fileID,
+                      function: String = #function,
+                      line: UInt = #line) -> Message {
+        
+        return log(
+            message,
+            level: .trace,
+            symbol: symbol,
+            category: category,
+            file: file,
+            function: function,
+            line: line
+        )
+                          
+    }
+    
     /// Logs a debug message.
     ///
     /// - Parameters: