How-To Guide ⏱ ~25 minutes

Working with Files and Folders

HyperXTalk gives you a straightforward set of commands for working with the file system — opening file pickers, reading and writing files, checking whether something exists, and listing the contents of a folder. This guide walks through all of them with practical examples.

What you'll cover
  • Checking whether a file or folder exists
  • Showing open and save file dialogs
  • Reading the contents of a file
  • Writing data to a file
  • The URL shortcut for simple file access
  • Listing files and subfolders in a directory
  • Creating folders

Checking Whether a File or Folder Exists

Before working with a file or folder, it's good practice to check it exists using the there is a operator:

-- Check a file if there is a file "/Users/emily/Documents/notes.txt" then answer "File exists!" end if -- Check a folder if there is not a folder "/Users/emily/Documents/MyApp" then create folder "/Users/emily/Documents/MyApp" end if

The inverse operator there is no works the same way in reverse — use whichever reads more naturally for your situation.

File Dialogs

Open dialog — answer file

Use answer file to show a standard Open dialog. The chosen file path is placed in it. If the user cancels, it is empty and the result returns "Cancel":

answer file "Select a file to open:" if the result is not "Cancel" then local tFilePath put it into tFilePath -- use tFilePath... end if

To allow the user to select multiple files at once, use answer files (plural). The result is a return-delimited list of paths:

answer files "Select files to process:" if the result is not "Cancel" then local tFiles, tFile put it into tFiles repeat for each line tFile in tFiles -- process each tFile... end repeat end if

Save dialog — ask file

Use ask file to show a standard Save dialog. The user enters a filename and chooses a location — the resulting path is placed in it:

ask file "Save as:" with "Untitled.txt" if the result is not "cancel" then local tSavePath put it into tSavePath -- write to tSavePath... end if
💡 Neither answer file nor ask file actually open or create the file — they only give you the path. You still need to open and read/write the file yourself.

Reading a File

Reading a file takes three steps: open it, read from it, then close it. The data is placed in the special it variable after reading:

stack script
function readFile pFilePath local tContents if there is not a file pFilePath then throw "readFile error: file not found —" && pFilePath end if open file pFilePath for text read read from file pFilePath until EOF put it into tContents close file pFilePath return tContents end readFile

Use it like this:

local tText put readFile("/Users/emily/Documents/notes.txt") into tText put tText into field "Editor"
⚠️ Always close the file after reading. Open files consume system resources and some platforms limit how many files can be open simultaneously.

Writing a File

Writing follows the same open / write / close pattern. Use for text write to replace the entire file contents, or for text append to add to the end:

stack script
-- Write (replaces existing contents) on writeFile pFilePath, pContents open file pFilePath for text write write pContents to file pFilePath close file pFilePath end writeFile -- Append (adds to end of file) on appendFile pFilePath, pContents open file pFilePath for text append write pContents to file pFilePath close file pFilePath end appendFile
⚠️ Opening a file for write immediately erases its contents — even if you don't write anything. Always make sure you have the right path before opening for write.

The URL Shortcut

For simple reads and writes, HyperXTalk offers a much shorter syntax using the URL keyword — no open or close required:

local tPath, tContents put "/Users/emily/Documents/notes.txt" into tPath -- Read put URL ("file:" & tPath) into tContents -- Write (replaces contents) put "Hello, world!" into URL ("file:" & tPath)
🟢 The URL shortcut is perfect for quick reads and writes. Use open file / read from file / write to file when you need more control — reading in chunks, appending, or reading from a specific position.

Listing Files and Folders

Use the files() and folders() functions to list the contents of a directory. Both return a return-delimited list of names. Pass a folder path as the argument, or omit it to use the current defaultFolder:

local tFolder, tFiles, tFolders put specialFolderPath("documents") into tFolder -- List files put files(tFolder) into tFiles sort lines of tFiles international -- List subfolders (always filter out "..") put folders(tFolder) into tFolders filter lines of tFolders without ".." sort lines of tFolders international
⚠️ The folders() function always includes a .. entry representing the parent folder. Always filter it out with filter lines of tFolders without ".." to avoid infinite loops and unexpected behaviour.

To filter by file extension — for example, only show HyperXTalk stacks:

local tFiles put files(specialFolderPath("documents")) into tFiles filter lines of tFiles with "*.hyperxtalk"

Creating Folders

Create a folder with the create folder command. It's good practice to check first that it doesn't already exist:

local tFolder put specialFolderPath("documents") & "/MyApp/exports" into tFolder if there is not a folder tFolder then create folder tFolder end if
💡 create folder only creates one level at a time. If /MyApp doesn't exist yet, creating /MyApp/exports will fail. Create parent folders first if needed.
🟢 Use specialFolderPath() to get the right path for common locations on each platform — "documents", "desktop", "support", "preferences", "home", and more. This keeps your code cross-platform without hardcoding paths.