Get the List of Files in a Directory Functions
The following functions allow getting the names of files in a directory in a predefined folder of the current project directory. The file system location allowed to append data is the folder shared\scripting of the current project. For example, [Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting.
The file names returned include their relative paths in the shared\scripting predefined folder.
Such functions can be run synchronously or asynchronously, and in the last case, it is necessary to provide a callback method that will be executed when the operation is completed.
fileGetListSync
The fileGetListSync function allows getting the names of files that match the specified <searchPattern> in the directory specified by <relativePath> in the predefined folder. It can also search any subdirectories (<includeSubdirectories> = true).
fileGetList
The fileGetList function allows getting asynchronously the names of files that match the specified <searchPattern> in the directory specified by <relativePath> in the predefined folder. It can also search any subdirectories (<includeSubdirectories> = true).
Then it calls the <callback> with the operation result.
Syntax
(Synchronous get files list)
var result = fileGetListSync(<relativePath>, <searchPattern>, <includeSubdirectories>)
(Asynchronous get files list. The result is provided in the callback method.)
fileGetList(<relativePath>, <callback>, <searchPattern>, <includeSubdirectories>)
Parameters Usage
Parameter | Type | Default | Use | Annotation |
relativePath | String | - | Mandatory | Relative path of the file to access in the shared\scripting folder of the current project. |
callback | Function | - | Mandatory for asynchronous calls | Object that identifies the callback function invoked to provide the result of the operation. |
searchPattern | String | "*" | Optional | The search string to match against the names of files in path. This parameter can contain "*" (zero or multiple characters in that position) and "?" (zero or one character in that position). A search pattern equal to "*" or empty retrieves all the files. The search pattern is not case sensitive. |
includeSubdirectories | Boolean | False | Optional | Whether to look into subdirectories. |
The callback function is declared as follows:
function fileGetListCallback(<getListResult>)
{
//... Do callback stuff here ...
}
Where <getListResult> is the result object.
The search pattern follows these rules:
- When you use the asterisk wildcard character in a
<searchPattern>such as "*.txt", the number of characters in the specified extension affects the search as follows: - If the specified extension is exactly three characters long, the
fileGetList[Sync]function returns files with extensions that begin with the specified extension. For example, "*.xls" returns both "book.xls" and "book.xlsx". - In all other cases, the
fileGetList[Sync]function returns files that exactly match the specified extension. For example, "*.ai" returns "file.ai" but not "file.aif". - When you use the question mark wildcard character, the
fileGetList[Sync]function returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file*.txt" returns both files. - Because the
fileGetList[Sync]function checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "*1*.txt" may return unexpected file names. For example, using a search pattern of "*1*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT".
Result
The functions fileGetListSync and fileGetListCallback return the FileGetListResult object.
Error Handling
Errors can occur in case:
- The specified
<relativePath>: - Is missing, null, empty or white space
- Is not a string
- Is invalid (such as, path containing a root directory, wrong absolute path, path outside of the predefined folder, path or file name containing invalid characters, files or directories that have too long path). Note that invalid characters and the path length depend on the operating system.
- Does not exist
- Does not represent a directory
<searchPattern>is invalid (not a string)<includeSubdirectories>is invalid (not a boolean value)
- The callback is missing, invalid, null, or empty (for asynchronous function only).
- The related error is logged only in the Trace Viewer.
Examples of Use
How to get the files in the shared scripting predefined folder and read their contents
var result = fileGetListSync(".")
if (result.files != null)
{
for (var i = 0; i< result.files.length; i++)
{
var fileContents = fileReadSync(result.files[i])
console("--- {0}\n{1}", result.files[i], fileContents.data)
}
}
How to get and print (asynchronously) the list of files matching a given search pattern
Get and print (asynchronously) the list of files in directory "MyDir" that match the search pattern "Log*.txt"
fileGetList("MyDir", getListCallback, "Log*.txt")
function getListCallback(getListResult)
{
if (getListResult.error)
console(getListResult.error)
else
console(getListResult.files)
}
How to get the list of all the files in a directory ("MyDir") and its subdirectories
The following instructions are equivalent.
var result = fileGetListSync("MyDir", "", true)
var result = fileGetListSync("MyDir", "*", true)
var result = fileGetListSync("MyDir", null,
)