Add followSymlink to children()

Closes #225.

Author: dduan

Sources/Pathos/children.swift

@@ -10,12 +10,15 @@ import Darwin
 ///   - path: the path whose children will be returned.
 ///   - recursive: set to `true` to include results from child directories in addition to that from `path`.
 ///                Defaults to `false`.
+///   - followSymlink: include content of a directroy, if it's pointed at by a symlink in the result.
 ///
 /// - Returns: path to directories and files of all types in `path`, and their types, in pairs.
 /// - Throws: A `SystemError` if path cannot be opened as a directory or there's not enough memory to hold all
 ///           data for the results.
 /// - SeeAlso: To work with `Path` or `PathRepresentable`, use `PathRepresentable.children(recursive:)`.
-public func children(inPath path: String, recursive: Bool = false) throws -> [(String, FileType)] {
+public func children(inPath path: String, recursive: Bool = false, followSymlink: Bool = false) throws
+    -> [(String, FileType)]
+{
     var result = [(String, FileType)]()
     guard let streamPtr = opendir(path) else {
         throw SystemError(posixErrorCode: errno)
@@ -40,7 +43,13 @@ public func children(inPath path: String, recursive: Bool = false) throws -> [(S
         let fullName = join(paths: path, name)
         result.append((fullName, pathType))
 
-        if recursive && pathType == .directory {
+        if pathType == .symlink,
+           followSymlink,
+           let realName = try? realPath(ofPath: fullName),
+           (try? isA(.directory, atPath: realName)) == true
+        {
+            result += try children(inPath: fullName, recursive: true)
+        } else if recursive && pathType == .directory {
             result += try children(inPath: fullName, recursive: true)
         }
     }
@@ -72,13 +81,15 @@ extension PathRepresentable {
     /// Result will be empty if this path cannot be opened or there's not enough memory to hold all data for
     /// the results.
     ///
-    /// - Parameter recursive: set to `true` to include results from child directories in addition to that
-    ///                        in this path. Defaults to `false`.
+    /// - Parameters:
+    ///   - recursive: set to `true` to include results from child directories in addition to that
+    ///                in this path. Defaults to `false`.
+    ///   - followSymlink: include content of a directroy, if it's pointed at by a symlink in the result.
     ///
     /// - Returns: paths to directories and files of all types in `path`, and their types, in pairs.
     /// - SeeAlso: `children(inPath:recursive:)`.
-    public func children(recursive: Bool = false) -> [(Self, FileType)] {
-        return ((try? children(inPath:recursive:)(self.pathString, recursive)) ?? [])
+    public func children(recursive: Bool = false, followSymlink: Bool = false) -> [(Self, FileType)] {
+        return ((try? children(inPath:recursive:followSymlink:)(self.pathString, recursive, followSymlink)) ?? [])
             .map { (.init($0), $1) }
     }
 
@@ -87,15 +98,18 @@ extension PathRepresentable {
     /// Result will be empty if this path cannot be opened or there's not enough memory to hold all data for
     /// the results.
     ///
-    /// - Parameters
+    /// - Parameters:
     ///   - type: The file type in question.
     ///   - recursive: set to `true` to include results from child directories in addition to that
     ///                in this path. Defaults to `false`.
+    ///   - followSymlink: include content of a directroy, if it's pointed at by a symlink in the result.
     ///
     /// - Returns: paths to directories and files of all types in `path`, and their types, in pairs.
     /// - SeeAlso: `children(inPath:recursive:)`.
-    public func children(ofType type: FileType, recursive: Bool = false) -> [Self] {
-        return ((try? children(inPath:recursive:)(self.pathString, recursive)) ?? [])
+    public func children(ofType type: FileType, recursive: Bool = false, followSymlink: Bool = false)
+        -> [Self]
+    {
+        return ((try? children(inPath:recursive:followSymlink:)(self.pathString, recursive, followSymlink)) ?? [])
             .filter { $1 == type }
             .map { .init($0.0) }
     }

Tests/PathosTests/ChildrenTests.swift

@@ -84,6 +84,23 @@ final class ChildrenTests: XCTestCase {
         )
     }
 
+    func testNotFollowingSymlinks() throws {
+        XCTAssertEqual(
+            Set(try children(inPath: self.fixture(.secondDirectoryThatExists)).map { $0.0 }),
+            [self.fixture(.secondSymbolInDirectory)]
+        )
+    }
+
+    func testFollowingSymlinks() throws {
+        XCTAssertEqual(
+            Set(try children(inPath: self.fixture(.secondDirectoryThatExists), followSymlink: true).map { $0.0 }),
+            [
+                self.fixture(.secondSymbolInDirectory),
+                self.fixture(.secondFileViaSymlink),
+            ]
+        )
+    }
+
     func testPathRepresentableChildrenInPath() {
         XCTAssertEqual(
             Set(Path(self.fixtureRoot).children().map { $0.0.pathString }),
@@ -261,4 +278,21 @@ final class ChildrenTests: XCTestCase {
             []
         )
     }
+
+    func testPathRepresentableNotFollowingSymlinks() throws {
+        XCTAssertEqual(
+            Set(self.fixturePath(.secondDirectoryThatExists).children().map { $0.0 }),
+            [self.fixturePath(.secondSymbolInDirectory)]
+        )
+    }
+
+    func testPathRepresentableFollowingSymlinks() throws {
+        XCTAssertEqual(
+            Set(self.fixturePath(.secondDirectoryThatExists).children(followSymlink: true).map { $0.0 }),
+            [
+                self.fixturePath(.secondSymbolInDirectory),
+                self.fixturePath(.secondFileViaSymlink),
+            ]
+        )
+    }
 }

Tests/PathosTests/FixtureSupport.swift

@@ -5,11 +5,16 @@ enum FixturePath: String {
     case fileThatExists = "hello"
     case noneExistence = "hello_not"
     case directoryThatExists = "world"
+    case secondDirectoryThatExists = "earth"
+    case thirdDirectoryThatExists = "another_world"
     case goodFileSymbol = "hello_symbol"
     case goodDirectorySymbol = "world_symbol"
     case badSymbol = "broken_symbol"
     case fileInDirectory = "world/world_hello"
+    case secondFileInDirectory = "another_world/me"
+    case secondFileViaSymlink = "earth/portal/me"
     case symbolInDirectory = "world/world_symbol"
+    case secondSymbolInDirectory = "earth/portal"
     case directoryInDirectory = "world/world_world"
     case fileInNestedDirectory = "world/world_world/hello"
     case fileInNestedDirectoryViaDirectorySymbol = "world_symbol/world_world/hello"
@@ -58,7 +63,11 @@ extension XCTestCase {
     }
 
     var childDirectoryFixture: Set<String> {
-        return [self.fixture(.directoryThatExists)]
+        return [
+            self.fixture(.directoryThatExists),
+            self.fixture(.secondDirectoryThatExists),
+            self.fixture(.thirdDirectoryThatExists),
+        ]
     }
 
     var childSymlinkFixture: Set<String> {
@@ -74,13 +83,16 @@ extension XCTestCase {
             self.fixture(.fileThatExists),
             self.fixture(.fileInDirectory),
             self.fixture(.fileInNestedDirectory),
+            self.fixture(.secondFileInDirectory),
         ]
     }
 
     var childDirectoryRecursiveFixture: Set<String> {
         return [
             self.fixture(.directoryThatExists),
             self.fixture(.directoryInDirectory),
+            self.fixture(.secondDirectoryThatExists),
+            self.fixture(.thirdDirectoryThatExists)
         ]
     }
 
@@ -90,6 +102,7 @@ extension XCTestCase {
             self.fixture(.goodDirectorySymbol),
             self.fixture(.badSymbol),
             self.fixture(.symbolInDirectory),
+            self.fixture(.secondSymbolInDirectory),
         ]
     }
 }

Tests/PathosTests/Fixtures/another_world/me

@@ -0,0 +1 @@
+../another_world

Tests/PathosTests/Fixtures/earth/portal

@@ -16,6 +16,8 @@ extension ChildrenTests {
         ("testDirectoriesRecursiveInPath", testDirectoriesRecursiveInPath),
         ("testFilesInPath", testFilesInPath),
         ("testFilesRecursiveInPath", testFilesRecursiveInPath),
+        ("testFollowingSymlinks", testFollowingSymlinks),
+        ("testNotFollowingSymlinks", testNotFollowingSymlinks),
         ("testPathRepresentableBlockDevicesInPath", testPathRepresentableBlockDevicesInPath),
         ("testPathRepresentableBlockDevicesRecursiveInPath", testPathRepresentableBlockDevicesRecursiveInPath),
         ("testPathRepresentableCharacterDevicesInPath", testPathRepresentableCharacterDevicesInPath),
@@ -26,6 +28,8 @@ extension ChildrenTests {
         ("testPathRepresentableDirectoriesRecursiveInPath", testPathRepresentableDirectoriesRecursiveInPath),
         ("testPathRepresentableFilesInPath", testPathRepresentableFilesInPath),
         ("testPathRepresentableFilesRecursiveInPath", testPathRepresentableFilesRecursiveInPath),
+        ("testPathRepresentableFollowingSymlinks", testPathRepresentableFollowingSymlinks),
+        ("testPathRepresentableNotFollowingSymlinks", testPathRepresentableNotFollowingSymlinks),
         ("testPathRepresentablePipesInPath", testPathRepresentablePipesInPath),
         ("testPathRepresentablePipesRecursiveInPath", testPathRepresentablePipesRecursiveInPath),
         ("testPathRepresentableSocketsInPath", testPathRepresentableSocketsInPath),