Pathos 0.3.2

Pathos 0.3.2

×

Maintained by Daniel Duan.

Pathos 0.3.2

Banner

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.

Installation

With CocoaPods

use_frameworks!

pod "Pathos"

With SwiftPM

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

Overview

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.

Development

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".

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).

Releasing

See RELEASING.md.

License

MIT. See LICENSE.md.