Reading a Real File

Read a Topaz file to find its inputs, result, and failure path. Use the study planner to trace where an invalid duration stops task creation.

Complete First Application first. Keep its src/main.tpz and src/plan.tpz open. If you renamed the project, they are inside source-unavailable.

Find imported code

An import tells you which module provides a name used in this file. For example, these lines import standard library modules.

import std.bytes { Bytes }
import std.json

In the study planner, import src.plan points to src/plan.tpz. Open that file when you need to follow makeTask or summarize.

Also look for built-in calls such as print, which needs no import. To understand file access, read the calls and the package's permissions. The execution profile, which sets the available operations and execution rules, also matters. Imports alone do not list all I/O.

Find the data

This short example groups a study session's data and turns it into text.

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"
}

StudySession stores a topic, a duration, and a completion state. Read those fields first. Then follow session.finished to see which text summarize returns.

For a topic of "Read", 25 minutes, and finished = false, the result is "Read: 25 minutes left". With finished = true, it is "Read: done".

Read the function inputs and result

function summarize(session: StudySession) -> string is the function signature. It names the function and states its parameters and return type.

Here, summarize takes a StudySession and returns a string. In the study planner, makeTask instead returns Result<StudyTask, string>. The caller can receive a task in Ok or an error message in Err.

Read the signature to decide which function is relevant, then inspect that function's body. To find file or other I/O operations, check its calls and the execution profile as well.

Follow a failed input

In src/plan.tpz, find parseMinutes(minuteText)? inside makeTask. The ? unwraps an Ok value. For Err, it returns the error from makeTask immediately.

Now follow the input "later". toInt cannot turn it into an integer, so parseMinutes returns Err("minutes must be a positive integer"). The ? passes this error back to the caller before a task is created. tests/plan.tpz checks that message.

To fix that input in src/main.tpz, replace it with a positive integer string such as "25". Distinguish these returned errors from runtime faults, such as an out-of-range array access that stops execution.

Try this

Read the summarize example above. Can code receiving its returned value tell from the type whether the session is finished?

Ready to continue when

In the study planner, find the import that leads to src/plan.tpz and the function that rejects "later". Follow its error back to makeTask, then locate the test that checks it.

Use Records & Nominal Data, Functions & Generics, and Null, Option, Result & Faults for detailed rules. Syntax at a Glance helps you look up an unfamiliar form.