4.5.2 Syntactic Rewriting

A file specification must be an atom or a compound term with arity 1. Such compound terms are transformed to atoms as described in ref-fdi-fsp. Let FileSpec be the given or transformed atomic file specification.

The file specification user stands for the standard input or output stream, depending on context.

A file specification FileSpec other than user is subject to syntactic rewriting. Depending on the operation, the resulting absolute filename is subject to further processing. Syntactic rewriting is performed wrt. a context directory Context (an absolute path), in the following steps:

• Under Windows, all ‘\’ characters are converted to ‘/’. This replacement is also performed, as needed, during all subsequent steps.
• A ‘$var’ in the beginning of FileSpec, followed by ‘/’ or the end of the path, is replaced by the absolute path of the value of the system property var. This is especially useful when the system property has no explicit value and thus takes its value from the environment variable with the same name. If var doesn't exist or its value is empty, a permission error is raised.

  A relative path that does not begin with ‘/’ is made absolute by prepending Context followed by a ‘/’. Note that, under UNIX, all paths that begin with ‘/’ are absolute.

  Under Windows only, a relative path that begins with a ‘/’ is made absolute by prepending the root (see below) of Context.

• A ‘~user’ in the beginning of FileSpec, followed by ‘/’ or the end of the path, is replaced by the absolute path of the home directory of user. If the home directory of user cannot be determined, a permission error is raised.

  Under Windows this has not been implemented, instead a permission error is raised.

  If the home directory of user is a relative path, it is made absolute using Context if needed.

• A ‘~’ in the beginning of FileSpec, followed by ‘/’ or the end of the path, is replaced by the absolute path of the home directory of the current user. If the home directory of the current user cannot be determined, a permission error is raised.

  The the home directory of the current user is a relative path it is made absolute using Context if needed.

  Under Windows, the home directory of the current user is determined using the system properties or environment variables HOMEDRIVE and HOMEPATH.

• If FileSpec is a relative file name, Context is prepended to it.
• The root of the file name is determined. Under UNIX this is simply the initial ‘/’, if any. Under Windows there are several variants of roots, as follows.
  • driveletter:/ where driveletter is a single upper or lower case character in the range ‘a’ to ‘z’. For example, ‘C:/’.
  • //?/driveletter:/ This is transformed to driveletter:/.
  • //host/share/ (a ‘UNC’ path, also known as a network path) where host and share are non-empty and do not contain /.
  • //?/unc/host/share/ This is transformed to //host/share/

  If no root can be determined a permission error is raised.

  A path is absolute if and only if it is begins with a root, as above.

• The following steps are repeatedly applied to the last ‘/’ of the root and the characters that follow it repeatedly until no change occurs.
  1. Repeated occurrences of / are replaced by a single /.
  2. ‘/.’, followed by ‘/’ or the end of the path, is replaced by ‘/’.
  3. /parent/.., followed by ‘/’ or the end of the path, is replaced by ‘/’.

  If the path still contains /.., followed by ‘/’ or the end of the path, a permission error is raised.

• Any trailing ‘/’ is deleted unless it is part of the root.
• Finally, under Windows, the path is normalized as follows: All Latin 1 characters (i.e. character codes in [0..255]) are converted to lower case. All other characters are converted to upper case.

  File systems under Windows are generally case insensitive. This step ensures that two file names that differ only in case, and therefore would reference the same file in the file system, will normalize to identical atoms.

  A downside to this normalization is that you cannot choose the case used for files created by SICStus Prolog on file systems such as NTFS that are case-preserving (but case-insensitive). For instance, you cannot create a file that has a mixed-case name in the file system, such as MyClass.java. Such a file would instead have a file system name myclass.java.

  This seldom matters, except for aesthetics, since any Windows application that tries to open a file named MyClass.java will also find myclass.java.

The following UNIX examples assumes that Context is ‘/usr/’; that the environment variables VAR1, VAR2, VAR3 have the values ‘/opt/bin’, ‘foo’ and ‘~/temp’ respectively and that the home directory of the current user, ‘joe’, is ‘/home/joe’.

     
     /foo/bar
        ==> /foo/bar
     
     /foo/.//bar/../blip///
        ==> /foo/blip
     
     /foo//../bar/../../blip
        ==> error
     
     $VAR1/../local/
        ==> /opt/local
     
     $VAR2/misc/.
        ==> /usr/foo/misc
     
     $VAR3/misc/.
        ==> /home/joe/temp/misc
     
     ~joe/../jenny/bin.
        ==> /home/jenny/bin
     

The following Windows examples assume that Context is ‘C:/Source/proj1’; that the environment variables VAR1, VAR2, VAR3 have the values ‘\\server\docs\brian’, ‘foo’ and ‘~/temp’ respectively and that the home directory of the current user is ‘C:/home’.

     
     /foo/bar
        ==> C:/foo/bar
     
     foo//../../blip
        ==> c:/source/blip
     
     $VAR1/../local/
        ==> //server/docs/local
     
     $VAR2/misc/.
        ==> c:/source/proj1/foo/misc
     
     $VAR3/misc/.
        ==> c:/home/temp/misc
     
     ~joe/../jenny/bin.
        ==> error