Reading a Real File

Outcome: open a file you did not write and locate its shape, its contracts, and where it can fail, without reading it line by line.

Prerequisite: complete First Application. Writing small programs and reading large ones are different skills, and this page is about the second one.

Reading is not writing in reverse

Reading a large file from top to bottom is rarely the fastest way to answer one question. Skilled readers skim for landmarks, build a rough map, and then read the relevant part closely. The same four kinds of landmark are useful whenever they appear.

Four passes get you oriented. Each one takes seconds.

Pass one, the imports

The first lines tell you what the file depends on before you know anything else about it.

import std.bytes { Bytes }
import std.json

Imports reveal named module dependencies. A longer import list often means the file coordinates several parts; an empty list does not prove the file has no host interaction, because prelude operations and the selected product profile still matter. Treat this pass as a quick map, not a proof.

Pass two, the shapes

Look for the nouns. A record declares a shape that values of that kind must have, and it usually tells you what the file is about faster than any comment.

record StudySession {
    topic: string,
    minutes: int,
    finished: bool
}

function summarize(session: StudySession) -> string {
    if session.finished {
        return "{session.topic}: done"
    }
    "{session.topic}: {session.minutes} minutes left"
}

Reading only the record, you already know this file deals with study sessions that have a topic, a duration, and a completion state. You learned the subject matter without reading a single line of logic.

Pass three, the signatures

Now read function signatures and skip every body. A signature is a contract, and contracts compose into a story.

In the example above, summarize takes a session and promises a string. The signature fixes its input and result shape. A Result return would also expose recoverable failure. It does not, by itself, encode every host capability: file and I/O authority also depend on the selected product profile.

This is why the signature pass is useful but bounded. Reading a stack of signatures gives you the file's data and recoverable-failure outline. Read imports and the package profile alongside them when you need to judge host authority, then descend into the one body relevant to your question.

Pass four, the failure paths

Last, find where the file admits things can go wrong. Look for Result in signatures and for the ? mark in bodies.

A function whose result type is a Result is telling you it can fail and that callers must deal with it. The ? mark in a body means the failure at that point is passed up to the caller rather than handled here. Together they draw the error path through the file without your reading any error handling in detail.

A file with no Result exposes no recoverable failure through those signatures. That does not prove that execution cannot fault or that no host operation occurs, so keep the distinction between a returned error and a runtime fault.

What you now do with a real file

Run those four passes on the source of any example in this documentation, or on your own first-application project. Imports, shapes, signatures, failure paths. You should be able to describe what the file is for in one sentence before you have read a single function body closely.

When one of the four passes leaves you stuck, the reference explains the exact form. Shapes are in Records & Nominal Data, signatures in Functions & Generics, and failure paths in Null, Option, Result & Faults.

Try this

Read the summarize function again and answer without running it. Can code that receives only the returned string learn from its type whether the session was finished?

Ready to continue when

You can open an unfamiliar file, name its dependencies, its main shapes, two of its contracts, and one place it can fail, in under a minute and without reading every line.

The reference material is organized the same way you just read. Syntax at a Glance is the fastest map of the forms themselves.