File and Folder References

SenseTalk provides several methods for working with files and file systems. You can use the commands and functions described here to access files and file system information, to determine or change your working directory, and other details about paths and directories. You can also access properties for individual files, such as file size and assigned permissions.

note

SenseTalk commands and functions for working with files and file system objects operate on the local machine rather than on a system under test (SUT).

The examples below show you how to access file and file system information by using SenseTalk. For topics such as creating or deleting files, writing to files, and other ways of altering files or file system objects, see File and Folder Interaction.

note

As a best practice, any files referenced within a SenseTalk script should be added to Eggplant Functional through the Resources pane in the Suite window. This method stores files to the Resources directory within the suite directory for the given suite. Although SenseTalk can access files stored elsewhere on the local file system, using the Resources directory provides additional capabilities. See the Resources Pane for more information.

Referring to Files in a Script

File, Folder Expression

To refer to a file in a script, just use the word file followed by an expression that evaluates to the name of the file. You can refer to folders in a similar way, using the word folder instead of file.

Syntax:
file filePath
folder filePath
directory filePath

note

The words folder and directory are used interchangeably within SenseTalk scripts—wherever the word folder is used in a script, you can use the word directory instead.

The filePath can be the text of a path in either Mac/Linux or Windows format, or it can be a list in which each item is one component of the path.

The name given can be either the full (absolute) path name of the file or folder, or the path relative to the current working folder (see the folder global property). SenseTalk determines the full “absolute” path name of the file based on the name given, according to the following rules:

• if the name begins with a slash (/) or the first item in the path list is "/" it is already an absolute file name
• if the name begins with a drive letter and colon followed by a slash or backslash (like "C:\") or the first item in the path list is a drive letter and colon and the second item is a slash it is already an absolute file name
• if the name begins with a tilde and a slash (~/) it represents a path relative to the user’s home folder
• if the name begins with a tilde (~) followed by a user name it represents a path relative to that specific user’s home folder
• if the name begins with a period and a slash (./) or two periods and a slash (../) it represents a relative path from either the current working folder or the current working folder's parent folder, respectively
• otherwise, it represents a file or path within the current working folder (the folder global property)

note

File paths on Mac and Linux systems and on the web use the slash character / to separate path components, but Windows systems use the backslash character \ instead. SenseTalk accepts file paths in either format interchangeably (as well as lists of path components), but defaults to using slash / when representing paths. You may use the FilePath or WindowsFilePath functions if you need a platform-specific standard representation.

Example:

open file"/etc/passwd"
move file "runlog24" into folder "archivedLogs"

Folder, Directory Function

Behavior: Returns the parent folder of a given file path.

Use the folder function (or its synonym, directory) to obtain the path to the folder containing a given file or folder.

The value returned will end with a slash, unless the folderNamesEndWithSlash global property is set to false. The slash at the end makes it easy to create a full path name by simply appending a file name.

Syntax:
{the} folder of filePath
folder( filePath )

If the filePath given is not an absolute path it will be taken relative to the current working folder, as given by the folder global property. The folder function may also be called with a fileDescription object (such as returned by the files() or fileDescription() functions) or with a script file object, to obtain the parent folder of the indicated file.

The value returned by the folder function is actually a fileDescription object, but can simply be treated as a string for most purposes. Its string value is the full path to the folder.

Examples:

put the folder of myFile into myFolder

put folder(someFile) & "siblingFileName" into newFile

LastPathComponent Function

Behavior: Returns the local name of a file system object, removing the path to the parent folder.

Use the lastPathComponent function when you have the full path name of a file or folder and want to obtain just the local name, without the full path.

Syntax:
{the} lastPathComponent of filePath
lastPathComponent( filePath )

Examples:

put the lastPathComponent of fullPath into fileName

put lastPathComponent("/Users/jc/Documents/Jan24.data") --> Jan24.data

FileExtension Function

Behavior: Returns the file extension from a file name.

Use the fileExtension function when you have the full name of a file or folder and want to obtain just the file extension. The extension is the part of the name following the last period. The period is not included in the extension that is returned.

Syntax:
{the} fileExtension of fileName
fileExtension( fileName )

Examples:

put the fileExtension of fileName into extension

put fileExtension("/Users/jc/Documents/Jan24.data") --> data

PathList Function

Behavior: Returns a file path as a list of individual path components in a standard format.

Use the pathList function when you have the full or partial path name of a file or folder and want to obtain a path list containing the individual components of that path in a standard format.

Syntax:
{the} pathList of filePath
pathList( filePath )

Examples:

put the pathList of filePath into filePathList

put pathList("/Users/sj/Documents/MLK.txt") --> ["/","Users","sj","Documents","MLK.txt"]

FilePath, WindowsFilePath Functions

Behavior: The filePath function returns a file path as a string in a standard (Mac/Linux/web) format, with slashes / as the separator between path components. The windowsFilePath function is similar, but returns a file path string in Windows format, using backslashes \ as the separator between components.

Use the filePath or windowsFilePath function when you have a full or partial path name of a file or folder in any format and want to obtain either a standard Mac/Linux/web text representation of that path that uses slashes between path components, or a Windows text representation that uses backslashes between path components.

Syntax:
{the} filePath of filePath
filePath( filePath )
{the} windowsFilePath of filePath
windowsFilePath( filePath )

Examples:

put the filePath of fullPath into stdPath

put filePath("\wiki\en\Home") --> /wiki/en/Home

put windowsFilePath("/Admin/theo/x32.jpg") --> \Admin\theo\x32.jpg

put the filePath of ["a","b","c"] --> a/b/c

put windowsFilePath of ["a","b","c"] --> a\b\c

ResolvedFilePath Function

Behavior: Returns a file path as a string in a "resolved" standard format, which is the full absolute path to the file, taking into account the current folder if necessary, and resolving components such as ".." and "~".

Use the resolvedFilePath function when you want to determine the full actual path fo a file or folder. Because of path mechanisms such as "~" which refers to the user's home folder and ".." which refers to the parent folder of any folder it is possible to have multiple different paths which all refer to the same location. The resolvedFilePath can be used to obtain a standard representation of the path which can be used to compare paths to see if they represent the same file, for example.

Syntax:
{the} resolvedFilePath of filePath
resolvedFilePath( filePath )

Examples:

put the resolvedFilePath of fileName into resolvedName

if resolvedFilePath(it) is resolvedFilePath(saveFile) then
  //Do things
end if

FileDescription Function

Behavior: Returns a fileDescription object containing information about a given file.

Use the fileDescription() function to obtain a packet of information about a file or folder. The value returned is a fileDescription object. A fileDescription is a SenseTalk object (property list) that appears as the short name of the file if displayed as text, but knows its full path and also contains many pieces of additional information about the file.

Syntax:
{the} fileDescription of filePath
fileDescription( filePath )

The filePath may be the full path to a file, or the file name relative to the current working folder. The value returned is a fileDescription object.

FileDescription Object

A fileDescription object is a property list with its objectType set to “fileDescription”. A fileDescription object contains an asText property that is set to the local name of the file, so displaying the object will simply show the file’s name.

Each fileDescription object also holds a number of additional items of information. In particular, the long name property contains the full path name of the file. Other properties include the parent folder where the file is located, and such information as the file size, owner, and permissions. Use the keys() or archive() function (or delete the object’s asText property before displaying it) to find out exactly what information is available.

SenseTalk commands and functions that work with files, such as the copy file and rename commands and the diskSpace() function, recognize fileDescription objects that are used in place of file names, and will use the long name to identify the actual file. In this way, fileDescription objects can serve as file identifiers that can be stored in variables, passed as parameters, and so forth.

FileDescription objects can also be obtained from the files() and folders() functions, which each return a list of fileDescriptions.

Examples:

put fileDescription("/tmp/data") into fileInfo
put fileInfo is a fileDescription --> True
put fileInfo --> "data"   (the fileDescription displays itself as the local name)
put the long name of fileInfo --> "/tmp/data"   (the object contains the full path name)

put fileInfo's NSFileSize into dataSize

SpecialFolderPath Function

Behavior: Returns the file system path to any of a number of special folders on the host computer where SenseTalk is running.

Parameters: The name of a special folder to get the path to that folder. Folders supported include: "home", "system", "library", "applications", "demo applications", "developer applications", "admin applications", "developer", "users", "documentation", "documents", "core services", "desktop", "caches", "application support", "fonts", "preferences", "temporary" (or "temp"), and "root".

Call the function with a tilde (~) followed by the login name of a user to get the path to that user's home folder, as shown in the second example below.

An optional second parameter can be given to specify the domain for the folder. The domainName can be one of the following: "user", "local", "network", "system", or "all". When a domain of "all" is given, more than one path might be returned, as a list. If no domain is specified, a domain appropriate for the folder being requested will be assumed.

Syntax:
specialFolderPath( folderName {, domainName} )
{the} specialFolderPath of folderName
{the} [temporary | temp | home | documents | desktop] folder

Example:

put specialFolderPath("applications") --> "/Applications"

Example:

put specialFolderPath("~brenda") --> "/Users/brenda"

Example:

put specialFolderPath("library", "local") --> "/Library"

tip

For a few commonly used folders, you can use the simple alternate syntax shown below. Note that this option works only with the temporary (temp), home, documents, and desktop folders.

Example:

put the temporary folder -- the path for the current user's temporary folder
put the home folder -- "/Users/<user_name>" where <user_name> is the name of the current user
put the documents folder -- "/Users/<user_name>/Documents"
put the desktop folder -- "/Users/<user_name>/Desktop"

Accessing File Properties

You can access a number of different properties of a file or folder. The following properties are accessible:

File Property Name	Description
name	the name of the file, such as “myFile.txt”
short name	the name without the extension — “myFile”
long name	the full path name of the file, such as “/tmp/myFile.txt”
display name	the name that should be displayed to the user
folder or directory	the full path name of the folder containing the file
size	the size of the file in bytes
creation date	the date/time when the file was created
modification date	the date/time when the file was last changed
permissions	a string denoting the file permissions (see below)
owner permissions	”read”, “write”, and/or “execute”
group permissions	”read”, “write”, and/or “execute”
other permissions	”read”, “write”, and/or “execute”
locked or immutable	the locked state of the file
entry type	“File”, “Folder”, “SymbolicLink”, “Socket”, “CharacterSpecial”, “BlockSpecial”, or “Unknown”
owner name	the login name of the owner of the file
group name	the name of the group the file is owned by
owner id	the user id number of the file’s owner
group id	the group id number of the file’s owner
link destination	for symbolic links, this gives the relative path name of the linked-to file

The permissions property is a string, similar to that reported by the ls -l command in Unix. It consists of 9 characters, rwxrwxrwx indicating read, write, and execute permissions for the owner, group, and others. Any permissions that are not present are replaced by dashes, so a permissions value of rwxr-xr-x, for example, would indicate a file that is readable and executable by everyone but writable only by the owner. The special permissions flags are indicated by additional items appended with separating commas when they apply. These include setuid, setgid, and sticky. So, the permissions value for a setuid file might be rwxr-xr-x,setuid.

The properties creation date, modification date, owner permissions, group permissions, other permissions, permissions, owner id, and group id may be set (using the set command) as well as retrieved. All other file properties are read-only.

To access the properties of a link directly (rather than the file or folder it links to), use the word link instead of file or folder.

The value of the folder property will end with a slash, unless the folderNamesEndWithSlash global property is set to false. The slash at the end makes it easy to create a full path name by simply appending a file name.

Syntax:
{the} fileProperty of [file | folder] fileName

Examples:

put the short name of file "/tmp/Friday.rtf"-- "Friday"

add the size of file datafile1 to filesizeTotal

Checking the Existence of a File or Folder

there is a file, file ... exists Operators

You can check whether a file exists by using the there is a file or file ... exists operators, or their negative counterparts to determine that a file or folder doesn’t exist:

Syntax:
there is a [file | folder] fileName
[file | folder] fileName exists
there is [not a | no] [file | folder] fileName
[file | folder] fileName [does not | doesn't] exist

Examples:

if file "tempWorkFile" exists then delete file "tempWorkFile"

if there is a file "scores" then
  put file "scores" into highScoreselse
  put "100,100,100,100,100" into highScores
end if

// Create an empty data file if it does not already exist:
if there is no file "data" then put "" into file "data"

You can check for the existence of a folder in the same way.

if folder "/tmp/work" does not exist then initWorkFolder