File.hs

{-
	Copyright (C) 2011-2015 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
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	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
	SearchPath,
	LocatedData,
-- * Functions
	locate,
	getFile,
	fromFile,
-- ** Accessors
	getFilePath,
	getData
) where

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.throwIO . System.IO.Error.userError $ "Invalid filename; " ++ fileName'
	| otherwise					= do
		fileExists	<- System.Directory.doesFileExist fileName'

		if not fileExists
			then Control.Exception.throwIO . System.IO.Error.mkIOError System.IO.Error.doesNotExistErrorType "No such file" Nothing $ Just fileName'
			else return {-to IO-monad-} [fileName']
	where
		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.throwIO . 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 `fmap` 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 . showString "ToolShed.System.File.fromFile:\tfailed to parse file=" $ shows filePath "."