Reading and writing external files

Reading and writing to external files can trip people up, but it is actually reasonably simple. Here I deal with reading and writing to ordinary text files, but we can just as easily read and write to any filetype you like. (This doesn't mean you'll be able to make sense of data from an Xpress file for instance; just that you can blindly read and write data to and from any file format you like.)

The following script is an adaptation of something from a SuperCard example. It lives in a menu

on mouseUp
  ask file "Save text as:"
  if it is empty then exit mouseUp
  set the fileType to "ttxtTEXT"
  set cursor to watch
  open file it
  write card field "main text" to file it
  close file it
end mouseUp

Here's a line-by-line explanation of what that script means:

on mouseUp

Line 1: ask file "Save text as:"
As you probably already know, this puts up a dialog box of the "save file" variety. The message can be whatever you want, but "Save text as" is hard to misunderstand - if a little terse.

Line 2: if it is empty then exit mouseUp
The result of this dialog is stored in a variable called ‘it’. (See the next chapter for a full description of what these are.) If this is empty then the user clicked "cancel", otherwise 'it' will contain the file name the user typed, prefaced by the pathname (such as Hard Disk:Folder1:Folder2:) for the place the user chose to save the file. You could replace the 'is empty' with 'equals empty', is "", '= empty' or some other variation of those items; it all means the same thing.
'Exit mouseUp' simply makes the script stop and bail out at this point - if the 'if' question is true.

Line 3: set the fileType to "ttxtTEXT"
This ensures the new file is a plain text 'SimpleText' document, This is the default file type and creator code anyway, so it isn't strictly necessary.

Line 4: set cursor to watch
Purely to indicate that something is happening. Not necessary, but it is good manners to reassure your user that a possibly lengthy action is taking place. (Although this shouldn't take more than a few seconds at most.) The cursor will automatically switch back to 'browse' (the hand) when the script has finished and SuperCard goes into 'idle' mode. The only reason this wouldn’t happen is if you've run the line "set lockCursor to true", which stops the cursor from switching unaided.

Line 5: open file it
The variable 'it' still contains the complete pathname, so we can simply use this. You have to open the file before you can do anything like reading or writing to it.
A good line to put straight after this one when still in development is "put the result". Many SuperCard operations will, if they have problems operating, put some kind of error message into another variable called 'the result'. If you 'put' the result (without specifying a specific container such as a text field for it to be put into) it will be shown in the message box. You can then see what sort of problem you were having. (If the path wasn’t correct or you weren’t able to make a file there you probably would have seen "file not found" in the result of your original script.) This is something you'd either modify or remove before releasing the project into the tender hands of the general user.

Line 6: write card field "main text" to file it
You can refer to objects such as field directly rather than having to place their name in a variable and then using that. This approach is often known as 'hard-wiring' a script. It doesn't allow you to juggle which field is exported based on some criteria, but it does make things simpler to understand.

Line 7: close file it
Important! Remember to close a file if you open it. It is, in a sense, out of bounds for most other applications while still 'open'.

end mouseUp

To read a file and place its contents into a field you'll have to use a slightly different script, such as:

on mouseUp
  open file "HD:Stuff:My Material.txt"
  read from file "HD:Stuff:My Material.txt" until eof
  put it into background field "main text"
  close file "HD:Stuff:My Material.txt"
end mouseUp

Here's a line-by-line explanation of what that script means:

on mouseUp

Line 1: open file "HD:Stuff:My Material.txt"
This opens a predetermined file living in a predetermined place on your hard drive.

Line 2: read from file "HD:Stuff:My Material.txt" until eof
Once open, you can read from the file. The "until eof" simply means keep reading until 'end of file'. The 'eof' is a SuperTalk keyword, look it up in the SLG for more info.

Line 3: put it into card field "main text"
The 'it' variable is automatically used to hold the read data. So you can just 'put it' into the destination field.

Line 4: close file "HD:Stuff:My Material.txt"
As mentioned earlier.

end mouseUp

There is one important rule when dissecting other people's scripts to find out how they work: Try to simplify things. Sometimes it can't be done, but even when you come to this conclusion you'll have soaked up a little more experience.

If you open a file using a particular pathname (such as "HD:Stuff:My Material.txt") you'll have to keep referring to it as that whole pathname thing, not just the filename on its own. When you refer to a document by its filename only, SuperCard (or your standalone app made from SuperCard) assumes it is in the same place as itself. If you 'open' a new file using just the filename rather than a full pathname you'll actually create one in the same place as SuperCard (or your standalone application).

If you open an existing file and write data TO it, you'll replace the existing contents. If you write AFTER the file you'll add your data to the end. Just like putting data INTO or AFTER a card field.

Of course, the script we just looked at was hard-wired to read one specific file in one particular place. If you want to allow someone to open any SimpleText file rather than just the one you supply, you can use "answer file" to find out which one they want:

on itemSelect
  answer file "What text file do you want?" of type "TEXT"
  if it is empty then exit itemSelect
  put it into theFileName
  read from file theFileName until eof
  put it into card field "main text"
  close file theFileName
end itemSelect

Here's a line-by-line explanation of what that script means:

on mouseUp

Line 1: answer file "Open what file?" of type "TEXT"
This shows a standard 'open file' dialog box with your text shown.
The optional of type "text" filters out any files which aren't that type, ensuring the user can't select a file which can't be read properly. Note that this can cause your project to filter out text files from Mac OS X's TextEdit and other applications which don't include filetype codes in the documents they create.

Line 1: if it is empty then exit mouseUp
If the user selected 'Cancel' then 'it' will be empty and we exit the whole 'mouseUp' handler, otherwise 'it' will hold the complete pathname for the selected document.

Line 1: put it into theFileName
The step after this one will reuse the 'it' variable, putting the data read from the file into there, so we have to store the pathname data before it gets lost. We simply put 'it' into a custom variable of our own. Here it is called 'theFileName', but it can be called almost anything you like. (See below for more details)

Line 1: read from file theFileName until eof
We read the data from the file until SuperCard reaches the end of the file (eof being the recognised term for that). We stored the file's pathname in the 'theFileName' variable, so the route to the file is now referenced as 'theFileName' in our script.

Line 1: put it into background field "field 3"
The data read from the file is automatically placed in the 'it' variable, so we simply put 'it' into the field..

Line 1: close file theFileName
It is important to remember to close any file we open. The 'theFileName' variable still holds the full pathname to the file, so we use that to refer to it again.

end mouseUp

Here the 'it' variable is used first to hold the pathname to the chosen file, and then to hold the data read from the file. You can see that it isn't a good idea to rely on anything held in the 'it' variable to stick around for very long. Which leads us to the next chapter and variables...