--[[----------------------------------------------------------------------------

KSPathUtils.lua

--------------------------------------------------------------------------------

ADOBE CONFIDENTIAL
------------------
Copyright 2011 Adobe Systems Incorporated
All Rights Reserved.

NOTICE: All information contained herein is, and remain the property of
Adobe Systems Incorporated and its suppliers, if any. The intellectual and
technical concepts contained herein are proprietary to Adobe Systems
Incorporated and its suppliers and may be covered by U.S. and Foreign
Patents, patents in process, and are protected by trade secret or copyright
law.  Dissemination of this information or reproduction of this material is
strictly forbidden unless prior written permission is obtained from
Adobe Systems Incorporated.

------------------------------------------------------------------------------]]

	-- WF.core.os
local KSPathUtilsImp = require 'KSPathUtilsImp'

	-- WF.core.utils
local WFArguments = require 'WFArguments'

--============================================================================--

-- @mark KSPathUtils namespace

--[[!

\class KSPathUtils

\brief This namespace provides cross-platform path-manipulation utilities.

]]--


local KSPathUtils = {}

--------------------------------------------------------------------------------
--[[!
	Retrieves a standard system-defined path.

	\param name (string) The name of the path to find. One of these values:
	<ul><li>"app" (current application install folder)</li>
	    <li>"appBuiltInPlugins" (folder for built-in plug-ins: see [ NSBundle builtInPlugInsPath ] )</li>
		<li>"adobeAppData" (Adobe application support data)</li>
		<li>"home" (user's home folder)</li>
		<li>"caches"</li>
		<li>"carouselDocuments" (the package in the pictures folder for revel documents.
			For example, <code>~/Pictures/Adobe Revel/Adobe Revel Library.rvl</code> in Mac OS. </li>
		<li>"carouselCaches" (caches subfolder specific to Adobe Revel)</li>
		<li>"documents" (user documents)</li>
		<li>"pictures" (user pictures)</li>
		<li>"desktop"</li>
		<li>"applications"</li>
		<li>"temp"</li>
		<li>"testdata" (path to dir in app package for test data)</li>
		<li>"Resources" (application resources)</li>
		<li>"TranslatedStrings" (dictionary <em>file</em> for locale-specific translated strings)</li>
	  </ul>

	\return (string) The file path.
]]--

function KSPathUtils.getStandardFilePath( --[[string]] name )
	-- WFArguments.check( "string" )
	-- This wrapper exists only for documentation purposes; real implementation
	-- comes from native code (see "Real implementation" below).
end

--------------------------------------------------------------------------------
--[[!
	Concatenates a folder name to a base path to form a new system path.

	\param base (string) The base file path.
	\param name (string) The name of the contained folder.
	
	\return (string) The complete path.
]]--

function KSPathUtils.child( --[[string]] base, --[[string]] name )
	-- WFArguments.check( "string", "string" )
	-- This wrapper exists only for documentation purposes; real implementation
	-- comes from native code (see "Real implementation" below).
end

--------------------------------------------------------------------------------
--[[!
	Strips the leaf file-name part from a full path.
	
	\param path (string) The path string.
	
	\return (string) The path of the folder containing the file.
]]--

function KSPathUtils.parent( --[[string]] path )
	-- WFArguments.check( "string" )
	-- This wrapper exists only for documentation purposes; real implementation
	-- comes from native code (see "Real implementation" below).
end

--------------------------------------------------------------------------------
--[[!
	Retrieves the leaf file-name part of a full path.

	\param path (string) The path string.
	
	\return (string) The file name.
]]--

function KSPathUtils.leafName( --[[string]] path )
	-- WFArguments.check( "string" )
	-- This wrapper exists only for documentation purposes; real implementation
	-- comes from native code (see "Real implementation" below).
end

--------------------------------------------------------------------------------
--[[!
	WINDOWS ONLY: Retrieve the short path name. The result can be used to open
	files with unicode name using the standard lua file.io functions.

	\param path (string) The file path. If the path does not exist, it will
		be created.
	
	\return (string) The short file path.
]]--

function KSPathUtils.shortPath( --[[string]] path )
	-- WFArguments.check( "string" )
	-- This wrapper exists only for documentation purposes; real implementation
	-- comes from native code (see "Real implementation" below).
end



--==============================================================================
-- @mark The real implementation
--==============================================================================

KSPathUtils = KSPathUtilsImp

--------------------------------------------------------------------------------

-- TODO [scouten 2015-08-22]: Remove this when we have a better understanding
-- of the TiC file permissions issue on Windows. For now, allow user to hack in
-- an alternate file path for sync data via environment variable.

--------------------------------------------------------------------------------

local overrideSyncPath = os.getenv( "OVERRIDE_SYNC_PATH" )

if overrideSyncPath then

	local overrideSelectors = {
		caches = true,
		carouselDocuments = true,
		carouselCaches = true,
		appSpecificCache = true,
	}
	
	local didCreateSyncPath = false

	local oldGetStandardFilePath = KSPathUtils.getStandardFilePath

	function KSPathUtils.getStandardFilePath( selector )

		if overrideSelectors[ selector ] then

			if not didCreateSyncPath then
				didCreateSyncPath = true
				require 'WFFileUtils'.mkdir( overrideSyncPath )
			end

			return overrideSyncPath

		else

			return oldGetStandardFilePath( selector )

		end

	end

end

--------------------------------------------------------------------------------

--[[!
	Check if a path is a parent of another path/file.

	\param maybeParentPath (string) the potential parent path.
	\param maybeChildPath (string) the potential child path.
	
	\return (boolean) Returns true if maybeParentPath is a parent path of maybeChildPath.
]]--

function KSPathUtils.isPathParentOf( --[[string]] maybeParentPath, --[[string]] maybeChildPath )

	WFArguments.check( "string", "string" )
	
	local previousPathToCheck
	local pathToCheck = maybeChildPath
	
	while pathToCheck ~= previousPathToCheck do
	
		if maybeParentPath == pathToCheck then
			return true
		end
	
		previousPathToCheck = pathToCheck
		pathToCheck = KSPathUtils.parent( pathToCheck )
	
	end
	
	return false
	
end

--------------------------------------------------------------------------------

local WFPlatformInfo = require 'WFPlatformInfo'

if not WFPlatformInfo.isWindows then
	function KSPathUtils.shortPath( path )
		return path
	end
end

--==============================================================================

return KSPathUtils
