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

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

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

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

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

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

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

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

import std.bytes { Bytes }
import std.json

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

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

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

record УчебноеЗанятие {
    тема: string,
    минуты: int,
    завершено: bool
}

function подвестиИтог(занятие: УчебноеЗанятие) -> string {
    if занятие.завершено {
        return "{занятие.тема}: done"
    }
    "{занятие.тема}: {занятие.минуты} minutes left"
}

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

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

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

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

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

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

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

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

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

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

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

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

Попробуйте

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

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

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

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