Office of Digital Humanities
By the end of this reading you should understand the following:
specialFolderPath() function to access files in commonly-used locations.the defaultFolder property to determine the default file location.the defaultFolder to change the default file location.The mid-1990s was 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, livecode.com, etc. These URLs often
include file path and file name information in addition to the basic web site
address. For example, an address like livecode.byu.edu/dight310/schedule.html
tells us that the resource we want is on the web server livecode.byu.edu,
in a folder named "dight310" 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, which 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 many 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.
LiveCode 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. LiveCode supports the following URL schemes:
http: Hyper-Text Transfer Protocol—a page on a web server
https: Hyper-Text Transfer Protocol Secure—same as http, but for accessing a page on a secure web server
file: a text file on the local disk (not on a server)
binfile: a binary data file on the local disk. Use the binfile scheme to read in media files, such as an audio or image files, or files saved in text encodings that are different from your computer's native encoding, such as UTF-8.
ftp: File Transfer Protocol—a directory or file on an FTP server
resfile: on Mac OS and OS X systems, the resource fork of a file; rarely used nowadays
URL keyword—LiveCode’s key to accessing external resourcesIn 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 earlier lesson for a review of how to refer to 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 LiveCode 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:/Users/Documents/Test.txt"
If you put data into a URL container that doesn't exist, LiveCode 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. One technique to ensure you don't try to write to a non-existent folder is to check to see if it exists first:
# in this example the folder would be in the defaultFolder
if there is a folder "myFolder" then
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 writable, 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 LiveCode 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 platform-native ASCII text. The binfile protocol is for accessing files containing binary data—things like Unicode text, images 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 plain, platform-native ASCII text files, and binfile for everything else.
Absolute paths have several inherent limitations. Most notably, if you create a program on one machine, the absolute paths will most likely be different on another one (due to different folder names, different user logins, different platforms, and so forth). But LiveCode provides tools for adapting absolute file paths to the current host system. Most common operating systems have standard folders for storing certain types of information. For example, preference files tend to be stored in a specific place; each user has a "home" folder where they can save their files; and there are typical places for storing temporary files. As a cross-platform development tool, LiveCode gives you an easy way to find out where these folders are located on the current host operating system, a function called specialFolderPath().
How does this function work? Let's say, for instance, that you want to save a file to the user's Desktop. Simply use the specialFolderPath() function with the argument "desktop":
put specialFolderPath("desktop") into tFolderPath
put tFolderPath & "/mydocument.txt" into tFilePath
put field "importantStuff" into URL ("file:" & tFilePath)
The specialFolderPath() function returns a file path to the folder appropriate for the current operating system. For example, on Mac OS X specialFolderPath("desktop") might return something like "/Users/myname/Desktop". On Windows it might be something like "C:/Users/myname/Desktop".
There are several common folder identifiers you can plug in to this function, including "home", "preferences", "temporary", and "fonts". Each identifier returns the platform-specific path to the given folder. See the LiveCode dictionary entry for specialFolderPath for a complete list.
One particularly useful folder identifier is "resources". When you call specialFolderPath("resources") you get the file path to the folder your stack is saved in. That makes it simple to build file paths to media assets that are stored in the same folder as your stack.
A note about special folder paths on mobile platforms. The specialFolderPath() function works on iOS and Android, but because file system access is much different on mobile versus desktop platforms, the available folder identifiers for mobile platforms are different, too. Perhaps the most useful folder identifiers for mobile devices are engine, documents, and cache. The resources identifier is also useful in the mobile environment; it is a synonym for engine.
specialFolderPath("engine") – returns the file path to the folder where your app is located in the mobile device's file system. This is most often where you would store media file resources like image and audio files for access by your app.specialFolderPath("resources") – same as "engine".specialFolderPath("documents") – returns the file path to the folder where your app is permitted to save permanent documents.
specialFolderPath("cache") – returns the file path to the folder where your app can save temporary files.What if you want to access files that are in a folder other than one of the special folders accessible through specialFolderPath()? LiveCode provides a way for you to specify where files should be created by default and where commands should look for files when no file path is specified. You can do this with the defaultFolder property. The defaultFolder is a property that applies to the entire LiveCode environment. Such properties are called global properties. If you examine the defaultFolder property immediately after launching LiveCode:
put the defaultFolder into message boxYou will get a result something like this (for Mac/Linux):
/Applications/Or this (for Windows):
C:/Program Files/RunRev/LiveCode
You can change the defaultFolder by setting it to the desired
folder:
set the defaultFolder to "/MyHD/MyProject/textfiles"
Once the defaultFolder is set, any reference to a relative file path will begin at the specified default folder to derive the full file path. Setting the defaultFolder persists only until LiveCode 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 how to set the defaultFolder to
the folder where the currently open stack is saved:
set the defaultFolder to specialFolderPath("resources")
In versions of LiveCode before v. 6.7, the specialFolderPath("resources") option did not exist, so in older versions you would have to do it like this:
get the effective fileName of this stack
set the itemDelimiter to "/"
delete last item of it
set the defaultFolder to it