[commit: packages/filepath] master: #12, add notes on why FilePath isn't abstract (59b8639)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/filepath

On branch  : master
Link       : http://git.haskell.org/packages/filepath.git/commitdiff/59b8639890fbf246d46a66147191458d1587fb98

>---------------------------------------------------------------

commit 59b8639890fbf246d46a66147191458d1587fb98
Author: Neil Mitchell <ndmitchell at gmail.com>
Date:   Tue Dec 22 07:51:11 2015 +0000

    #12, add notes on why FilePath isn't abstract


>---------------------------------------------------------------

59b8639890fbf246d46a66147191458d1587fb98
 README.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/README.md b/README.md
index f2ff622..536f88c 100644
--- a/README.md
+++ b/README.md
@@ -7,3 +7,12 @@ The `filepath` package provides functionality for manipulating `FilePath` values
 * [`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?
+
+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`, and all file-orientated 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.