diff --git a/Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift b/Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift new file mode 100644 index 0000000..0588860 --- /dev/null +++ b/Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift @@ -0,0 +1,121 @@ +// ===----------------------------------------------------------------------=== +// +// This source file is part of the Hummingbird DocC Middleware open source project +// +// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors +// Licensed under the EUPL 1.2 or later. +// +// See LICENSE for license information +// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors +// +// ===----------------------------------------------------------------------=== + +import Foundation +import RegexBuilder + +/// A use case that obtains some necessary data from a given URI path, that are essential for routing the documentation contents. +struct PrepareURIPathUseCase { + + // MARK: Type aliases + + /// A pseudo-type that contains the archive name and URI path, plus the resource URI paths used for routing the documentation contents. + typealias PreparedURIPaths = (archiveName: String, archivePath: String, resourcePath: String) + + // MARK: Properties + + /// A root path that suffixes the documentation resource. + private let uriRoot: String + + // MARK: Initializers + + /// Initializes this use case. + /// + /// > important: It is assumed that the `uriRoot` parameter is not empty and that it is prefixed by the `/` character. + /// + /// - Parameter uriRoot: A root path that prefixes the documentation resource. + init(uriRoot: String) { + self.uriRoot = uriRoot + } + + // MARK: Functions + + /// Extracts some necessary data essential for documentation contents routing from a given URI path. + /// + /// The necessary data to extract from a given URI path is: + /// 1. the `DocC` documentation archive name; + /// 2. the `DocC` documentation archive URI path; + /// 3. the `DocC` documentation resource URI path. + /// + /// > important: It is assumed that the `uriPath` parameter is a URI path that does not contain any percent encoded strings. + /// + /// - Parameter uriPath: A URI path to extract the data from. + /// - Returns: A pseudo-type that contains the archive' name and URI path, plus the resource URI paths. + func callAsFunction(_ uriPath: String) -> PreparedURIPaths? { + guard let uriRest = restOfURIPath(from: uriPath) else { + return nil + } + + let documentationName = uriRest + .split(separator: .forwardSlash) + .map(String.init) + .first + + let archiveName: String = if let documentationName { + documentationName.lowercased() + } else { + .empty + } + let archivePath: String = if let documentationName { + .init(format: .Format.Path.archive, documentationName) + } else { + .empty + } + + return (archiveName, archivePath, uriRest) + } + +} + +// MARK: - Helpers + +private extension PrepareURIPathUseCase { + + // MARK: Functions + + /// Extracts the rest of the URI path from a given URI path against a defined URI root path. + /// + /// A given URI path is matched against a regular expression, which is generated from a provided URI root path. + /// So this function would return either a string that represents a partial URI path, or a `nil` instance depending the result of the match between + /// the URI path and the regular expression: + /// * A `nil` instance in case there is no match; + /// * A `/` string in case there is a perfect match; + /// * A partial URI path prefixed with the `/` character in case there is an offset in the match. + /// + /// - Parameter uriPath: A URI path to get the rest of the URI path from. + /// - Returns: A rest of the URI path prefixed by the `/`character in case where there is any offset path after extracting the root path from the given URI path or not. Otherwise, a `nil` value is returned. + func restOfURIPath(from uriPath: String) -> String? { + let restReference = Reference(String.self) + let uriPattern = Regex { + uriRoot + Optionally { + Capture(as: restReference) { + OneOrMore(.anyNonNewline) + } transform: { output in + String(output) + } + } + } + + guard let matches = uriPath.prefixMatch(of: uriPattern) else { + return nil + } + guard let uriRest = matches.output.1 else { + return .forwardSlash + } + guard uriRest.hasPrefix(String.forwardSlash) else { + return .init(format: .Format.Path.root, uriRest) + } + return uriRest + } + +} diff --git a/Sources/DocCMiddleware/Public/Configurations/DoccMiddlewareConfiguration.swift b/Sources/DocCMiddleware/Public/Configurations/DoccMiddlewareConfiguration.swift new file mode 100644 index 0000000..f62ad7f --- /dev/null +++ b/Sources/DocCMiddleware/Public/Configurations/DoccMiddlewareConfiguration.swift @@ -0,0 +1,8 @@ +// +// File.swift +// hummingbird-docc-middleware +// +// Created by Javier Cicchelli on 23/09/2025. +// + +import Foundation diff --git a/Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift b/Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift new file mode 100644 index 0000000..8dfde44 --- /dev/null +++ b/Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift @@ -0,0 +1,154 @@ +// ===----------------------------------------------------------------------=== +// +// This source file is part of the Hummingbird DocC Middleware open source project +// +// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors +// Licensed under the EUPL 1.2 or later. +// +// See LICENSE for license information +// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors +// +// ===----------------------------------------------------------------------=== + +import Testing + +@testable import struct DocCMiddleware.PrepareURIPathUseCase + +@Suite("Prepare URI Path Use Case", .tags(.useCase)) +struct PrepareURIPathUseCaseTests { + + // MARK: Use case tests + +#if swift(>=6.2) + @Test(arguments: zip( + Input.prepareURIPaths, + Output.prepareURIPaths + )) + func `extract data with URI root not suffixed with forward slash`( + uri uriPath: String, + expects result: PrepareURIPathUseCase.PreparedURIPaths? + ) throws { + try assertData( + uriRoot: .uriRoot, + uriPath: uriPath, + expects: result + ) + } + + @Test(arguments: zip( + Input.prepareURIPathsSlashed, + Output.prepareURIPaths + )) + func `extract data with URI root suffixed with forward slash`( + uri uriPath: String, + expects result: PrepareURIPathUseCase.PreparedURIPaths? + ) throws { + try assertData( + uriRoot: .uriRootSlashed, + uriPath: uriPath, + expects: result + ) + } +#else + @Test("extract data with URI root not suffixed with forward slash", arguments: zip( + Input.prepareURIPaths, + Output.prepareURIPaths + )) + func dataWithURIRootNotSuffixedWithForwardSlash( + uri uriPath: String, + expects result: PrepareURIPathUseCase.PreparedURIPaths? + ) throws { + try assertData( + uriRoot: .uriRoot, + uriPath: uriPath, + expects: result + ) + } + + @Test("extract data with URI root suffixed with forward slash", arguments: zip( + Input.prepareURIPathsSlashed, + Output.prepareURIPaths + )) + func dataWithURIRootSuffixedWithForwardSlash( + uri uriPath: String, + expects result: PrepareURIPathUseCase.PreparedURIPaths? + ) throws { + try assertData( + uriRoot: .uriRootSlashed, + uriPath: uriPath, + expects: result + ) + } +#endif + +} + +// MARK: - Assertions + +private extension PrepareURIPathUseCaseTests { + + // MARK: Functions + + /// Asserts the data returned by the ``PrepareURIPathUseCase`` use case based on the given `uriRoot` and `uriPath` URI paths plus + /// an expected result. + /// - Parameters: + /// - uriRoot: A URI path to initialize the use case with. + /// - uriPath: A URI path to use with the use case. + /// - result: An expected result coming out of the use case. + func assertData( + uriRoot: String, + uriPath: String, + expects result: PrepareURIPathUseCase.PreparedURIPaths? + ) throws { + // GIVEN + let useCase = PrepareURIPathUseCase(uriRoot: uriRoot) + + // WHEN + let output = useCase(uriPath) + + // THEN + if !uriPath.contains(uriRoot) { + #expect(output == nil) + } else { + #expect(output != nil) + + let data = try #require(output) + + #expect(data.archiveName == result?.archiveName) + #expect(data.archivePath == result?.archivePath) + #expect(data.resourcePath == result?.resourcePath) + } + } + +} + +// MARK: - Constants + +private extension Input { + /// A list of URI paths to match against the root URI path not suffixed with a forward slash. + static let prepareURIPaths: [String] = [.uriOffset, .uriRoot, .uriOther] + /// A list of URI paths to match against the root URI path suffixed with a forward slash. + static let prepareURIPathsSlashed: [String] = [.uriOffsetSlashed, .uriRootSlashed, .uriOther] +} + +private extension Output { + /// A list of expected outputs for the URI path samples, regardless their match against suffixed or not suffixed root URI paths. + static let prepareURIPaths: [PrepareURIPathUseCase.PreparedURIPaths?] = [ + ("somearchive", "/SomeArchive.doccarchive", "/SomeArchive/some/content/path"), + (.empty, .empty, .forwardSlash), + nil + ] +} + +private extension String { + /// A root URI path to initialize the use case with. + static let uriRoot: Self = "/some/path" + /// A root URI path suffixed with a forward slash to initialize the use case with. + static let uriRootSlashed: Self = "/some/path/" + /// A URI path prefixed with a root URI path not suffixed with a forward slash. + static let uriOffset: Self = .uriRoot + "/SomeArchive/some/content/path" + /// A URI path prefixed with a root URI path suffixed with a forward slash. + static let uriOffsetSlashed: Self = .uriRootSlashed + "SomeArchive/some/content/path" + /// A URI path not related to any root URI path. + static let uriOther: Self = "/some/other/path" +}