• Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint

Specifying Paths

When creating a File or Folder object, you can specify a platform-specific path name, or an absolute or relative path in a platform-independent format known as universal resource identifier (URI) notation. The path stored in the object is always an absolute, full path name that points to a fixed location on the disk.

  • Use the toString method to obtain the name of the file or folder as string containing an absolute path name in URI notation.

  • Use the fsName (page 142) property to obtain the platform-specific file name.

Absolute and relative path names

An absolute path name in URI notation describes the full path from a root directory down to a specific file or folder. The path starts with one or two slashes (/), and a slash separates path elements. For example, the following describes an absolute location for the file myFile.jsx:


A relative path name in URI notation is appended to the path of the current directory, as stored in the globally available current (page 148) property of the Folder class. The path starts with a folder or file name, or with one of the special names dot (.) for the current directory, or dot dot (. .) for the parent of the current directory. A slash (/) separates path elements. For example, the following paths describe various relative locations for the file myFile.jsx:

myFile.jsxIn the current directory.
../myFile.jsxIn the parent of the current directory.
../../myFile.jsxIn the grandparent of the current directory.
../dir1/myFile.jsxIn dir1, which is parallel to the current directory.

Relative path names are independent of different volume names on different machines and operating systems, and therefore make your code considerably more portable. You can, for example, use an absolute path for a single operation, to set the current directory in the Folder.current property, and use relative paths for all other operations. You would then need only a single code change to update to a new platform or file location.

Character interpretation in paths

There are some platform differences in how path names are interpreted:

  • In Windows and Mac OS, path names are not case sensitive. In UNIX, paths are case sensitive.

  • In Windows, both the slash (/) and the backslash (\) are valid path element separators.

  • In Mac OS, both the slash (/) and the colon (:) are valid path element separators.

If a path name starts with two slashes (or backslashes in Windows), the first element refers to a remote server. For example, //myhost/mydir/myfile refers to the path /mydir/myfile on the server myhost.

URI notation allows special characters in path names, but they must specified with an escape character (%) followed by a hexadecimal character code. Special characters are those that are not alphanumeric and not one of the following characters:

/ - — . ! ~ * ' ( )

A space, for example, is encoded as %20, so the file name "my file" is specified as "my%20file". Similarly, the character ä is encoded as %E4, so the file name "Bräun" is specified as "Br%E4un".

This encoding scheme is compatible with the global JavaScript functions encodeURI and decodeURI.

The home directory

A path name can start with a tilde (~) to indicate the user’s home directory. It corresponds to the platform’s HOME environment variable.

UNIX and Mac OS assign the HOME environment variable according to the user login. In Mac OS, the default home directory is /Users/username. In UNIX, it is typically /home/username or /users/username. Extend Script assigns the home directory value directly from the platform value.

In Windows, the HOME environment variable is optional. If it is assigned, its value must be a Windows path name or a path name referring to a remote server (such as \\myhost\mydir). If the HOME environment variable is undefined, the Extend Script default is the user’s home directory, usually the C:\Documents and Settings\username folder.


A script can access many of the folders that are specified with platform-specific variables through static, globally available Folder class properties (page 148); for instance, appData (page 148) contains the folder that stores application data for all users.

Volume and drive names

A volume or drive name can be the first part of an absolute path in URI notation. The values are interpreted according to the platform.

Mac OS volumes

When Mac OS X starts, the startup volume is the root directory of the file system. All other volumes, including remote volumes, are part of the /Volumes directory. The File and Folder objects use these rules to interpret the first element of a path name:

  • If the name is the name of the startup volume, discard it.

  • If the name is a volume name, prepend /Volumes.

  • Otherwise, leave the path as is.

Mac OS 9 is not supported as an operating system, but the use of the colon as a path separator is still supported and corresponds to URI and to Mac OS X paths as shown in the following table. These examples assume that the startup volume is MacOSX, and that there is a mounted volume Remote.

URI path nameMac OS 9 path nameMac OS X path name
~/dir/file /Users/jdoe/dir/file

Windows drives

In Windows, volume names correspond to drive letters. The URI path /c/temp/file normally translates to the Windows path C:\temp\file.

If a drive exists with a name matching the first part of the path, that part is always interpreted as that drive. It is possible for there to be a folder in the root that has the same name as the drive; imagine, for example, a folder C:\C in Windows. A path starting with /c always addresses the drive C:, so in this case, to access the folder by name, you must use both the drive name and the folder name, for example /c/c for C:\C.

If the current drive contains a root folder with the same name as another drive letter, that name is considered to be a folder. That is, if there is a folder D:\C, and if the current drive is D:, the URI path /c/temp/file translates to the Windows path D:\c\temp\file. In this case, to access drive C, you would have to use the Windows path name conventions.

To access a remote volume, use a uniform naming convention (UNC) path name of the form //servername/sharename. These path names are portable, because both Max OS X and UNIX ignore multiple slash characters. Note that in Windows, UNC names do not work for local volumes.

These examples assume that the current drive is D:

URI path nameWindows path name
~/dir/fileC:\Documents and Settings\jdoe\dir\file


When you access an alias, the operation is transparently forwarded to the real file. The only operations that affect the alias are calls to rename and remove, and setting properties readonly and hidden. When a File object represents an alias, the alias property of the object returns true, and the resolve method returns the File or Folder object for the target of the alias.

In Windows, all file system aliases (called shortcuts) are actual files whose names end with the extension .lnk. Never use this extension directly; the File and Folder objects work without it.

For example, suppose there is a shortcut to the file /folder1/some.txt in the folder /folder2. The full Windows file name of the shortcut file is \folder2\some.txt.lnk.

To access the shortcut from a File object, specify the path /folder2/some.txt. Calling that File object’s open method opens the linked file (in /folder1). Calling the File object’s rename method renames the shortcut file itself (leaving the .lnk extension intact).

However, Windows permits a file and its shortcut to reside in the same folder. In this case, the File object always accesses the original file. You cannot create a File object to access the shortcut when it is in the same folder as its linked file.

A script can create a file alias by creating a File object for a file that does not yet exist on disk, and using its createAlias (page 143) method to specify the target of the alias.

Portability issues

If your application will run on multiple platforms, use relative path names, or try to originate path names from the home directory. If that is not possible, work with Mac OS X and UNIX aliases, and store your files on a machine that is remote to your Windows machine so that you can use UNC names.

As an example, suppose you use the UNIX machine myServer for data storage. If you set up an alias share in the root directory of myServer, and if you set up a Windows-accessible share at share pointing to the same data location, the path name //myServer/share/file would work for all three platforms.

  • Creative Edge
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint