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

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

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 (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
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.

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 (see Syntax, below) 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/UNIX 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 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 (a property list with 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() 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"

put the long name of FileInfo-- "/tmp/data"

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 domain 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})

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:

putthe temporary folder-- Returns the path for the current user's temporary folder

putthe home folder-- "/Users/<user_name>" where <user_name> is the name of the current user

putthe documents folder-- "/Users/<user_name>/Documents"

putthe 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
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
immutable

the locked state of the file

entry type

“File”, “Folder”, “SymbolicLink”, “Socket”, “CharacterSpecial”, “BlockSpecial”, or “Unknown”

type code

HFS type code, as a 4-character string

creator code

HFS creator code, as a 4-character string

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 berwxr-xr-x,setuid.

The properties creation date, modification date, owner permissions, group permissions, other permissions, permissions, type code, creator code, 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

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

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

 

This topic was last updated on May 29, 2020, at 11:42:02 AM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2020 Eggplant