rock-n-code/hummingbird-docc
1
0
Fork 0
Code Issues Pull Requests Releases 3 Activity

Implemented the PrepareURIPathUseCase use case type in the library target.

Browse Source
This commit is contained in:
Javier Cicchelli
2025-09-23 15:19:16 +02:00
parent 0d76afb738
commit 2f701ce95e
3 changed files with 283 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift
+121
View File
@@ -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
}
}
Sources/DocCMiddleware/Public/Configurations/DoccMiddlewareConfiguration.swift
+8
View File
@@ -0,0 +1,8 @@
//
// File.swift
// hummingbird-docc-middleware
//
// Created by Javier Cicchelli on 23/09/2025.
//
import Foundation
Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift
+154
View File
@@ -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"
}