Reading Data Back from a File

Imagine a drawing program that saves its pictures to a file. Months later the same program is updated, and the new version may store its information a little differently than the old one did. Will the new version still open the files the old version saved? The answer depends on how the data was represented in the file from the beginning. A file that is tied too closely to the exact layout a program uses today causes trouble as soon as that layout changes. Two design habits reduce the problem: storing a version number inside the file, and writing the file in a format a person can read and understand.

This article follows one file from the moment it is written to the moment a program decides whether it can be read. As you go, keep one question in mind: what does the reader need to know before it can trust the numbers in the file?

A file written by a program without a version number is fragile. The file holds a long sequence of values, and the meaning of each value depends on the program knowing exactly what position it occupies. The reader works through the values in the same order the writer produced them. If the program later changes that order, or adds a value somewhere in the middle, the reader consumes the numbers under the wrong assumptions.

The source gives a concrete case: adding a new property to curves. Once the program expects an extra value for each curve, every older file becomes unreadable, unless the user happens to remember which version of the program created that file. The data is not damaged in any physical sense. What has changed is the set of rules needed to interpret it. The same bytes or numbers that meant one thing under the old layout now mean something else under the new one.

Read the diagram as a sequence of slots. An old file fills the slots as the old program defined them. A reader that expects the new layout will pull the wrong value into the wrong slot, and nothing in the raw numbers announces the mismatch. The file has not been corrupted; the reader's rules have moved away from the writer's rules.

A well-designed data file begins with a small header that describes the file itself. In the format discussed in the source, the first line does two jobs. The first word names the program that created the file. This gives the program a quick test: when a user picks a file to open, the program can look at that first word and confirm that the file is of the correct type before it tries to read anything else.

The same first line also carries a version number, which in the source example is 1.0. The version number answers a different question from the program name. The program name asks what kind of file this is. The version number asks which rules were used to write the rest of the file. Each time the file layout changes, the number changes with it, so a higher number means a newer layout.

A reader that checks the header does not simply start parsing. It makes a sequence of decisions, and each decision uses information from the first line. The flowchart below traces those decisions from the first line of the file to the point where the program either parses the contents or reports a problem.

The important choice sits at the version check. The source states that a program meeting a version it does not understand should explain that a newer version is needed rather than guess at the contents. Guessing is exactly what the position-based reader was forced to do in the earlier example, and the version number exists to prevent it.

The version number protects a reader from wrong guesses, but a second design habit makes the file easier to work with in the first place. A human-readable format uses clear labels so that a person looking at the file can tell what each piece of data means. The label removes the guesswork, so each line carries its own explanation.

The source's example shows the idea in two places. First, a line that begins with the word 'background' is followed by three numbers, which are the red, green, and blue components of a color. A reader does not need to know the program's internal order to understand that line. Second, each curve is wrapped between the markers 'startcurve' and 'endcurve'. Inside those markers the file holds the curve's color, its symmetry property, and the xy-coordinates of each point. Because the structure is spelled out in words, a reader can follow the file from top to bottom without running a program.

Readability has practical value in three ways. Files in this format can be created or edited by hand, and the source notes that the example file was in fact written in a text editor rather than produced by the program. A readable file is easier to debug, because a mistake such as a missing marker or a misplaced number is visible on the page. And labeled formats make changes simpler: a new option can be added as a new labeled line without forcing every reader to memorize a new position.