
canonical_path_name(+Path, -CanonicalPath)

   Expand a path name into the full `canonical' form.

Arguments
   Path                A pathname (atom or string)
   CanonicalPath       Canonical pathname for Path

Type
   Operating System

Description
   This predicate expands a given pathname, and converts it into the
   `canonical' form of the pathname. The following are done to the path:


    An absolute path is returned. If a relative path is supplied, the
   path is prefixed with the current working directory. On Windows, a
   drive name is prefixed, if necessary.

    Leading '~' and environment variables (such as '$HOME') are
   substituted by the appropriate value. If this substitution is not
   possible (e.g. if the environment variable does not exist), nothing
   is changed.

    Special sequences such as '.', '..', extra '/' are appropriately
   removed/replaced. 

    The non-aliased path is returned, i.e. any symbolic links are
   replaced by the non-symbolic linked version of the path.
   
    On Windows and Mac OS X, where different cases of letters in
   path names are allowed but ignored (so e.g. "foo" and "Foo" are
   aliases), the `normalised' version of the name, using the letter
   cases when each file/directory was created, is returned
   (not supported in older versions of Windows before 2000).

    If the path denotes an existing directory, the canonical path
   is terminated with a '/'.



   Not all components of Path need to exist.  The removal of aliasing
   is performed only on the part of the path that does exist.


   The type of the returned CanonicalPath is the same as the type of
   Path (string or atom).  If Path is empty, it is replaced by the
   current working directory. 


    The predicates canonical_path_name/2 and existing_file/4 are intended
    as replacement for absolute_file_name/2 in previous releases. The
    functionality of completing an incomplete name and returning an
    absolute path of absolute_file_name/2 has been separated. The following
    approximately implements the old absolute_file_name/2:


    absolute_file_name(Rel, Abs) :-
	(Rel == user ->
	    Abs == user  % treat user specially
	; get_flag(prolog_suffix, Sufs),
	  (existing_file(Rel, Sufs, [], ExtRel) -> true ; ExtRel = Rel),
	  canonical_path_name(ExtRel, Abs)
        ).





Modes and Determinism
   canonical_path_name(+, -) is det

Exceptions
     5 --- Path is not a string or atom.

Examples
         [eclipse]: canonical_path_name("file", Full).  %cwd is /homes/tom
      Full = "/homes/tom/file"
      yes

      [eclipse]: canonical_path_name(file, Full).
      Full = '/homes/tom/file'
      yes

      [eclipse]: canonical_path_name("~/file", Full).
      Full = "/homes/tom/file"
      yes

      [eclipse]: canonical_path_name('file/..', Full).
      Full = '/homes/tom/'

      [eclipse]: canonical_path_name('/users/tom', Full). 
      % /users/tom is a symbolic link for /homes/tom
      Full = '/homes/tom/'


See Also
   existing_file / 4, os_file_name / 2, pathname / 4
