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.

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

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)

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,

)