Чтение реального файла

Результат: вы откроете файл, который писали не вы, и найдёте его форму, его контракты и места, где он может завершиться ошибкой, не читая его строка за строкой.

Что нужно знать: завершите Первое приложение. Писать небольшие программы и читать большие — разные навыки, и эта страница про второй.

Чтение — это не письмо наоборот

Когда в большом файле нужно ответить на один вопрос, чтение сверху вниз редко оказывается самым быстрым способом. Опытные читатели выхватывают взглядом ориентиры, строят приблизительную карту и лишь затем внимательно читают нужную часть. Следующие четыре вида ориентиров полезны всякий раз, когда встречаются.

Сориентироваться помогают четыре прохода. Каждый занимает секунды.

Проход первый, импорты

Первые строки сообщают, от чего зависит файл, ещё до того, как вы узнали о нём что-либо другое.

import std.bytes { Bytes }
import std.json

Импорты показывают именованные зависимости от модулей. Длинный список часто означает, что файл координирует несколько частей, но отсутствие импортов не доказывает отсутствие взаимодействия с хостом: важны также операции прелюдии и выбранный профиль продукта. Это быстрая карта, а не доказательство.

Проход второй, формы

Ищите существительные. Запись объявляет форму, которую обязаны иметь значения этого вида, и обычно она говорит, о чём файл, быстрее любого комментария.

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

Прочитав одну лишь запись, вы уже знаете, что файл имеет дело с учебными занятиями, у которых есть тема, длительность и признак завершения. Предметную область вы узнали, не прочитав ни строки логики.

Проход третий, сигнатуры

Теперь читайте сигнатуры функций и пропускайте все тела. Сигнатура — это контракт, а контракты складываются в связный рассказ.

В примере выше summarize принимает занятие и обещает строку. Сигнатура фиксирует форму входа и результата. Возвращаемый Result также показал бы восстанавливаемую ошибку. Но не все возможности хоста записаны в одной сигнатуре: доступ к файлам и вводу-выводу зависит ещё и от выбранного профиля продукта.

Поэтому проход по сигнатурам полезен, но имеет границы. Несколько сигнатур дают очертания данных и восстанавливаемых ошибок. Чтобы судить о полномочиях хоста, читайте вместе с ними импорты и профиль пакета, а затем переходите к тому телу, которое относится к вашему вопросу.

Проход четвёртый, пути ошибок

Наконец, найдите места, где файл признаёт, что дело может пойти не так. Ищите Result в сигнатурах и знак ? в телах.

Функция с типом результата Result сообщает, что может завершиться ошибкой и что вызывающий код обязан с этим разобраться. Знак ? в теле означает, что ошибка в этом месте передаётся вызывающему коду, а не обрабатывается здесь. Вместе они прочерчивают путь ошибок через файл, и вам не приходится подробно разбирать обработку ошибок.

Если Result нигде не встречается, эти сигнатуры не выносят наружу восстанавливаемую ошибку. Это не доказывает, что выполнение не может аварийно остановиться или что файл не выполняет операций хоста. Различайте возвращаемую ошибку и ошибку времени выполнения.

Что теперь делать с реальным файлом

Проведите эти четыре прохода по исходнику любого примера в документации или по собственному проекту first-application. Импорты, формы, сигнатуры, пути ошибок. Вы должны суметь описать назначение файла одним предложением ещё до того, как внимательно прочитаете хоть одно тело функции.

Если один из четырёх проходов заводит в тупик, точную форму объясняет справочник. Формы описаны в разделе Записи и номинальные данные, сигнатуры — в разделе Функции и обобщения, а пути ошибок — в разделе Null, Option, Result и ошибки.

Попробуйте

Прочитайте функцию summarize ещё раз и ответьте, не запуская её. Может ли код, получивший только возвращённую строку, узнать по её типу, было ли занятие завершено?

Готовы двигаться дальше, если

Вы можете открыть незнакомый файл и меньше чем за минуту, не читая каждую строку, назвать его зависимости, его основные формы, два его контракта и одно место, где он может завершиться ошибкой.

Справочные материалы устроены так же, как вы только что читали. Раздел Краткий обзор синтаксиса — самая быстрая карта самих форм.