wip

.gitignore

@@ -6,3 +6,4 @@ DerivedData/
 .swiftpm/configuration/registries.json
 .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
 .netrc
+.nvim/*

.nvim/xcodebuild/devices.json

@@ -1 +0,0 @@
-{"projectFile": "/Volumes/Bucket/Repos/swift-cli-doc/Package.swift", "scheme": "swift-cli-doc", "devices": [{"platform": "macOS", "name": "My Mac", "arch": "arm64e", "id": "00008103-000E79D011EA001E"}]}

.nvim/xcodebuild/report.json

@@ -1 +0,0 @@
-{"testsCount": 6, "xcresultFilepath": "/Users/michael/Library/Developer/Xcode/DerivedData/swift-cli-doc-dgihrbuebwxquzdknevkczbenunz/Logs/Test/Test-swift-cli-doc-2024.12.04_17-02-40--0500.xcresult", "failedTestsCount": 0, "tests": {"CliDocTests:_Global": [{"target": "CliDocTests", "name": "testGroup", "testResult": "passed", "swiftTestingId": "CliDocTests/testGroup", "class": "_Global", "time": "0.00031 seconds", "success": true}, {"target": "CliDocTests", "name": "testHStack", "testResult": "passed", "swiftTestingId": "CliDocTests/testHStack", "class": "_Global", "time": "0.000081 seconds", "success": true}, {"target": "CliDocTests", "name": "testVStack", "testResult": "passed", "swiftTestingId": "CliDocTests/testVStack", "class": "_Global", "time": "0.000049 seconds", "success": true}, {"target": "CliDocTests", "name": "testNote", "testResult": "passed", "swiftTestingId": "CliDocTests/testNote", "class": "_Global", "time": "0.00027 seconds", "success": true}, {"target": "CliDocTests", "name": "testExamples", "testResult": "passed", "swiftTestingId": "CliDocTests/testExamples", "class": "_Global", "time": "0.00027 seconds", "success": true}, {"target": "CliDocTests", "name": "testExamplesWithCustomExampleOnlyStyle", "testResult": "passed", "swiftTestingId": "CliDocTests/testExamplesWithCustomExampleOnlyStyle", "class": "_Global", "time": "0.00016 seconds", "success": true}]}, "buildWarnings": [], "usesSwiftTesting": true, "testErrors": [], "buildErrors": []}

.nvim/xcodebuild/settings.json

@@ -1 +0,0 @@
-{"platform": "macOS", "workingDirectory": "/Volumes/Bucket/Repos/swift-cli-doc", "swiftPackage": "/Volumes/Bucket/Repos/swift-cli-doc/Package.swift", "deviceName": "My Mac", "destination": "00008103-000E79D011EA001E", "lastBuildTime": 7, "scheme": "swift-cli-doc"}

.nvim/xcodebuild/test-explorer.json

@@ -1 +0,0 @@
-[{"status": "passed", "hidden": false, "name": "CliDocTests", "classes": [{"status": "passed", "hidden": false, "id": "CliDocTests/_Global", "name": "_Global", "tests": [{"status": "passed", "hidden": false, "name": "testExamples", "id": "CliDocTests/_Global/testExamples", "swiftTestingId": "CliDocTests/testExamples", "kind": "test"}, {"status": "passed", "hidden": false, "name": "testExamplesWithCustomExampleOnlyStyle", "id": "CliDocTests/_Global/testExamplesWithCustomExampleOnlyStyle", "swiftTestingId": "CliDocTests/testExamplesWithCustomExampleOnlyStyle", "kind": "test"}, {"status": "passed", "hidden": false, "name": "testGroup", "id": "CliDocTests/_Global/testGroup", "swiftTestingId": "CliDocTests/testGroup", "kind": "test"}, {"status": "passed", "hidden": false, "name": "testHStack", "id": "CliDocTests/_Global/testHStack", "swiftTestingId": "CliDocTests/testHStack", "kind": "test"}, {"status": "passed", "hidden": false, "name": "testNote", "id": "CliDocTests/_Global/testNote", "swiftTestingId": "CliDocTests/testNote", "kind": "test"}, {"status": "passed", "hidden": false, "name": "testVStack", "id": "CliDocTests/_Global/testVStack", "swiftTestingId": "CliDocTests/testVStack", "kind": "test"}], "swiftTestingId": "CliDocTests", "kind": "class"}], "id": "CliDocTests", "kind": "target"}]

Sources/CliDoc/BaseNodes/HStack.swift

@@ -17,6 +17,7 @@ public struct HStack: TextNode {
 
   @inlinable
   public var body: some TextNode {
-    content.map { $0.render() }.joined(separator: separator.render())
+    content.removingEmptys()
+      .joined(separator: separator.render())
   }
 }

Sources/CliDoc/BaseNodes/VStack.swift

@@ -17,6 +17,7 @@ public struct VStack: TextNode {
 
   @inlinable
   public var body: some TextNode {
-    content.map { $0.render() }.joined(separator: separator.render())
+    content.removingEmptys()
+      .joined(separator: separator.render())
   }
 }

Sources/CliDoc/Modifiers/ExamplesStyle.swift

@@ -1,105 +0,0 @@
-import Rainbow
-
-public extension ExampleSection {
-
-  func style<S: ExampleSectionStyle>(_ style: S) -> some TextNode {
-    style.render(content: .init(
-      header: header,
-      label: label,
-      examples: examples
-    ))
-  }
-
-  func exampleStyle<S: ExampleStyle>(_ style: S) -> some TextNode {
-    DefaultExamplesStyle(exampleStyle: style).render(content: .init(
-      header: header,
-      label: label,
-      examples: examples
-    ))
-  }
-}
-
-extension Array where Element == ExampleSection.Example {
-  func exampleStyle<S: ExampleStyle>(_ style: S) -> some TextNode {
-    style.render(content: .init(examples: self))
-  }
-}
-
-public struct ExampleSectionConfiguration {
-  @usableFromInline
-  let header: any TextNode
-
-  @usableFromInline
-  let label: any TextNode
-
-  @usableFromInline
-  let examples: [ExampleSection.Example]
-
-  @usableFromInline
-  init(header: any TextNode, label: any TextNode, examples: [ExampleSection.Example]) {
-    self.header = header
-    self.label = label
-    self.examples = examples
-  }
-}
-
-public struct ExampleConfiguration {
-  @usableFromInline
-  let examples: [ExampleSection.Example]
-
-  @usableFromInline
-  init(examples: [ExampleSection.Example]) {
-    self.examples = examples
-  }
-}
-
-public protocol ExampleSectionStyle: NodeModifier where Content == ExampleSectionConfiguration {}
-public protocol ExampleStyle: NodeModifier where Content == ExampleConfiguration {}
-
-public extension ExampleSectionStyle where Self == DefaultExamplesStyle {
-  static func `default`(exampleStyle: any ExampleStyle = .default) -> Self {
-    DefaultExamplesStyle(exampleStyle: exampleStyle)
-  }
-}
-
-public extension ExampleStyle where Self == DefaultExampleStyle {
-  static var `default`: Self {
-    DefaultExampleStyle()
-  }
-}
-
-public struct DefaultExamplesStyle: ExampleSectionStyle {
-
-  @usableFromInline
-  let exampleStyle: any ExampleStyle
-
-  @inlinable
-  public init(exampleStyle: any ExampleStyle = .default) {
-    self.exampleStyle = exampleStyle
-  }
-
-  @inlinable
-  public func render(content: ExampleSectionConfiguration) -> some TextNode {
-    VStack(spacing: 2) {
-      HStack {
-        content.header
-        content.label
-      }
-      exampleStyle.render(content: .init(examples: content.examples))
-    }
-  }
-}
-
-public struct DefaultExampleStyle: ExampleStyle {
-
-  public func render(content: ExampleConfiguration) -> some TextNode {
-    VStack(spacing: 2) {
-      content.examples.map { example in
-        VStack {
-          Label(example.label.green.bold)
-          ShellCommand { example.example }.style(.default)
-        }
-      }
-    }
-  }
-}

Sources/CliDoc/Modifiers/SectionStyle.swift

@@ -31,7 +31,7 @@ public struct DefaultSectionStyle: SectionStyle {
     VStack {
       content.header
       content.content
-      content.footer.textStyle(.italic)
+      content.footer
     }
   }
 }

Sources/CliDoc/Nodes/ExampleSection.swift

@@ -4,23 +4,32 @@ public struct ExampleSection<Header: TextNode, Label: TextNode>: TextNode {
   public typealias Example = (label: String, example: String)
 
   @usableFromInline
-  let examples: [Example]
-
-  @usableFromInline
-  let header: Header
-
-  @usableFromInline
-  let label: Label
+  let configuration: ExampleSectionConfiguration
 
   @inlinable
   public init(
     examples: [Example],
-    @TextBuilder header: () -> Header,
+    @TextBuilder title: () -> Header,
     @TextBuilder label: () -> Label
   ) {
-    self.examples = examples
-    self.header = header()
-    self.label = label()
+    self.configuration = .init(
+      title: title(),
+      label: label(),
+      examples: examples
+    )
+  }
+
+  @inlinable
+  public init(
+    _ title: @autoclosure () -> Header,
+    label: @autoclosure () -> Label,
+    examples: [Example]
+  ) {
+    self.init(
+      examples: examples,
+      title: title,
+      label: label
+    )
   }
 
   @inlinable
@@ -29,23 +38,105 @@ public struct ExampleSection<Header: TextNode, Label: TextNode>: TextNode {
   }
 }
 
-public extension ExampleSection where Header == String, Label == String {
-  @inlinable
-  init(
-    header: String = "Examples:".yellow.bold,
-    label: String = "Some common usage examples.",
-    examples: [Example]
-  ) {
-    self.init(examples: examples) { header } label: { label }
-  }
+/// The type-erased configuration of an ``ExampleSection``
+public struct ExampleSectionConfiguration {
+  @usableFromInline
+  let title: any TextNode
 
-  @inlinable
-  init(
-    header: String = "Examples:".yellow.bold,
-    label: String = "Some common usage examples.",
-    examples: Example...
-  ) {
-    self.init(header: header, label: label, examples: examples)
-  }
+  @usableFromInline
+  let label: any TextNode
 
+  @usableFromInline
+  let examples: [ExampleSection.Example]
+
+  @usableFromInline
+  init(title: any TextNode, label: any TextNode, examples: [ExampleSection.Example]) {
+    self.title = title
+    self.label = label
+    self.examples = examples
+  }
+}
+
+// MARK: - Style
+
+public extension ExampleSection {
+
+  func style<S: ExampleSectionStyle>(_ style: S) -> some TextNode {
+    style.render(content: configuration)
+  }
+
+  func exampleStyle<S: ExampleStyle>(_ style: S) -> some TextNode {
+    DefaultExamplesStyle(exampleStyle: style).render(content: configuration)
+  }
+}
+
+extension Array where Element == ExampleSection.Example {
+  func exampleStyle<S: ExampleStyle>(_ style: S) -> some TextNode {
+    style.render(content: .init(examples: self))
+  }
+}
+
+public struct ExampleConfiguration {
+  @usableFromInline
+  let examples: [ExampleSection.Example]
+
+  @usableFromInline
+  init(examples: [ExampleSection.Example]) {
+    self.examples = examples
+  }
+}
+
+public protocol ExampleSectionStyle: NodeModifier where Content == ExampleSectionConfiguration {}
+public protocol ExampleStyle: NodeModifier where Content == ExampleConfiguration {}
+
+public extension ExampleSectionStyle where Self == DefaultExamplesStyle {
+  static func `default`(exampleStyle: any ExampleStyle = .default) -> Self {
+    DefaultExamplesStyle(exampleStyle: exampleStyle)
+  }
+}
+
+public extension ExampleStyle where Self == DefaultExampleStyle {
+  static var `default`: Self {
+    DefaultExampleStyle()
+  }
+}
+
+public struct DefaultExamplesStyle: ExampleSectionStyle {
+
+  @usableFromInline
+  let exampleStyle: any ExampleStyle
+
+  @inlinable
+  public init(exampleStyle: any ExampleStyle = .default) {
+    self.exampleStyle = exampleStyle
+  }
+
+  @inlinable
+  public func render(content: ExampleSectionConfiguration) -> some TextNode {
+    VStack(spacing: 2) {
+      HStack {
+        content.title
+          .color(.yellow)
+          .textStyle(.bold)
+
+        content.label
+          .textStyle(.italic)
+      }
+      exampleStyle.render(content: .init(examples: content.examples))
+    }
+  }
+}
+
+public struct DefaultExampleStyle: ExampleStyle {
+
+  public func render(content: ExampleConfiguration) -> some TextNode {
+    VStack(spacing: 2) {
+      content.examples.map { example in
+        VStack {
+          Label(example.label.green.bold)
+          ShellCommand { example.example }.style(.default)
+        }
+      }
+    }
+  }
 }

Sources/CliDoc/Utils.swift

@@ -19,3 +19,18 @@ func seperator(_ separator: String, count: Int) -> any TextNode {
   }
   return output
 }
+
+extension Array where Element == (any TextNode) {
+
+  @usableFromInline
+  func removingEmptys() -> [String] {
+    compactMap { node in
+      let string = node.render()
+      if string == "" {
+        return nil
+      }
+      return string
+    }
+  }
+
+}

Tests/CliDocTests/CliDocTests.swift

@@ -56,11 +56,13 @@ func testNote() {
 func testExamples() {
   #expect(setupRainbow)
   let examples = ExampleSection(
+    "Examples:",
+    label: "Some common usage examples.",
     examples: [("First", "ls -lah"), ("Second", "find . -name foo")]
   )
 
   let expected = """
-  \("Examples:".yellow.bold) Some common usage examples.
+  \("Examples:".yellow.bold)\(" ")\("Some common usage examples.".italic)
 
   \("First".green.bold)
   $ \("ls -lah".italic)
@@ -68,19 +70,22 @@ func testExamples() {
   \("Second".green.bold)
   $ \("find . -name foo".italic)
   """
-  #expect(examples.render() == expected)
+  let result = printIfNotEqual(examples.render(), expected)
+  #expect(result)
 }
 
 @Test
 func testExamplesWithCustomExampleOnlyStyle() {
   #expect(setupRainbow)
   let examples = ExampleSection(
+    "Examples:",
+    label: "Some common usage examples.",
     examples: [("First", "ls -lah"), ("Second", "find . -name foo")]
   )
   .exampleStyle(CustomExampleOnlyStyle())
 
   let expected = """
-  \("Examples:".yellow.bold) Some common usage examples.
+  \("Examples:".applyingStyle(.bold).applyingColor(.yellow)) \("Some common usage examples.".italic)
 
   \("First".red)
   $ \("ls -lah".italic)
@@ -88,7 +93,73 @@ func testExamplesWithCustomExampleOnlyStyle() {
   \("Second".red)
   $ \("find . -name foo".italic)
   """
-  #expect(examples.render() == expected)
+  let result = printIfNotEqual(examples.render(), expected)
+  #expect(result)
+}
+
+@Test(
+  arguments: SectionArg.arguments
+)
+func testSection(arg: SectionArg) {
+  #expect(setupRainbow)
+  printIfNotEqual(arg.section.render(), arg.expected)
+  #expect(arg.section.render() == arg.expected)
+}
+
+struct SectionArg: @unchecked Sendable {
+  let section: any TextNode
+  let expected: String
+
+  static var arguments: [Self] {
+    [
+      .init(
+        section: Section {
+          "Header"
+        } content: {
+          "Content"
+        } footer: {
+          "Footer"
+        },
+        expected: """
+        Header
+        Content
+        Footer
+        """
+      ),
+      .init(
+        section: Section {
+          "Content"
+        } footer: {
+          "Footer"
+        },
+        expected: """
+        Content
+        Footer
+        """
+      ),
+      .init(
+        section: Section {
+          "Header"
+        } content: {
+          "Content"
+        },
+        expected: """
+        Header
+        Content
+        """
+      )
+    ]
+  }
+}
+
+@discardableResult
+func printIfNotEqual(_ lhs: String, _ rhs: String) -> Bool {
+  guard lhs == rhs else {
+    print(lhs)
+    print(rhs)
+    return false
+  }
+  return true
 }
 
 struct CustomExampleOnlyStyle: ExampleStyle {
@@ -96,7 +167,7 @@ struct CustomExampleOnlyStyle: ExampleStyle {
     VStack(spacing: 2) {
       content.examples.map { example in
         VStack {
-          Label(example.label.red)
+          example.label.red
           ShellCommand { example.example }
         }
       }