Inform 7 Home Page / Documentation

§23.15. Exchanging files with other programs

Provided we declare the files in the right way, it is easy for one project to read a file created by another project.

But if we want more rapid communication, between two projects which are each playing at the same time, we need to be more careful. What if project A tries to read the file at the same moment that project B is writing it?

To avoid this, we have a concept of files being "ready". A file is ready if it exists, and is completely written, and not in use elsewhere. We have already seen:

if the file of Invariants exists...

But now we want a stronger condition:

if ready to read (external file):

This condition is true if the file exists and is marked as being ready to read; that is, it is not in a state where another program is currently writing it. Example:

if ready to read the file of Invariants, ...

A file cannot be ready to read if it does not exist, so this is a stronger condition. If A and B are attempting communication in real time, both running at once, then Project A should check that an external file owned by B is ready before it tries to read it. Files can also be marked as ready or not ready, in effect claiming them, thus:

mark (external file) as ready to read

This phrase marks that we have finished writing to the given file, so that any external program is welcome to read it now. Example:

mark the file of Invariants as ready to read;

mark (external file) as not ready to read

This phrase marks that we are about to start writing to the given file, so that any external program should wait until we're finished if it wants to read the file. Example:

mark the file of Invariants as not ready to read;

Possibilities really begin to open up when project A is our story file, but B is not another story file at all: it is some external program such as a Web service, say. (Of course this is harder to set up, since the player needs to have both A and B running at the same time, but for stories running on an Internet server this can all be made seamless.)

When Inform begins writing a table, or text, to a file, it initially marks the file as not ready: only when the table or text is completely written and the file about to close is the file marked as ready.

In order to write non-story-file programs as B, communicating with story files as A, we need to know the file format used by Inform. An Inform file is currently a Unix text file (with 10 as the line division character), encoded as ASCII Latin-1. (We would like to use Unicode at some point in the future, but the Glk and Glulx layers are still not fully converted to Unicode.) It opens with a single header line in the form:

* //IFID// leafname

The opening character is an asterisk if the file is currently ready, a hyphen if the file is currently not ready. The IFID between the slashes is the IFID number of the project which last wrote to the file. (Marking "ready" or "not ready" does not count as a write for this purpose.) If an external program wrote the file, it should call itself something which will not clash with any story file's IFID. The leafname is the filename text used inside the story file where the file was declared. For instance:

* //4122DDA8-A153-46BC-8F57-42220F9D8795// ice

arrow-up.png Start of Chapter 23: Figures, Sounds and Files
arrow-left.png Back to §23.14. Writing, reading and appending text to files
arrow-right.png Onward to Chapter 24: Testing and Debugging: §24.1. Checking against the Index

***ExampleFlathead News Network
Using external files, together with a simple Unix script running in the background, to provide live news headlines inside a story file.