
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:


    A full path is returned. If a relative path is supplied, the
   path is prefixed with the current working directory

    leading '~' and environment variables (such as '$HOME') are
   substituted by the appropriate value. If this substitution is not
   possible (e.g. if the envrionment variable does not exist), the 
   original path is returned unchanged. 

    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,
   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 is a directory, a terminating '/' is always returned.



   Path does not need to exist, and only the removal of aliasing is 
   performed on the part of the path that does exist. 


   CanonicalPath is always the same type as 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
