Настройки и документация

Повторите пути, аргументы и команды.

Образ и опорная карта

Адрес для письма можно назвать в самом письме, хранить в записной книжке или взять адрес по умолчанию. Явно названный адрес должен побеждать. Карта: путь из команды → если его нет, путь из окружения → если и его нет, местный путь по умолчанию. Окружение — настройки, которые родительский процесс передаёт программе при запуске. Образ не делает относительный путь абсолютным: tasks.json зависит от текущей папки.

Option<PathBuf> означает, что путь может присутствовать или отсутствовать. if let Some(path) берёт путь только при наличии. Первый найденный путь возвращается; дальнейшие ветви не выполняются. PathBuf::from создаёт значение пути, display() показывает его человеку. /// — комментарий документации перед функцией: Cargo включает его в страницы, которые строит cargo doc. Этот первый пример подставляет значения прямо в вызовы для воспроизводимого вывода; в настоящем запуске аргумент получают из args, а окружение — из std::env::var_os. При отсутствии переменной var_os возвращает None.

Запустите и разберите

Создайте новый Cargo проект без зависимостей. Скопируйте первый Rust блок в src/main.rs; cargo run покажет выбор без настройки и с настройкой окружения. Затем выполните cargo doc --no-deps: команда создаст HTML-документацию проекта в target/doc, не включая страницы зависимостей. На Windows можно открыть её в браузере из проводника; на macOS/Linux — из файлового менеджера. README — обычный файл README.md в корне проекта, где новичок должен найти требования, команды запуска, путь файла и действия при ошибке.

use std::path::PathBuf;

/// Выбрать путь: команда, окружение, местный вариант по умолчанию.
pub fn choose_path(command: Option<PathBuf>, environment: Option<PathBuf>) -> PathBuf {
    if let Some(path) = command {
        return path;
    }
    if let Some(path) = environment {
        return path;
    }
    PathBuf::from("дела.json")
}

fn main() {
    println!("По умолчанию: {}", choose_path(None, None).display());
    println!(
        "Из окружения: {}",
        choose_path(None, Some(PathBuf::from("семья.json"))).display()
    );
}

По умолчанию: дела.json
Из окружения: семья.json

Вопросы для воспроизведения

1. Какой путь победит, если заданы все три варианта?
2. От чего зависит относительный путь tasks.json?
3. Для кого нужны README и комментарий ///?

Задание

Обязательное. Добавьте третий вызов choose_path, где заданы и путь из команды, и путь из окружения; выведите выбранный путь. Затем создайте README.md с тремя разделами: установка Rust, запуск через cargo run, правило приоритета путей и предупреждение о текущей папке. Передайте инструкцию человеку, который не видел урок, или пройдите её сами из новой пустой папки.

Ответы

use std::path::PathBuf;

/// Выбрать путь: команда, окружение, местный вариант по умолчанию.
pub fn choose_path(command: Option<PathBuf>, environment: Option<PathBuf>) -> PathBuf {
    if let Some(path) = command {
        return path;
    }
    if let Some(path) = environment {
        return path;
    }
    PathBuf::from("дела.json")
}

fn main() {
    println!("По умолчанию: {}", choose_path(None, None).display());
    println!(
        "Из окружения: {}",
        choose_path(None, Some(PathBuf::from("семья.json"))).display()
    );
    println!(
        "Из команды: {}",
        choose_path(
            Some(PathBuf::from("работа.json")),
            Some(PathBuf::from("семья.json"))
        )
        .display()
    );
}

По умолчанию: дела.json
Из окружения: семья.json
Из команды: работа.json

# Органайзер: выбор файла

1. Откройте https://www.rust-lang.org/tools/install, установите Rust для своей ОС, откройте новый терминал и проверьте `cargo --version`.
2. В папке проекта выполните `cargo run`.
3. Путь из команды имеет приоритет над окружением; затем берётся `дела.json` в текущей папке. В этом учебном примере значения переданы прямо в коде; файл ещё не создаётся.
4. Если Cargo сообщает ошибку, прочитайте её текст и проверьте, что команда запущена в папке с `Cargo.toml`.

После проверки

Изменённое значение окружения не обязано быть надёжным местом для секрета; здесь там только путь. Для настоящего органайзера документируйте, где лежат данные, как создаётся копия, что делать при повреждении и какие случаи ещё не покрыты. Документация cargo doc.

Предыдущий урок · Оглавление