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.
On this page:
- Referring to Files in a Script
- Folder, Directory Functions
- LastPathComponent Function
- FileExtension Function
- PathList Function
- FilePath, WindowsFilePath Functions
- ResolvedFilePath Function
- FileDescription Function
- SpecialFolderPath Function
- Accessing File Properties
- Checking the Existence of a File or Folder
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
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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
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)
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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)
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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)
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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)
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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)
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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)
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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)
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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})
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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
|
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
|
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
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
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
Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant