Copyright (C) 2011 Dr. Alistair Ward

	This program is free software: you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation, either version 3 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program.  If not, see <http://www.gnu.org/licenses/>.
{- |
 [@AUTHOR@]	Dr. Alistair Ward

 [@DESCRIPTION@]	File-operations.

module ToolShed.System.File(
-- * Types
-- ** Type-synonyms
-- * Functions
-- ** Accessors
) where

import			Control.Applicative((<$>))
import qualified	Control.Exception
import qualified	Control.Monad
import qualified	Data.List
import qualified	System.Directory
import qualified	System.FilePath
import			System.FilePath((</>))
import qualified	System.IO.Error

-- | The ordered sequence of directories, searched for a file.
type SearchPath	= [System.FilePath.FilePath]

{- |
	* When supplied with an /absolute/ file-path, the /search-path/ is ignored and an exception is thrown if either the file-path is invalid or the file doesn't exist.

	* If the specified file-name is /relative/, all matching instances on the specified /search-path/ are returned.

	* CAVEAT: doesn't perform file-globbing.
locate :: System.FilePath.FilePath -> SearchPath -> IO [System.FilePath.FilePath]
locate fileName searchPath
	| System.FilePath.isRelative fileName'		= Control.Monad.filterM System.Directory.doesFileExist . filter System.FilePath.isValid . Data.List.nubBy System.FilePath.equalFilePath $ map (System.FilePath.normalise . (</> fileName')) searchPath
	| not $ System.FilePath.isValid fileName'	= Control.Exception.throw . System.IO.Error.userError $ "Invalid filename; " ++ fileName'
	| otherwise					= do
		fileExists	<- System.Directory.doesFileExist fileName'

		if not fileExists
			then Control.Exception.throw . System.IO.Error.mkIOError System.IO.Error.doesNotExistErrorType "No such file" Nothing $ Just fileName'
			else return {-to IO-monad-} [fileName']
		fileName'	= System.FilePath.normalise fileName

-- | A file-path, and the contents read from it.
type LocatedData a	= (System.FilePath.FilePath, a)

-- | Accessor.
getFilePath :: LocatedData a -> System.FilePath.FilePath
getFilePath	= fst

-- | Accessor.
getData :: LocatedData a -> a
getData	= snd

{- |
	Traverse the /search-path/, looking for matching instances of the specified file-name,
	and either throw an exception, or return a pair composed from the path to the first matching file, together with its contents.
getFile :: System.FilePath.FilePath -> SearchPath -> IO (LocatedData String)
getFile fileName directories	= do
	filePaths	<- locate fileName directories

	if null filePaths
		then Control.Exception.throw . System.IO.Error.mkIOError System.IO.Error.doesNotExistErrorType ("Can't find in " ++ show directories) Nothing $ Just fileName
		else {-located-} let
			filePath	= head filePaths	--Discard any subsequent paths.
		in (,) filePath <$> readFile filePath

{- |
	* Returns the polymorphic data, read from the first matching file on the /search-path/, along with the path from which it was read.

	* Returns an error on failure to parse the contents of the first matching file found on the /search-path/.
fromFile :: Read a => System.FilePath.FilePath -> SearchPath -> IO (LocatedData a)
fromFile fileName directories	= do
	(filePath, fileContents)	<- getFile fileName directories

	case reads fileContents of
		[(x, _)]	-> return {-to IO-monad-} (filePath, x)	--CAVEAT: discards any unconsumed text.
		_		-> error $ "ToolShed.System.File.fromFile:\tfailed to parse file=" ++ show filePath