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.

A file specification FileSpec 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 ‘$PROP’ 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 PROP. 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 does not exist or its value is empty, then 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, then 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, then 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, then a permission error is raised.

  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, then 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, then 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, then a permission error is raised.

• Any trailing ‘/’ is deleted unless it is part of the root.
• Finally, under Windows, the case-normalized path is obtained 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 case-normalize to identical atoms.

  Since release 4.3, open/[3,4], and other build-in predicates that create files and directories, creates files using the file name argument as obtained from syntactic rewriting but before applying case-normalization. This means that open('HelloWorld.txt', write, S), file_property(S,file_name(Name). will create a file that has the mixed-case name HelloWorld.txt in the file system but Name will end in ‘helloworld.txt’, i.e. the stream property will reflect the case-normalized path.

  The fact that open/[3,4] et al. preserves case when creating files seldom matters, except for aesthetics, since any Windows application that tries to open a file named HelloWorld.txt will also find helloworld.txt.

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