BRIGHAM YOUNG UNIVERSITY

  Humanities Technology and Research Support Center

CHum 310
Using External Files

Objectives

By the end of this reading you should understand the following:

1. The two approaches to accessing external files on the local file system.
2. Know how to work with files using the open file–close file model.
3. Understand that there are different "modes" of the open file command, depending on what you plan to do with the file after you open it.
4. Recognize that good programming practice demands that you always close a previously opened file when you are finished accessing it.
5. Know who to work with files using the resource-oriented (URL) model.
6. Understand how file permissions can limit what you can do with files, regardless of the access model you use.

Often you may want to use data stored in external files in your Revolution program. Revolution and the Transcript scripting language have a rich set of tools that make reading, writing and modifying external files simple. This lesson will look at the basic tools and techniques for working with external files.

Two Models for working with external files

There are two different approaches for reading and writing external files. One model is oriented toward local, disk-based files systems. The other is oriented toward a world connected by the internet.

Model One: File-oriented—more cumbersome, but also more flexible

  go to stack URL "http://chum310.byu.edu/Lectures/ExtFilesLect.rev"

Do the activity "Exploring the open and close commands".

Under this model, before you do anything with a file it must be accessed, or formally "opened". The open file and close file commands perform the "housekeeping" functions that are necessary to adhere to the rules of the computer's file system, freeing the developer from that task.

By default the open file command looks for the file or creates the file (if it doesn’t already exist) in the same folder as the Revolution application. If another location is desired, the entire pathname must be specified. Revolution uses Unix file path conventions, so the slash (/) character is used to delimit levels in the file path. Users of the Classic Mac OS therefore must get used to using a slash character instead of a colon to delimit levels, while Windows users must get used to using a slash rather than a backslash (\).

open file "myfile.txt"
close file "myfile.txt"
    -- will open or create a file in the Revolution application folder by default

Use this format on Unix and Macintosh systems. Note the / at the beginning of the file path:
open file "/MyHD/Documents/MyProject/myfile.txt"
close file "/MyHD/Documents/MyProject/myfile.txt"

On Windows systems you specify the Drive letter:
open file "C:/Documents/MyProject/myfile.txt"
close file "C:/Documents/MyProject/myfile.txt"

Beware of the common errors when using open file and close file:

• Giving an incomplete or incorrect path name;
• Typing the file name differently in the open and close commands;
• Trying to open an already opened file;
• Trying to close an already closed file;
• Forgetting the key word file.

Variants of the open file command

Aside from the basic forms, there are several variants of this command that create specific conditions when the file is opened:

open file for update - (Default form) opened file will be available for both reading and writing.

open file for read - Opened file will be available for read only. You must use this form for opening files from read-only media (like CD-ROMs); if you try to use any other form the subsequent read access will fail.

open file for write - Next write to file command will completely replace the file’s contents.

open file for append - Next write to file command will add its data to the end of the file without replacing current contents.

Reading the contents of files

Once a file is open, you often will want to get its contents so you can use it in your program in some way. Use the read from file command for this. Here is a common usage of this command:

read from file filename until end

Where filename is a properly-formed, full path name of the file you want to ready from. Remember, if you don't use a full path designation Revolution will expect the file to be in the defaultFolder. The following sequence will read all of the data in myFile.txt and put it into the it variable:

open file "/My HD/MyFolder/myFile.txt" for update
read from file "/My HD/MyFolder/myFile.txt" until end
close file "/My HD/MyFolder/myFile.txt"

Variants of the read from file command:

read from file ... until end|empty|EOF -- these are synonyms. All three will read until reaching the end of the file.

read from file ... until string -- where string is any text string. Will read until encountering the string in the file.

read from file ... at startPoint for amount -- where startPoint and amount are positive integers. Will read starting at startPoint for amount characters.

read from file ... for amount words|items|lines -- where amount is a positive integer. Reads the specified number of chunks.

Common errors

• No until or for parameter provided.
• Filename is different from opened file.
• File not previously opened.
• Wrong format of open file command. For example, the following forms will cause an error when followed by a read command:

  open file "myFile.txt" for write

  open file "myFile.txt" for append

Writing data to files

The other common operation you will want to do with files is to write data to them. For these operations there is the write to file command. Here is a typical usage of this command:

write "Hello World!" to file filename

Where filename is a properly-formed, full path name of the file you want to ready from. Remember, if you don't use a full path designation Revolution will expect the file to be in the defaultFolder. The following sequence will overwrite the first five characters of myFile.txt:

open file "/MyHD/MyFolder/myFile.txt"
write "Hello" to file "/MyHD/MyFolder/myFile.txt"
close file "/MyHD/MyFolder/myFile.txt"

The write command must be preceded by either the open file for update, open file for write, or open file for append form of the open file command. Preceeding a write command with the open file for read form, for example, will cause the write command to fail, and the result function will return "File is not open for write."

By default, writing starts where the last read or write command left off, assuming the file was not closed since the previous read or write.

Variants of the write to file command

write...to file...at start -- where start is a positive or negative integer. For a positive number the write begins start characters after the beginning of the file; for a negative number the write begins start characters before the end of the file.

If no start is specified, writing begins at the place the last read or write operation left off, or at the first character if this is the first read or write since the file was opened.

write...to file...at EOF|end -- Starts writing after the last char in the file.

Common errors

• Overwriting an existing file with new file of the same name.
• Using a filename that is different from opened file.
• Trying to write to a file not previously opened.
  
• Using the wrong format of open file command

  -- All of these can be followed by a write to file command:
open file "myFile.txt"
open file "myFile.txt" for update
open file "myFile.txt" for write
open file "myFile.txt" for append

  -- This form will cause an error when followed by wrte to file:
open file "myFile.txt" for read

Model two: Resource-oriented—simple and far-reaching

The mid-1990s were a watershed period for personal computing. During this time the World Wide Web revolution started a paradigm shift in the way people worked with their computers. No longer were users limited to accessing only data on their local hard drives. Now, through the medium of a web browser they could access information on a huge, interconnected "web" of computers around the world. The internet became a huge presence almost overnight.

The inventors of the Web needed a simple way to reliably retrieve different types of data on the literally millions of computers on the internet. They came up with the concept of the Uniform Resource Locator, or URL. This is most familiar to users of the Web as the "web site address" they enter into their browser's address field to go to a new web site—familiar addresses like www.ibm.com, byu.edu, www.nasa.gov, www.runrev.com, etc. These URLs often include file path and file name information in addition to the basic web site address. For example, the address revolution.byu.edu/chum310/schedule.html tells us that the resource we want is on the web server revolution.byu.edu, in a folder named "chum310" and in a file named "schedule.html".

What many Web users don't realize is that URLs can locate much more than "pages" on the internet. There are a number of URL schemes that specify the method or protocol for retrieving the resource you are trying to get. You see this in the http:// portion of the URL that web browsers automatically provide if you do not type it before the address. HTTP, or Hypertext Transfer Protocol, is far and away the most commonly-used scheme on the internet. But you've probably noticed others, like https, Hypertext Transfer Protocol Secure; mailto, Email address; or ftp, File Transfer Protocol. There is even a scheme, called file, for accessing files on the local file system.

Another thing most Web users don't realize is that any computer application, not just web browsers, can be written to access internet resources. Some common examples include email applications, like Microsoft's Outlook and Apple's Mac OS X Mail; iTunes, which connects directly to Apple's online music store; and the many applications that include a "Check for Updates" feature.

Revolution was written to allow simple access to internet resources using URL-style addresses and schemes. What this means to you as a developer is that you can easily access virtually any public data resource on any web server anywhere in the world. Revolution supports the following URL schemes:

http: Hyper-Text Transfer Protocol—a page from a web server
ftp: File Transfer Protocol—a directory or file on an FTP server
file: a text file on the local disk (not on a server)
binfile: a binary data file (such as an audio or image file)
resfile: on Mac OS and OS X systems, the resource fork of a file

In the context of the present discussion about working with local files, this means that you can read a file on your computer's hard drive in a single command by using the URL keyword:

    put URL "file:myfile.txt" into field "myfield"

As you would anticipate from past discussions, this will place the contents of the file "myfile.txt", located in the current defaultFolder into field "myfield". You could access any file on your hard drive, or on any mounted volume, simply by supplying the full file path to that file. (See the previous lesson on accessing external files for a review of file path formats.)

You are not limited only to retrieving entire files. A URL can be considered a full-fledged Revolution container, just like a field or variable. That means you can access chunks of data in a file using lines, characters, words, items, etc.

    put line 1 of URL "file:myfile.txt" into field "myfield"
    put word 6 to 10 of URL "file:myfile.txt" into myVar
    get item 5 of URL "file:/Hard Drive/My Folder/myfile.txt" -- Mac format filepath
    get item 5 of URL "file:C:/Documents and Settings/localuser/My Documents/myfile.txt"  -- Windows format filepath

Nor are you limited only to reading from URL resource files. You can write data to any URL container in the same way to put data into a field or variable:

    put field "myfield" into URL "file:myfile.txt"
    put return & line 1 of field "userName" after URL "file:userList.txt"
    put it into item 5 of URL "file"myfile.txt"
    put "Test" into word 3 of URL "file:/Hard Drive/Applications/Test"

If you put data into a URL container that doesn't exist, Revolution will create the file, then write to it. However, if you try to put data into a URL container in a folder that doesn't exist, the command will fail. On technique to ensure you don't try to write to a non-existent folder is to check to see if it exists first:

    if there is a folder "myFolder" then # in this example the folder would be in the defaultFolder
      put field "myfield" into URL "file:myFolder/myfile.txt"
    end if

Of course, the ability to put data into a URL assumes that the file system will allow you to do so. For security reasons, many areas of a file system may only be writable by certain users with high levels of access to the hard drive. Additionally, some disks, such as CD-ROMs or DVD-ROMs, are not writable (ROM stands for "Read-only Memory") by nature. If you try write to a URL that is not writeable, the command will fail silently (with no warning message.) To check to see whether a put into URL command was successful, you should check the result function immediately after issuing the command, like this:

    put field "myfield" into URL "file:/System/myfile.txt" # Mere mortals can't write to the Mac System folder!
    put the result into tResult
    if tResult is not empty then
      answer "Your operation failed with this error: " & tResult
    end if

So far we have only discussed the file protocol for URLs. There are several others that Revolution supports. Most of these we will cover in a later discussion. But let's look briefly at the binfile protocol. The binfile protocol is also used to access files on the local file system. The main difference between file and binfile is that the file protocol is intended for files containing ASCII text. The binfile protocol is for accessing files containing binary data—things like image or audio files, for example. When you use the file protocol to retrieve the contents of a file, it modifies the line ending characters to match the current operating system. If you don't know what this means, don't worry—we'll cover this in a future topic. For now it's sufficient to understand that you should use file for text files, and binfile for everything else.

On file location and the default folder

Revolution provides a way for you to specify where files should be created by default and where the open and close commands should look for files when no file path is specified. This makes it faster and easier to use these commands when all of your files are to be in one location consistently. The defaultFolder property is the key to this. If you examine the defaultFolder property immediately after launching Revolution:

put the defaultFolder into message box

You will get a result something like this:

/MyHD/Applications/Revolution

You can change the defaultFolder by setting it to the desired folder:

set the defaultFolder to "/MyHD/MyProject/textfiles"

Once this is done, the open, close, read and write commands will all look to the specified folder to execute their operations. This state will continue only until Revolution is shut down, so if you want this folder to be used every time you open your stack, you should probably set the defaultFolder in an openStack or openCard handler.

Here is a useful sequence of commands that will set the defaultFolder to the folder where the currently open stack is:

get the fileName of this stack
set the itemDelimiter to "/"
delete last item of it
set the defaultFolder to it

Ways of choosing files

Several commands are provided, which can be used in conjunction with the get/put URL method, or with open, read, write, and close commands, that make it easy to choose a location for the file. The commands are intended to present familiar open and save-style dialog boxes, consistent with the operating system you are using.

answer file syntax: answer file prompt where prompt is a text prompt that will appear in the dialog. The answer file command brings up a standard file selection dialog, such as you see when choosing Open... from the File menu in most applications. When the user select the file, its full path name is returned to the special variable it. Keep in mind that answer file does not actually open the file, but only returns the name and path of the selected file. The actual opening and reading have to be scripted.

answer folder syntax: answer folder [prompt] where prompt is an optional text prompt that will appear in the dialog. The answer folder command brings up a standard Open dialog to let the user select a folder. The full pathname of the selected folder is returned in the it variable.This command can be used to let the user choose where a file is to be saved, or where to look for an existing file.

ask file syntax: ask file prompt [with defaultFileName] where prompt is a text prompt that will appear in the dialog. If you specify a defaultFileName, that string will appear in the entry field for the file name, and the user can choose either to accept it or change it. The ask file command brings up a standard file dialog, such as you see when choosing Save... from the File menu in most applications. It allows the user to type a file name and specify a location to save it,then puts the result into the special variable it. Remember that ask file does not actually create or write to a file, only returns a pathname and the name the user typed. The developer can use this information to actually write the data to the file in the location returned by this command.

Looking at the file system in Revolution

There are two very useful functions in Revolution that allow you to examine the contents of a folder in the computer's file system--the files and the folders.

The files function returns a list of files in the defaultFolder. By using the detailed files form you can also get detailed information about the file, such as its modification date, size, and access permissions.

put the files into fld "myfld"

The folders function returns a list of folders in the defaultFolder. By using the detailed folders form you can also get detailed information about the folder, such as its creation date and access permissions.

put the folders into fld "myfld"

The Text Editor Exercise