First commit

Author: tataruRobert

.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+/.build
+/Packages
+xcuserdata/
+DerivedData/
+.swiftpm/configuration/registries.json
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.netrc
+.swiftpm/xcode/

LICENSE

@@ -0,0 +1,35 @@
+// swift-tools-version: 6.0
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SwiftLogOSLogHandler",
+    platforms: [ .iOS(.v14), .macOS(.v10_13)],
+    products: [
+        // Products define the executables and libraries a package produces, making them visible to other packages.
+        .library(
+            name: "SwiftLogOSLogHandler",
+            targets: ["SwiftLogOSLogHandler"]),
+    ],
+    dependencies: [
+        .package(
+            url: "https://github.com/apple/swift-log.git",
+            from: "1.6.1"
+        )
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products from dependencies.
+        .target(
+            name: "SwiftLogOSLogHandler",
+            dependencies: [
+                .product(name: "Logging", package: "swift-log")
+            ]
+        ),
+        .testTarget(
+            name: "SwiftLogOSLogHandlerTests",
+            dependencies: ["SwiftLogOSLogHandler"]
+        ),
+    ]
+)

Package.resolved

@@ -0,0 +1,173 @@
+# SwiftLogOSLogHandler
+
+**SwiftLogOSLogHandler** is a logging backend for Apple’s [swift-log](https://github.com/apple/swift-log). It integrates with Apple’s [OSLog](https://developer.apple.com/documentation/os/logging) Unified Logging system and provides advanced string interpolation for flexible, compile-time-controlled logging.
+
+---
+
+## Features
+
+- **Apple Unified Logging Integration**: Leverage OSLog for optimized, structured, and categorized logging.
+- **Advanced String Interpolation**: Customize log messages with options like privacy, formatting, alignment, and more.
+
+---
+
+## Installation
+
+### Swift Package Manager
+
+To include **SwiftLogOSLogHandler** in your project, add it to your `Package.swift` file:
+
+```swift
+let package = Package(
+    name: "YourProject",
+    platforms: [
+        .iOS(.v14),
+        .macOS(.v10_13)
+    ],
+    dependencies: [
+        .package(
+            url: "git@github.com:TechArtists/ios-swift-log-os-log-handler.git",
+            from: "1.0.0"
+        )
+    ],
+    targets: [
+        .target(
+            name: "YourTarget",
+            dependencies: [
+                .product(name: "SwiftLogOSLogHandler", package: "SwiftLogOSLogHandler")
+            ]
+        )
+    ]
+)
+```
+Alternatively, to add the package using Xcode:
+
+    1. Navigate to File > Add Packages.
+    2. Enter the repository URL: `git@github.com:TechArtists/ios-swift-log-os-log-handler.git`.
+    3. Add the package to your target.
+## Usage
+
+To effectively utilize logging in your application, initialize and manage your loggers using the `init(label: String, factory: (String) -> any LogHandler)` method of the `Logger`. This method allows for versatile logging configurations, making it easy to combine `SwiftLogOSLogHandler` with other logging handlers, such as file-based handlers, using the `MultiplexLogHandler`.
+
+```swift
+import Logging
+import Foundation
+import SwiftLogFileLogHandler
+import SwiftLogOSLogHandler
+
+enum Loggers {
+    static let main = Logging.Logger(label: "main") { label in
+        MultiplexLogHandler([
+            SwiftLogOSLogHandler(label: label, shouldLogCallsiteMetadata: true),
+            SwiftLogFileLogHandler(label: label)
+        ])
+    }
+    
+    static let onboarding = Logging.Logger(label: "onboarding") { label in
+        MultiplexLogHandler([
+            SwiftLogOSLogHandler(label: label),
+            SwiftLogFileLogHandler(label: label)
+        ])
+    }
+}
+
+Loggers.main.info("Welcome Main Logger")
+Loggers.onboarding.info("Welcome Onboarding logger")
+
+// Output
+// Main: Welcome Main Logger
+// Onboarding: Welcome Onboarding logger
+
+```
+
+## Differences Between `SwiftLogOSLogHandler` and `OS_log`
+
+While `SwiftLogOSLogHandler` provides a convenient bridge to integrate Apple's OSLog system with the Swift logging API, there are some important distinctions to consider when choosing between using this library and using `OS_log` directly:
+
+### Performance
+
+- **OSlog Optimizations**: The native `OSlog` API is optimized for performance, offering efficient logging capabilities that are tailored specifically for Apple's operating systems. This includes direct support for various log levels, privacy controls, and more, with minimal overhead.
+- **SwiftLogOSLogHandler Efficiency**: Using `SwiftLogOSLogHandler` introduces some overhead compared to directly using `OSlog`, due to the additional layer that bridges Swift's logging system with `OSlog`. However, this trade-off is generally acceptable for many applications that benefit from the streamlined logging API provided by `swift-log`.
+
+### Call Site Accuracy
+
+- **OS_log Call Site**: The native `OSlog` accurately captures the call site information (file, function, line) and associates this metadata directly with each log entry.
+- **SwiftLogOSLogHandler Call Site**: Due to the way Swift’s logging system interacts with `OS_log`, the call site information will not reflect the actual source of the log message but rather the location within the handler itself. To compensate for this, `SwiftLogOSLogHandler` offers a `shouldLogCallsiteMetadata` parameter. When enabled, this option appends call site metadata directly into your log messages in the format: `[File: \(file), Function: \(function), Line: \(line)]`:
+
+```swift
+let main = SwiftLogOSLogHandler(label: "example", shouldLogCallsiteMetadata: true)
+
+// Example Log Message
+main.info("Important action performed")
+
+// Output
+// Important action performed [File: Example.swift, Function: performAction, Line: 42]
+```
+
+### Advanced String Interpolation with `taMessage`
+
+The `taMessage` parameter allows for enhanced string interpolation in log messages, including:
+- **Privacy Options**: Use `.public` or `.private` to control the visibility of log message content.
+- **Formatting**: Apply formatting options such as `.fixed` for numeric precision.
+- **Alignment**: Define alignment and column width for text.
+
+**Example Usage**:
+
+```swift
+let testString = "Performance Test"
+let cpuUsage = 89.57
+
+Loggers.main.info(taMessage: "\(testString, privacy: .public)")
+Loggers.main.error(taMessage: "High CPU usage: \(cpuUsage, format: .fixed(precision: 2), align: .left(columns: 10))%")
+Loggers.main.critical(taMessage: "System health critical. \(UUID(), privacy: .private) CPU: \(cpuUsage, privacy: .public)")
+Loggers.main.notice(taMessage: "Running maintenance. Task ID: \(UUID(), privacy: .public)")
+```
+
+**Example Output**:
+
+```
+Performance Test [File: SystemMonitor.swift, Function: checkPerformance, Line: 120]
+High CPU usage: <redacted>%
+System health critical. <redacted> CPU: 89.57
+Running maintenance. Task ID: 5E6A10C8-45F0-4923-8C28-3A6C8D17F7AA
+```
+
+### Logging with Bootstrapping
+
+To ensure all logs are effectively captured and routed through the desired logging backend, you need to bootstrap the logging system. Bootstrapping associates a specific handler, such as `SwiftLogOSLogHandler`, to all `Logger` instances created thereafter.
+
+Here’s how to configure OSLog as the universal backend by bootstrapping the logging system:
+
+```swift
+import Logging
+import SwiftLogOSLogHandler
+
+// Bootstrap the logging system with OSLog as the handler.
+LoggingSystem.bootstrap { label in
+    SwiftLogOSLogHandler(label: label)
+}
+
+// Create a Logger instance after bootstrapping.
+let loggerMain = Logger(label: "Main")
+
+// Log messages using the logger instance.
+// These messages will now be routed and handled by the bootstrapped SwiftLogOSLogHandler.
+loggerMain.info("Application started successfully.")
+loggerMain.warning("Low disk space detected.")
+```
+
+**OSLog Output**:
+```
+Main: info: Application started successfully.
+Main: warning: Low disk space detected.
+```
+
+### Important Considerations
+
+- **Bootstrap Before Using Loggers**: Ensure that you bootstrap the logging system *before* creating any `Logger` instances. Loggers created prior to bootstrapping will not be associated with the specified backend and may not output logs as expected.
+  
+- **Universal Handling**: Once you bootstrap with `SwiftLogOSLogHandler`, all subsequent `Logger` instances in your application will use OSLog, ensuring consistent and centralized logging behavior.
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for more details.

Package.swift

@@ -0,0 +1,36 @@
+//
+//  LogInterpolation+Formatting.swift
+//  TALogger
+//
+//  Created by Robert Tataru on 01.10.2024.
+//
+
+
+public enum LogBoolFormatting: Sendable {
+    /// Displays an interpolated boolean value as true or false.
+    case truth
+    /// Displays an interpolated boolean value as yes or no.
+    case answer
+}
+
+public enum LogStringAlignment: Sendable {
+    case none
+    case left(columns: Int)
+    case right(columns:  Int)
+}
+
+public enum LogFloatFormatting: Sendable {
+    case fixed(precision: Int, explicitPositiveSign: Bool)
+    
+    public static func fixed(explicitPositiveSign: Bool = false, precision: Int = 6) -> LogFloatFormatting {
+        .fixed(precision: precision, explicitPositiveSign: explicitPositiveSign)
+    }
+}
+
+public enum LogIntegerFormatting: Sendable {
+    case decimal(minDigits: Int, explicitPositiveSign: Bool)
+    
+    public static func decimal(explicitPositiveSign: Bool = false, minDigits: Int = 0) -> Self {
+        .decimal(minDigits: minDigits, explicitPositiveSign: explicitPositiveSign)
+    }
+}

README.MD

@@ -0,0 +1,46 @@
+//
+//  LogPrivacy.swift
+//  TALogger
+//
+//  Created by Robert Tataru on 01.10.2024.
+//
+
+public enum LogPrivacy: Equatable, Sendable {
+    public enum Mask: Equatable, Sendable {
+        case hash
+        case none
+    }
+    
+    case `public`
+    case `private`(mask: Mask = .none)
+    
+    #if DEBUG
+    nonisolated(unsafe) internal static var disableRedaction: Bool = true
+    #endif
+    
+    internal static let redacted: String = "<redacted>"
+    
+    /// Returns the string representation of the value based on the privacy settings.
+    ///
+    /// - Parameter value: The value to be processed.
+    /// - Returns: A string that is either the original value, its hash, or a redacted placeholder.
+    public func value(for value: Any) -> String {
+        #if DEBUG
+        if Self.disableRedaction {
+            return String(describing: value)
+        }
+        #endif
+        
+        switch self {
+        case .public:
+            return String(describing: value)
+        case .private(let mask):
+            switch mask {
+            case .hash:
+                return "\(String(describing: value).hash)"
+            case .none:
+                return Self.redacted
+            }
+        }
+    }
+}

Sources/SwiftLogOSLogHandler/LogInterpolation/LogInterpolation+Formatting.swift

@@ -0,0 +1,36 @@
+//
+//  Untitled.swift
+//  TALogger
+//
+//  Created by Robert Tataru on 01.10.2024.
+//
+
+public extension TAMessage.LogStringInterpolation {
+    public mutating func appendInterpolation(_ argumentString: @Sendable @autoclosure @escaping () -> String, align: LogStringAlignment = .none, privacy: LogPrivacy = .private()) {
+        addInterpolationType(.string(argumentString, alignment: align, privacy: privacy))
+    }
+    
+    public mutating func appendInterpolation<T>(_ value: @Sendable @autoclosure @escaping () -> T, align: LogStringAlignment = .none, privacy: LogPrivacy = .private()) where T: CustomStringConvertible {
+        addInterpolationType(.stringConvertible(value, alignment: align, privacy: privacy))
+    }
+    
+    public mutating func appendInterpolation<T: SignedInteger>(_ number: @Sendable @autoclosure @escaping () -> T, format: LogIntegerFormatting = .decimal(), align: LogStringAlignment = .none, privacy: LogPrivacy = .private()) {
+        addInterpolationType(.signedInt({ Int64(number()) }, format: format, alignment: align, privacy: privacy))
+    }
+
+    public mutating func appendInterpolation<T: UnsignedInteger>(_ number: @Sendable @autoclosure @escaping () -> T, format: LogIntegerFormatting = .decimal(), align: LogStringAlignment = .none, privacy: LogPrivacy = .private()) {
+        addInterpolationType(.unsignedInt({ UInt64(number()) }, format: format, alignment: align, privacy: privacy))
+    }
+    
+    public mutating func appendInterpolation(_ number: @Sendable @autoclosure @escaping () -> Float, format: LogFloatFormatting = .fixed(), align: LogStringAlignment = .none, privacy: LogPrivacy = .private()) {
+        addInterpolationType(.float(number, format: format, alignment: align, privacy: privacy))
+    }
+    
+    public mutating func appendInterpolation(_ number: @Sendable @autoclosure @escaping () -> Double, format: LogFloatFormatting = .fixed(), align: LogStringAlignment = .none, privacy: LogPrivacy = .private()) {
+        addInterpolationType(.double(number, format: format, alignment: align, privacy: privacy))
+    }
+    
+    public mutating func appendInterpolation(_ boolean: @Sendable @autoclosure @escaping () -> Bool, format: LogBoolFormatting = .truth, privacy: LogPrivacy = .private()) {
+        addInterpolationType(.bool(boolean, format: format, privacy: privacy))
+    }
+}

Sources/SwiftLogOSLogHandler/LogInterpolation/LogInterpolation+Privacy.swift

@@ -0,0 +1,35 @@
+//
+//  LogStringInterpolation.swift
+//  TALogger
+//
+//  Created by Robert Tataru on 01.10.2024.
+//
+import Foundation
+
+extension TAMessage {
+    public struct LogStringInterpolation: StringInterpolationProtocol, Sendable {
+        
+        public enum InterpolationType : Sendable{
+            case literal(String)
+            case string(@Sendable () -> String, alignment: LogStringAlignment, privacy: LogPrivacy)
+            case stringConvertible(@Sendable () -> CustomStringConvertible, alignment: LogStringAlignment, privacy: LogPrivacy)
+            case signedInt(@Sendable () -> Int64, format: LogIntegerFormatting, alignment: LogStringAlignment, privacy: LogPrivacy)
+            case unsignedInt(@Sendable () -> UInt64, format: LogIntegerFormatting, alignment: LogStringAlignment, privacy: LogPrivacy)
+            case double(@Sendable () -> Double, format: LogFloatFormatting, alignment: LogStringAlignment, privacy: LogPrivacy)
+            case bool(@Sendable () -> Bool, format: LogBoolFormatting, privacy: LogPrivacy)
+            case float(@Sendable () -> Float, format: LogFloatFormatting, alignment: LogStringAlignment, privacy: LogPrivacy)
+        }
+       
+        private(set) var storage: [InterpolationType] = []
+        
+        public mutating func addInterpolationType(_ type: InterpolationType) {
+            storage.append(type)
+        }
+        
+        public init(literalCapacity: Int, interpolationCount: Int) {}
+        
+        public mutating func appendLiteral(_ literal: String) {
+            storage.append(.literal(literal))
+        }
+    }
+}