Readme: fix examples, add summary of why this library exists.

Author: kareman

README.md

@@ -4,11 +4,10 @@
 
 A strongly typed Swift library for working with local files and directories.
 
-Because when working with paths you almost always know which are for directories and which are for files, so why not let the compiler in on it too?
+It differentiates between file paths and directory paths, and between paths and actual files and directories, because the programmer knows which are which and when the compiler knows it too it can be much more helpful. 
 
-Still a work in progress and has not been properly tested, so use at your own risk. This readme is also clearly far from finished.
-
-[API documentation](https://kareman.github.io/FileSmith/)
+See also:
+- [API documentation](https://kareman.github.io/FileSmith/)
 
 ## Terms
 
@@ -69,7 +68,7 @@ var dir2 = try Directory(create: "dir/dir2", ifExists: .throwError)
 var dir3 = try dir2.create(directory: "dir3", ifExists: .open) // dir/dir2/dir3
 
 var file1_edit = try filepath.create(ifExists: .open)
-let file2_edit = try EditableFile(create: "file2.txt", ifExists: .open)
+let file2_edit = try WritableFile(create: "file2.txt", ifExists: .open)
 let file3_edit = try dir1.create(file: "file3.txt", ifExists: .open) // dir/dir1/file3
 ```
 
@@ -81,7 +80,7 @@ dir2 = try Directory(open: "dir/dir2")
 dir3 = try dir2.open(directory: "dir3")
 
 let file1 = try filepath.open()
-let file2 = try File(open: "file2.txt")
+let file2 = try ReadableFile(open: "file2.txt")
 let file3 = try dir1.open(file: "file3.txt")
 ```
 
@@ -114,8 +113,8 @@ Directory.current.directories(recursive: true) // [dir, dir/dir1, dir/dir2, dir/
 ```swift
 let dir1_link = try Directory(createSymbolicLink: "dir1_link", to: dir1, ifExists: .open)
 let dir2_link = try dir1.create(symbolicLink: "dir2_link", to: dir2, ifExists: .open)
-let file1_link = try File(createSymbolicLink: "file1_link", to: file1, ifExists: .open)
-let file2_link = try dir2.create(symbolicLink: "file2_link", to: file2, ifExists: .open)
+let file1_link = try ReadableFile(createSymbolicLink: "file1_link", to: file1, ifExists: .open)
+let file2_link = try dir2.create(symbolicLink: "file2_link", to: file2, ifExists: .open) as ReadableFile
 ```
 
 #### Misc

Tests/FileSmithTests/DirectoryTests.swift

@@ -163,86 +163,6 @@ class DirectoryTests: XCTestCase {
 			XCTFail(String(describing: error))
 		}
 	}
-
-
-	/// The code examples under "Usage" in the readme.
-	func testReadme() {
-		do {
-			// #### Change current working directory
-			DirectoryPath.current = "/tmp"
-			Directory.current = Directory.createTempDirectory()
-
-			// #### Paths
-			let dirpath = DirectoryPath("dir/dir1")
-			var filepath: FilePath = "file.txt"
-			filepath = FilePath(base: "dir", relative: "file.txt")
-			filepath = FilePath("dir/file.txt")
-
-			filepath.relativeString
-			filepath.base?.string
-			filepath.absoluteString
-			filepath.string // relativeString ?? absoluteString
-			filepath.name
-			filepath.nameWithoutExtension
-			filepath.extension
-
-
-			dirpath.append(file: "file.txt")  // FilePath("dir/dir1/file.txt")
-			dirpath.append(directory: "dir2") // DirectoryPath("dir/dir1/dir2")
-			dirpath.isAParentOf(filepath)
-
-			// #### Create
-			var dir1 = try dirpath.create(ifExists: .replace)
-			var dir2 = try Directory(create: "dir/dir2", ifExists: .throwError)
-			var dir3 = try dir2.create(directory: "dir3", ifExists: .open) // dir/dir2/dir3
-
-			var file1_edit = try filepath.create(ifExists: .open)
-			let file2_edit = try WritableFile(create: "file2.txt", ifExists: .open)
-			let file3_edit = try dir1.create(file: "file3.txt", ifExists: .open) // dir/dir1/file3
-
-			// #### Open
-			dir1 = try dirpath.open()
-			dir2 = try Directory(open: "dir/dir2")
-			dir3 = try dir2.open(directory: "dir3")
-
-			let file1 = try filepath.open()
-			let file2 = try ReadableFile(open: "file2.txt")
-			let file3 = try dir1.open(file: "file3.txt")
-
-			// #### Read/Write
-			file1_edit.encoding = .utf16 // .utf8 by default
-			file1_edit.write("some text...")
-			file2.write(to: &file1_edit)
-
-			let contents: String = file3.read()
-			for line in file3.lines() { // a lazy sequence
-				// ...
-			}
-			while let text = file3.readSome() {
-				// read pipes etc. piece by piece, instead of waiting until they are closed.
-			}
-
-			// #### Search/Filter
-			Directory.current.files(recursive: true)       // [file2.txt, dir/file1.txt, dir/dir1/file3.txt]
-			dir1.files("*3.*", recursive: true)            // [file3.txt]
-			Directory.current.directories(recursive: true) // [dir, dir/dir1, dir/dir2, dir/dir2/dir3]
-
-			// #### Symbolic links
-			let dir1_link = try Directory(createSymbolicLink: "dir1_link", to: dir1, ifExists: .open)
-			let dir2_link = try dir1.create(symbolicLink: "dir2_link", to: dir2, ifExists: .open)
-			let file1_link = try ReadableFile(createSymbolicLink: "file1_link", to: file1, ifExists: .open)
-			let file2_link = try dir2.create(symbolicLink: "file2_link", to: file2, ifExists: .open) as ReadableFile
-
-			// #### Misc
-			try file1_edit.delete()
-			try dir1.delete()
-
-			// Suppress unused variables warning.
-			_ = [dir3,file2_edit,file3_edit,contents,dir1_link,dir2_link,file1_link,file2_link]
-		} catch {
-			XCTFail(String(describing: error))
-		}
-	}
 }
 
 extension DirectoryTests {
@@ -254,6 +174,5 @@ extension DirectoryTests {
 		("testOpenDirectory", testOpenDirectory),
 		("testCreateDirectory", testCreateDirectory),
 		("testDirectoryInAMultitudeOfWays", testDirectoryInAMultitudeOfWays),
-		("testReadme", testReadme),
 		]
 }