Add a subset of path manipulation functionality (#1)

* Add a subset of path manipulation functionality

* Review changes and version bump

* Add documentation for lua users

* Update README.md

Author: gabyx

.gitignore

@@ -1,3 +1,6 @@
 /dist
 /.ghc.environment.*
-/.stack-work
+/.stack-work
+/dist-newstyle
+
+/stack.yaml.lock

README.md

@@ -1,5 +1,4 @@
-HsLua Module: System
-====================
+# HsLua Module: System
 
 This module provides access to system information and functionality via
 Haskell's `System` module.
@@ -8,9 +7,7 @@ Intended usage for this package is to preload it by adding the loader
 function to `package.preload`. Note that the Lua `package` library must
 have already been loaded before the loader can be added.
 
-
-Example
--------
+## Example
 
 ``` haskell
 loadProg :: Lua Status
@@ -22,31 +19,29 @@ loadProg = do
           ++ "system.with_tmpdir('.', 'foo', print)"
 ```
 
+## Documentation
 
-Documentation
--------------
-
-## Fields
+### Fields
 
-### arch
+#### arch
 
 The machine architecture on which the program is running.
 
-### compiler_name
+#### compiler_name
 
 The Haskell implementation with which the host program was compiled.
 
-### compiler_version
+#### compiler_version
 
 The version of `compiler_name` with which the host program was compiled.
 
-### os
+#### os
 
 The operating system on which the program is running.
 
-## Functions
+### General Functions
 
-### env
+#### env
 
 `env ()`
 
@@ -57,7 +52,7 @@ Returns:
 - A table mapping environment variables names to their string value
   (table).
 
-### getenv
+#### getenv
 
 `getenv (var)`
 
@@ -74,7 +69,7 @@ Returns:
 - value of the variable, or nil if the variable is not defined (string
   or nil).
 
-### getwd
+#### getwd
 
 `getwd ()`
 
@@ -84,7 +79,7 @@ Returns:
 
 - The current working directory (string).
 
-### ls
+#### ls
 
 `ls ([directory])`
 
@@ -101,7 +96,7 @@ Returns:
 - A table of all entries in `directory` without the special entries (`.`
   and `..`).
 
-### mkdir
+#### mkdir
 
 `mkdir (dirname [, create_parent])`
 
@@ -123,7 +118,7 @@ Parameters:
 `create_parent`
 :   create parent directories if necessary
 
-### rmdir
+#### rmdir
 
 `rmdir (dirname [, recursive])`
 
@@ -138,7 +133,7 @@ Parameters:
 `recursive`
 :   delete content recursively
 
-### setenv
+#### setenv
 
 `setenv (var, value)`
 
@@ -152,7 +147,7 @@ Parameters:
 `value`
 :   new value (string).
 
-### setwd
+#### setwd
 
 `setwd (directory)`
 
@@ -164,7 +159,7 @@ Parameters:
 :   Path of the directory which is to become the new working
     directory (string)
 
-### tmpdirname
+#### tmpdirname
 
 `tmpdirname ()`
 
@@ -189,7 +184,7 @@ Returns:
 
 - The current directory for temporary files (string).
 
-### with\_env
+#### with\_env
 
 `with_env (environment, callback)`
 
@@ -211,9 +206,9 @@ Parameters:
 
 Returns:
 
--   The result(s) of the call to `callback`
+- The result(s) of the call to `callback`
 
-### with\_tmpdir
+#### with\_tmpdir
 
 `with_tmpdir ([parent_dir,] templ, callback)`
 
@@ -236,9 +231,9 @@ Parameters:
 
 Returns:
 
--   The result of the call to `callback`.
+- The result of the call to `callback`.
 
-### with\_wd
+#### with\_wd
 
 `with_wd (directory, callback)`
 
@@ -258,11 +253,223 @@ Parameters:
 
 Returns:
 
--   The result(s) of the call to `callback`
+- The result(s) of the call to `callback`
+
+### Path Manipulation Functions
+
+This library includes wrappers around the following functions from the [filepath](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath.html) library for the current platform (POSIX or Windows). All examples below are for [POSIX systems](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html).
+
+#### take_directory
+
+`take_directory(filepath)`
+
+Get the directory name, move up one level.
+
+```lua
+takeDirectory("/foo/bar/baz") == "/foo/bar"
+takeDirectory("/foo/bar/baz/") == "/foo/bar/baz"
+```
+
+Parameters:
+
+`filepath`
+:   path path
+
+Returns:
+
+- The modified filepath.
+
+This function wraps [System.FilePath.takeDirectory](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:takeDirectory).
+
+#### take_filename
+
+`take_filename(filepath)`
+
+Get the file name.
+
+```lua
+takeFileName("/directory/file.ext") == "file.ext"
+takeFileName("test/") == ""
+```
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- The file name.
+
+This function wraps [System.FilePath.takeFileName](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:takeFileName).
+
+#### take_extensions
+
+`take_extensions(filepath)`
+
+Get all extensions.
+
+```lua
+takeExtensions("/directory/path.ext") == ".ext"
+takeExtensions("file.tar.gz") == ".tar.gz
+```
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- String of all extensions.
+
+This function wraps [System.FilePath.takeExtensions](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:takeExtensions).
+
+#### drop_extension
+
+`drop_extension(filepath)`
+
+Remove last extension, and the `.` preceding it.
+
+```lua
+dropExtension("/directory/path.ext") == "/directory/path"
+```
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- The modified filepath without extension.
+
+This function wraps [System.FilePath.dropExtension](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:dropExtension).
+
+#### has_extension
+
+`has_extensions(filepath)`
+
+Does the given filename have an extension?
+
+```lua
+hasExtension("/directory/path.ext") == true
+hasExtension("/directory/path") == false
+```
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- `true` if `filepath` has an extension.
+
+This function wraps [System.FilePath.hasExtension](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:hasExtension).
+
+#### split_directories
+
+`split_directories(filepath)`
+
+Split a path by the directory separator.
+
+```lua
+splitDirectories("/directory/file.ext") == {"/","directory","file.ext"}
+splitDirectories("test/file") == {"test","file"}
+splitDirectories("/test/file") == {"/","test","file"}
+```
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- A list of all directory paths.
+
+This function wraps [System.FilePath.splitDirectories](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:splitDirectories).
+
+#### join_path
+
+`join_path(filepath)`
+
+Join path elements back together by the directory separator.
+
+```lua
+joinPath({"/","directory/","file.ext"}) == "/directory/file.ext"
+```
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- The joined path.
+
+This function wraps [System.FilePath.joinPath](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:joinPath).
+
+#### is_relative
+
+`ìs_relative(filepath)`
+
+Is a path relative, or is it fixed to the root?
+
+```lua
+isRelative("test/path") == true
+isRelative("/test") == false
+isRelative("/") == false
+```
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- `true` if `filepath` is a relative path.
+
+This function wraps [System.FilePath.isRelative](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:isRelative).
+
+#### is_absolute
+
+`is_absolute(filepath)`
+
+Is a path absolute? (same as `! is_relative(filepath)`)
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- `true` if `filepath` is an absolute path.
+
+This function wraps [System.FilePath.isAbsolute](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:isAbsolute).
+
+#### normalise
+
+`normalise(filepath)`
+
+Normalise a path. See examples [here](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:normalise).
+
+Parameters:
+
+`filepath`
+:   path
+
+Returns:
+
+- The normalised path.
 
+This function wraps [System.FilePath.normalise](https://hackage.haskell.org/package/filepath-1.4.2.1/docs/System-FilePath-Posix.html#v:normalise).
 
-License
--------
+## License
 
 This package is licensed under the MIT license. See [`LICENSE`](LICENSE)
 for details.