Swiftpack.co - Package - dduan/Pathos


Pathos is everything you need for file system¹ inquiry and manipulation.

For a taste what that means, let's generate a static site from Markdown files!

// Create a unique, temporary directory.
let temporaryRoot = try createTemporaryDirectory()

// Find paths to .md files relative to current working directory, recursively.
for markdown in try glob("**/*.md") {

    // path/to/file.md -> path/to/file.
    let url = basename(ofPath: markdown)

    // Join path segements.
    let urlPath = join(paths: temporaryRoot, url)

    // Make a directory.
    try createDirectory(atPath: urlPath)

    // Read from a file.
    let source = try readString(atPath: markdown)

    // Write to a file. `markdown2html` … just imagine it exists.
    try write(markdown2html(source), atPath: join(paths: url, "index.html"))

// Move a directory.
try movePath(temporaryRoot, toPath: "output")

Pathos offers conventional OOP interfaces to all of these functions as well.

Read the documentation to learn more.

¹ Unix virtual file system, as opposed to underlying system such as APFS, Ext4, btrfs etc.


With CocoaPods


pod "Pathos"

With SwiftPM

.package(url: "http://github.com/dduan/Pathos", from: "0.3.2")


Pathos includes a ton of interfaces (Battery included). Here's a rough breakdown and links to API documentation.

|Section | Description | |------------------------|---------------------------------------------------------------------------| | POP and OOP | Protocols and types for OOP interfaces. | | Finding Files | Discover child in folders by pattern or file type. | | File IO | Reading and writing files and symoblic links. | | Manipulating Paths | Deleting/moving/creating directories. | | Analyzing Paths | Properties about the path, such as its equivalent absolute path. | | Temporary Paths | Temporary and unique files and directories. | | Relationships | Relationships between multiple paths. Joining, common components, etc. | | Working Directory | Getting/setting current working directory. | | System Attributes | File size, access time, permissions, etc. | | Existence | Find out if a path points to an existing file, the type of the file, etc. | | Constants | Public constants. | | Errors | Errors Pathos throw in various places. |

Design Goals

  1. Provide as few abstractions atop POSIX file API as possible, but no fewer. Make conventional C APIs Swift-y, but avoid over-abstraction. Use string for path values for efficiency and simplicity. User can trivially and incrementally add on abstractions for their needs.
  2. Battery included. Include a well-rounded set of convenience for file manipulations. (Python users, for example, should feel right at home).
  3. Support OOP. Almost everything in Pathos is available in 2 paradigms: procedural (free functions) and OOP (methods). A super simple protocol, PathRepresentable, serves as the root for all functionalities.
  4. Error handling can be optional. In practice, specific POSIX error code is often not more actionable than some indication that things went wrong. Therefore, the OOP interfaces from Pathos hides the system errors. Users can opt in and out of the overhead of dealing with POSIX errors by switching between paradigms. For example, instead of throwing out errors such as lack of permission, PathRepresentable.delete() simply returns false to indication the operation failure.


Use make targets for development.

  • make build builds the library in release configuration. This command also checks whether there's any test changes and update the Linux test manifest on macOS (or remind you to do so on Linux).
  • make clean deletes build artifacts including SPM build folders and other artifacts.
  • develop-linux-docker launches a docker container with Swift. The project is mirrored at /Pathos. You can edit from the host and run/test in the container.

Also, see "Testing".


XCTest is used for testing.

  • make test runs all tests.
  • make generate-linux-test-manifest updates the test manifest for Linux, this only works on macOS.
  • make test-docker runs tests in Linux docker container (you'll need Docker installed in your host).






Stars: 84



0.3.2 - 2020-09-21 22:27:00

  • Fix a bug where children always recusively visit its content when following symlinks.

0.3.1 - 2020-09-19 02:38:54

  • children() can follow symlinks found in the content if followSymlink parameter is set to True.
  • expand Linux distro support to match that of Swift's.

0.3.0 - 2020-07-01 00:08:59


  • Warnings in Swift 5.3


  • Added a new type Metadata, which represents information from stat (Darwin, Linux).
  • Added API to retrieve Metadata.
  • PathRepresentable.set(_:) (permissions)


The following APIs are deprecated in favor of metadata access APIs.

  • size(atPath)
  • modificationTime(atPath:)
  • accessTime(atPath:)
  • metadataChangeTime(atPath:)
  • PathRepresentable.size
  • PathRepresentable.modificationTime
  • PathRepresentable.accessTime
  • PathRepresentable.metadataChangeTime
  • permissions(forPath:)
  • PathRepresentable.permissions

Removed adding/removing permissions in favor of directly setting it:

  • add(_:forPath:)
  • remove(_:forPath:)
  • PathRepresentable.add(_:)
  • PathRepresentable.remove(_:)

Previously symbolic links were referred to as "symbol" or "symbolic link" in APIs. From this version on, they'll be referred to as "symlink". This resulted in the following changes:

  • createSymbolicLink(fromPath:toPath:) -> createSymlink(fromPath:toPath:)
  • PathRepresentable.createSymbolicLink(at:) -> PathRepresentable.createSymlink(at:)
  • readSymbolicLink(atPath:toPath) -> readSymlink(atPath:toPath)
  • PathRepresentable.readSymbolicLink() -> PathRepresentable.readSymlink()
  • FileType.symbolicLink -> FileType.symlink

Carthage is no longer supported.

Breaking changes

Previously symbolic links were referred to as "symbol" or "symbolic link" in APIs. From this version on, they'll be referred to as "symlink". This resulted in the following breaking changes:

  • exists(atPath:followSymbol:) -> exists(atPath:followSymlink:)
  • PathRepresentable.exists(followSymbol:) -> PathRepresentable.exists(followSymlink:)
  • copyFile(fromPath:toPath:followSymbolicLink:checkSize:) -> copyFile(fromPath:toPath:followSymlink:checkSize:)
  • PathRepresentable.copy(to:followSymbolicLink:checkSize:) -> PathRepresentable.copy(to:followSymlink:checkSize:)
c0a33d66a22521493e8ef30a40306800442ba46100ad15e6682172e369a06976  0.3.0.tar.gz
5f28bcbc7f4f1c773ac5287a250ae92d034c32a5021b36fbdaa21249538ec7b5  0.3.0.zip

0.2.3 - 2020-04-03 01:38:12

  • Re-implemented children(inPath:recursive) to fix issue #122
1909614ae4daf87749ac3e773acc23383244891ee383d86ba502d925f353ffea  0.2.3.tar.gz
04307d24befed1d304f05d152cb3f99e8d72aaff10119267e5fcf7bcf5c36610  0.2.3.zip
54c99f67f57b6a552e1594155ccd03eeede166fae40031d80e2a954654b620d1  Pathos.framework.zip

0.2.2 - 2020-03-09 06:37:47

  • Removed a build warning in Swift 5.2

0.2.1 - 2019-10-21 20:36:21

0.2.0 - 2019-04-09 16:34:52

0.1.3 - 2019-04-07 00:27:32

Fixed a bug for writing strings where an extra nul is added at the end of file.

0.1.2 - 2019-03-27 05:58:50

0.1.1 - 2019-03-27 05:00:50

+ for PathRepresentable joining.

0.1.0 - 2019-03-26 05:51:05

Swift 5 Support

0.0.6 - 2019-03-24 08:07:42

0.0.5 - 2019-03-11 16:14:52

the string label from Path.init is removed.

0.0.4 - 2019-02-13 07:25:11

Improve interface.

0.0.3 - 2019-01-15 03:41:07

Update APIs for writing to files. The main change include having a sensible default permission for new files, and accepting non UInt8 byte sequence.

0.0.2 - 2019-01-03 05:26:22

All 1.0 features has been implemented. Some unit tests are still missing.

- 2018-09-24 00:51:19