Improve README

Author: hasufell

HACKING.md

@@ -0,0 +1,21 @@
+# Hacking
+
+Most of the code is in `System/FilePath/Internal.hs` which is `cpphs`'d into both `System/FilePath/Posix.hs`
+and `System/FilePath/Windows.hs` via `make cpp` and commited to the repo. This Internal module is a bit weird
+in that it isn't really a Haskell module, but is more an include file.
+
+The library has extensive doc tests. Anything starting with `-- >` is transformed into a doc test as a predicate
+that must evaluate to `True`. These tests follow a few rules:
+
+* Tests prefixed with `Windows:` or `Posix:` are only tested against that specific
+  implementation - otherwise tests are run against both implementations.
+* Any single letter variable, e.g. `x`, is considered universal quantification, and is checked with `QuickCheck`.
+* If `Valid x =>` appears at the start of a doc test, that means the property
+  will only be tested with `x` passing the `isValid` predicate.
+
+The tests can be generated by `make gen` in the root of the repo, and will be placed in `tests/TestGen.hs`.
+The `TestGen.hs` file is checked into the repo, and the CI scripts check that `TestGen.hs` is in sync with
+what would be generated a fresh - if you don't regenerate `TestGen.hs` the CI will fail.
+
+The `.ghci` file is set up to allow you to type `ghci` to open the library, then `:go` will regenerate the
+tests and run them.

README.md

@@ -1,33 +1,38 @@
 # FilePath [![Hackage version](https://img.shields.io/hackage/v/filepath.svg?label=Hackage)](https://hackage.haskell.org/package/filepath)
 
-The `filepath` package provides functionality for manipulating `FilePath` values, and is shipped with both [GHC](https://www.haskell.org/ghc/) and the [Haskell Platform](https://www.haskell.org/platform/). It provides three modules:
+The `filepath` package provides functionality for manipulating `FilePath` values, and is shipped with [GHC](https://www.haskell.org/ghc/).
+It provides three modules:
 
-* [`System.FilePath.Posix`](http://hackage.haskell.org/package/filepath/docs/System-FilePath-Posix.html) manipulates POSIX/Linux style `FilePath` values (with `/` as the path separator).
-* [`System.FilePath.Windows`](http://hackage.haskell.org/package/filepath/docs/System-FilePath-Windows.html) manipulates Windows style `FilePath` values (with either `\` or `/` as the path separator, and deals with drives).
-* [`System.FilePath`](http://hackage.haskell.org/package/filepath/docs/System-FilePath.html) is an alias for the module appropriate to your platform.
+* [`System.FilePath.Posix`](http://hackage.haskell.org/package/filepath/docs/System-FilePath-Posix.html)
+  manipulates POSIX/Linux style `FilePath` values (with `/` as the path separator).
+* [`System.FilePath.Windows`](http://hackage.haskell.org/package/filepath/docs/System-FilePath-Windows.html)
+  manipulates Windows style `FilePath` values (with either `\` or `/` as the path separator, and deals with drives).
+* [`System.FilePath`](http://hackage.haskell.org/package/filepath/docs/System-FilePath.html)
+  is an alias for the module appropriate to your platform.
 
 All three modules provide the same API, and the same documentation (calling out differences in the different variants).
 
-### Should `FilePath` be an abstract data type?
+### What is a `FilePath`?
 
-The answer for this library is "no". While an abstract `FilePath` has some advantages (mostly type safety), it also has some disadvantages:
+In Haskell, the definition is `type FilePath = String` as of now. A Haskell `String` is a list of Unicode code points.
 
-* In Haskell the definition is `type FilePath = String`, and all file-oriented functions operate on this type alias, e.g. `readFile`/`writeFile`. Any abstract type would require wrappers for these functions or lots of casts between `String` and the abstraction.
-* It is not immediately obvious what a `FilePath` is, and what is just a pure `String`. For example, `/path/file.ext` is a `FilePath`. Is `/`? `/path`? `path`? `file.ext`? `.ext`? `file`?
-* Often it is useful to represent invalid files, e.g. `/foo/*.txt` probably isn't an actual file, but a glob pattern. Other programs use `foo//bar` for globs, which is definitely not a file, but might want to be stored as a `FilePath`.
-* Some programs use syntactic non-semantic details of the `FilePath` to change their behaviour. For example, `foo`, `foo/` and `foo/.` are all similar, and refer to the same location on disk, but may behave differently when passed to command-line tools.
-* A useful step to introducing an abstract `FilePath` is to reduce the amount of manipulating `FilePath` values like lists. This library hopes to help in that effort.
+On unix, filenames don't have a predefined encoding as per the
+<https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_170 POSIX specification>
+and are passed as @char[]@ to syscalls.
 
-### Developer notes
+On windows (at least the API used by `Win32`) filepaths are UTF-16 strings.
 
-Most of the code is in `System/FilePath/Internal.hs` which is `cpphs`'d into both `System/FilePath/Posix.hs` and `System/FilePath/Windows.hs` via `make cpp` and commited to the repo. This Internal module is a bit weird in that it isn't really a Haskell module, but is more an include file.
+This means that Haskell filepaths have to be converted to C-strings on unix
+(utilizing the current filesystem encoding) and to UTF-16 strings
+on windows.
 
-The library has extensive doc tests. Anything starting with `-- >` is transformed into a doc test as a predicate that must evaluate to `True`. These tests follow a few rules:
+Further, this is a low-level library and it makes no attempt at providing a more
+type safe variant for filepaths (e.g. by distinguishing between absolute and relative
+paths) and ensures no invariants (such as filepath validity).
 
-* Tests prefixed with `Windows:` or `Posix:` are only tested against that specific implementation - otherwise tests are run against both implementations.
-* Any single letter variable, e.g. `x`, is considered universal quantification, and is checked with `QuickCheck`.
-* If `Valid x =>` appears at the start of a doc test, that means the property will only be tested with `x` passing the `isValid` predicate.
+For such libraries, check out the following:
 
-The tests can be generated by `make gen` in the root of the repo, and will be placed in `tests/TestGen.hs`. The `TestGen.hs` file is checked into the repo, and the CI scripts check that `TestGen.hs` is in sync with what would be generated a fresh - if you don't regenerate `TestGen.hs` the CI will fail.
-
-The `.ghci` file is set up to allow you to type `ghci` to open the library, then `:go` will regenerate the tests and run them.
+* [hpath](https://hackage.haskell.org/package/hpath)
+* [path](https://hackage.haskell.org/package/path)
+* [paths](https://hackage.haskell.org/package/paths)
+* [strong-path](https://hackage.haskell.org/package/strong-path)

filepath.cabal

@@ -28,6 +28,7 @@ extra-source-files:
     System/FilePath/Internal.hs
 extra-doc-files:
     README.md
+    HACKING.md
     changelog.md
 
 source-repository head