[Package] : some optimize

README.md

@@ -22,6 +22,127 @@
 * Complete customizable for text out
 * 100% Code Coverage
 
+## Examples
+
+### Use Builtin Sinks
+
+#### Simple stdout
+
+```swift
+//create sink
+let sink = StandardSink.out()
+//create formation
+let formation = Formation.standard
+//create log
+var logger = Logger(label: "LogName") {
+    Handler(name: $0, sink: sink, formation: formation, logLevel: .trace)
+}
+// do some logs
+logger.trace("This is a trace message")
+logger.debug("This is a debug message")
+logger.info("This is a info message")
+logger.notice("This is a notice message")
+logger.warning("This is a warning message")
+logger.error("This is a error message")
+logger.critical("This is a critical message")
+ ```
+
+Terminal out :
+
+![](Documentations/README/Resources/stdout.png)
+
+#### Change LogLevel
+
+```swift
+logger.logLevel = .info
+logger.debug("will not log")
+logger.info("will log")
+```
+
+#### Add MetaData
+
+```swift
+logger[metadataKey: "UserID"] = .stringConvertible(9527)
+logger.info("message with logger meta data")
+logger.info("message with both logger and message meta data", metadata: ["UserName": .string("L1MeN9Yu")])
+```
+
+Terminal out :
+
+![](Documentations/README/Resources/stdout_message_with_metadata.png)
+
+### Builtin Sinks
+
+#### FileSink
+
+```swift
+let fileSink = FileSink("path/of/log")
+```
+
+Log message will write to file.
+
+See [Tests](Tests/FileSinkTests.swift) for more.
+
+#### OSLogSink (Apple platform only)
+
+```swift
+let osLogSink = OSLogSink(subsystem: "subsystem", category: "category")
+```
+
+Log message will write to OS log (Apple's syslog). Use `Connsole.app` in your macOS to watch oslog messages.
+
+See [Tests](Tests/OSLogSinkTests.swift) for more.
+
+#### SystemLogSink (Linux)
+
+```swift
+let systemLogSink = SystemLogSink()
+```
+
+Log message will write to syslgo.
+
+See [Tests](Tests/SystemLogSinkTests.swift) for more.
+
+### Formation
+
+`Formation` generate the log message.
+
+There are some builtin `Formation`:
+
+1. Formation.standard. This is default for `stdout/stderr`.
+2. Formation.standardXcode. This is default for `stdout/stderr` display in Xcode due Xcode's console is not support ANSI escape code.
+![](Documentations/README/Resources/stdout_xcode.png)
+3. Formation.file. This is default for `File`.
+4. Formation.os. This is default for `OSLog`.
+5. Formation.system. This is default for `syslog`.
+
+### Advanced Customize Formation
+
+Create `Formation` is simple : `Formation(components: <#T##[Component]##[Senna.Component]#>, printer: <#T##Printable?##Senna.Printable?#>, separator: <#T##String?##Swift.String?#>)`
+
+The Formation contains `components: [Component]`, `printer: Printable?` and `separator: String?`.
+
+#### Component
+
+Component is your log message's element. See [Component](Sources/Types/Component.swift) file.
+
+#### Printable
+
+The `Printable` enhanced your log messages, It can add color or style to the component.
+
+The builtin `Printer` has two default instance.
+`Printer.standard` for `stdout/stderr`.
+`Printer.standard` for `stdout/stderr` in Xcode.
+
+You can create new `Printer` instance or Use `YourPrinter` which implements `Printable` protocol.
+
+See [Printer](Sources/Implements/Printer.swift) and [Printable](Sources/Protocols/Printable.swift) for more.
+
+#### Separator
+
+The `Separator` string is used for split log message's component.
+The `Formation.standard`'s separator is `" ▶ "`.
+
 ## Installation
 
 ### Swift Package Manager

Sources/Implements/Formatter.swift → Sources/Implements/Formation.swift

@@ -5,7 +5,7 @@
 import Foundation
 import Logging
 
-public struct Formatter: Formable {
+public struct Formation: Formable {
     public let components: [Component]
     public let printer: Printable?
     public let separator: String?
@@ -47,8 +47,8 @@ public struct Formatter: Formable {
     }
 }
 
-public extension Formatter {
-    static let standard = Formatter(
+public extension Formation {
+    static let standard = Formation(
         components: [
             .name,
             .timestamp(Component.defaultDateFormatter),
@@ -62,11 +62,11 @@ public extension Formatter {
             .message,
             .metadata,
         ],
-        printer: Printer.default,
+        printer: Printer.standard,
         separator: " ▶ "
     )
 
-    static let standardXcode = Formatter(
+    static let standardXcode = Formation(
         components: [
             .name,
             .timestamp(Component.defaultDateFormatter),
@@ -84,7 +84,7 @@ public extension Formatter {
         separator: " ▶ "
     )
 
-    static let file = Formatter(components: [
+    static let file = Formation(components: [
         .name,
         .timestamp(Component.defaultDateFormatter),
         .group([
@@ -95,7 +95,12 @@ public extension Formatter {
         .metadata,
     ])
 
-    static let os = Formatter(components: [
+    static let os = Formation(components: [
+        .message,
+        .metadata,
+    ])
+
+    static let system = Formation(components: [
         .message,
         .metadata,
     ])

Sources/Implements/Handler.swift

@@ -8,7 +8,7 @@ import Logging
 public struct Handler: LogHandler {
     public let name: String
     public let sink: SinkCapable
-    public let formatter: Formable
+    public let formation: Formable
 
     private var prettyMetadata: String?
     public var metadata = Logger.Metadata() {
@@ -22,10 +22,10 @@ public struct Handler: LogHandler {
         set { metadata[metadataKey] = newValue }
     }
 
-    public init(name: String, sink: SinkCapable, formatter: Formable, logLevel: Logger.Level) {
+    public init(name: String, sink: SinkCapable, formation: Formable, logLevel: Logger.Level) {
         self.name = name
         self.sink = sink
-        self.formatter = formatter
+        self.formation = formation
         self.logLevel = logLevel
     }
 
@@ -36,7 +36,7 @@ public struct Handler: LogHandler {
             ??
             prettyMetadata
 
-        let formattedMessage = formatter.format(name: name, level: level, message: message, prettyMetadata: prettyMetadata, file: file, function: function, line: line)
+        let formattedMessage = formation.format(name: name, level: level, message: message, prettyMetadata: prettyMetadata, file: file, function: function, line: line)
         sink.process(formattedMessage, level)
     }
 }

Sources/Implements/Printer.swift

@@ -34,7 +34,7 @@ public extension Printer {
 }
 
 public extension Printer {
-    static let `default` = Printer(
+    static let standard = Printer(
         emoji: { _, _ in nil },
         textColor: {
             switch ($0, $1) {

Tests/FileSinkTests.swift

@@ -11,7 +11,7 @@ final class FileSinkTests: XCTestCase {
         try Data().write(to: fileURL, options: .atomic)
         let fileSink = FileSink(fileURL.path)
         let logger = Logger(label: "File") {
-            Handler(name: $0, sink: fileSink, formatter: Formatter.file, logLevel: .trace)
+            Handler(name: $0, sink: fileSink, formation: Formation.file, logLevel: .trace)
         }
         var count = 10
         while count > 0 {
@@ -39,7 +39,7 @@ final class FileSinkTests: XCTestCase {
         try Data().write(to: fileURL, options: .atomic)
         let fileSink = FileSink(fileURL.path, flushMode: .always)
         let logger = Logger(label: "File") {
-            Handler(name: $0, sink: fileSink, formatter: Formatter.file, logLevel: .trace)
+            Handler(name: $0, sink: fileSink, formation: Formation.file, logLevel: .trace)
         }
         var count = 10
         while count > 0 {

Tests/MultiHandlerTests.swift

@@ -5,8 +5,8 @@ final class MultiHandlerTests: XCTestCase {
     func testMultiHandler() throws {
         var logger = Logger(label: "Multi") {
             MultiplexLogHandler([
-                Handler(name: $0, sink: StandardSink.out(flushMode: .when(.warning)), formatter: Formatter.standard, logLevel: .trace),
-                Handler(name: $0, sink: StandardSink.error(flushMode: .always), formatter: Formatter.standardXcode, logLevel: .notice),
+                Handler(name: $0, sink: StandardSink.out(flushMode: .when(.warning)), formation: Formation.standard, logLevel: .trace),
+                Handler(name: $0, sink: StandardSink.error(flushMode: .always), formation: Formation.standardXcode, logLevel: .notice),
             ])
         }
         logger.trace("\(UInt8.random(in: .min ..< .max))")

Tests/OSLogSinkTests.swift

@@ -10,7 +10,7 @@ final class OSLogSinkTests: XCTestCase {
     @available(OSX 10.12, iOS 10.0, tvOS 10.0, watchOS 3.0, *)
     func testOS() {
         let logger = Logger(label: "OSLog") {
-            Handler(name: $0, sink: OSLogSink(subsystem: "subsystem", category: "category"), formatter: Formatter.os, logLevel: .trace)
+            Handler(name: $0, sink: OSLogSink(subsystem: "subsystem", category: "category"), formation: Formation.os, logLevel: .trace)
         }
         logger.trace("\(UInt8.random(in: .min ..< .max))")
         logger.debug("\(UInt8.random(in: .min ..< .max))")

Tests/StandardSinkTests.swift

@@ -8,7 +8,7 @@ import XCTest
 final class StandardSinkTests: XCTestCase {
     func testStandardOut() {
         let logger = Logger(label: "stdout") {
-            Handler(name: $0, sink: StandardSink.out(), formatter: Formatter.standard, logLevel: .trace)
+            Handler(name: $0, sink: StandardSink.out(), formation: Formation.standard, logLevel: .trace)
         }
         logger.trace("\(UInt8.random(in: .min ..< .max))")
         logger.debug("\(UInt8.random(in: .min ..< .max))")
@@ -21,7 +21,7 @@ final class StandardSinkTests: XCTestCase {
 
     func testStandardError() {
         let logger = Logger(label: "stderr") {
-            Handler(name: $0, sink: StandardSink.error(), formatter: Formatter.standard, logLevel: .trace)
+            Handler(name: $0, sink: StandardSink.error(), formation: Formation.standard, logLevel: .trace)
         }
         logger.trace("\(UInt8.random(in: .min ..< .max))")
         logger.debug("\(UInt8.random(in: .min ..< .max))")
@@ -34,7 +34,7 @@ final class StandardSinkTests: XCTestCase {
 
     func testMetaData() {
         var logger = Logger(label: "stdout") {
-            Handler(name: $0, sink: StandardSink.out(), formatter: Formatter.standard, logLevel: .trace)
+            Handler(name: $0, sink: StandardSink.out(), formation: Formation.standard, logLevel: .trace)
         }
         logger[metadataKey: "UserName"] = .string("L1MeN9Yu")
         logger[metadataKey: "UserID"] = .stringConvertible(9527)
@@ -50,7 +50,7 @@ final class StandardSinkTests: XCTestCase {
 
     func testLevel() {
         var logger = Logger(label: "stdout") {
-            Handler(name: $0, sink: StandardSink.out(), formatter: Formatter.standard, logLevel: .trace)
+            Handler(name: $0, sink: StandardSink.out(), formation: Formation.standard, logLevel: .trace)
         }
         logger.trace("\(UInt8.random(in: .min ..< .max))")
         logger.debug("\(UInt8.random(in: .min ..< .max))")
@@ -66,7 +66,7 @@ final class StandardSinkTests: XCTestCase {
 
     func testStandardXcode() {
         let logger = Logger(label: "stdout+xcode") {
-            Handler(name: $0, sink: StandardSink.out(), formatter: Formatter.standardXcode, logLevel: .trace)
+            Handler(name: $0, sink: StandardSink.out(), formation: Formation.standardXcode, logLevel: .trace)
         }
         logger.trace("\(UInt8.random(in: .min ..< .max))")
         logger.debug("\(UInt8.random(in: .min ..< .max))")
@@ -81,7 +81,7 @@ final class StandardSinkTests: XCTestCase {
         struct NilPrinter: Printable {}
 
         let logger = Logger(label: "stdout+xcode") {
-            Handler(name: $0, sink: StandardSink.out(), formatter: Senna.Formatter(components: [
+            Handler(name: $0, sink: StandardSink.out(), formation: Senna.Formation(components: [
                 .message,
                 .metadata,
             ], printer: NilPrinter()), logLevel: .trace)

Tests/SystemLogSinkTests.swift

@@ -8,7 +8,7 @@ import XCTest
 final class SystemLogSinkTests: XCTestCase {
     func testSystem() {
         let logger = Logger(label: "syslog") {
-            Handler(name: $0, sink: SystemLogSink(), formatter: Formatter.os, logLevel: .trace)
+            Handler(name: $0, sink: SystemLogSink(), formation: Formation.system, logLevel: .trace)
         }
         logger.trace("\(UInt8.random(in: .min ..< .max))")
         logger.debug("\(UInt8.random(in: .min ..< .max))")
@@ -21,7 +21,7 @@ final class SystemLogSinkTests: XCTestCase {
 
     func testMetaData() {
         var logger = Logger(label: "syslog") {
-            Handler(name: $0, sink: SystemLogSink(), formatter: Formatter.os, logLevel: .trace)
+            Handler(name: $0, sink: SystemLogSink(), formation: Formation.system, logLevel: .trace)
         }
         logger[metadataKey: "UserName"] = .string("L1MeN9Yu")
         logger[metadataKey: "UserID"] = .stringConvertible(9527)