Merge pull request #7 from bialger/deadline_0

Use ArgParser from GitHub, minor version update

CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.12)
 
 project(
         weather-forecast
-        VERSION 1.3
+        VERSION 1.3.5
         DESCRIPTION "Console weather forecast app that uses OpenMeteo and Yandex Geocoder API"
         LANGUAGES CXX
 )

README.md

@@ -1,45 +1,222 @@
-# Лабораторная работа 7
+# Программа weather-forecast
+
+Данная программа предоставляет прогноз погоды в терминале с удобным текстовым интерфейсом.
+Она была написана как лабораторная работа в курсе "Программирование на C++" в программе ITMO SE.
+С заданием можно ознакомиться [здесь](./TASK.md).
 
 Документация проекта находится [в соответствующей папке](./docs/README.md).
 
-Прогноз погоды. Внешние библиотеки.
+Этот документ описывает сборку из исходного кода и использование программы
+weather-forecast.
+
+## Зависимости
+
+Для успешной компиляции требует установленного `Git`, `CMake` и компилятора C++,
+поддерживающего стандарт C++20.
+Также потребуется ключ от [Yandex Geocoder API](https://yandex.ru/dev/geocode/doc/ru/).
+
+> Если Вам не хочется получать ключ, можно воспользоваться архивом кэша:
+> [cache.zip](https://github.com/bialger/weather-forecast/releases/download/v1.2.0/cache.zip).
+> После распаковки поместите в каталог /.config, а затем начните установку. 
+> <br>
+> Используйте вместо API-ключа `00000000-0000-0000-0000-000000000000`.
+
+## Как собрать
+
+> **Важно!**<br>
+> Для ОС Windows успешная сборка и компиляция возможна **только** при
+> установленном компиляторе `MinGW`.
+
+В данном документе описана исключительно процедура сборки главного исполняемого
+файла.
+> Процесс сборки тестов описан не будет, его можно восстановить из
+[CI/CD скрипта](/.github/workflows/ci_tests.yml).
+
+### Автоматическая сборка и установка
+
+Сделайте исполняемым и запустите [shell-script установки](/install.sh), затем следуйте
+инструкциям.
+> **Важно!**<br>
+> Для ОС Windows автоматизированная сборка гарантирована только
+> при запуске в Git Bash.
+
+```shell
+chmod +x ./install.sh && ./install.sh
+```
+
+### Ручная сборка
+
+* Сначала, если Вы этого не сделали, клонируйте проект и перейдите в его каталог:
+
+```shell
+git clone https://github.com/bialger/weather-forecast.git && cd weather-forecast
+```
+
+#### Linux и MacOs
+
+* Создайте Release-кеш CMake:
+
+```shell
+cmake -S . -B ~/CMakeBuilds/weather-forecast -DCMAKE_BUILD_TYPE=Release
+```
+
+* Соберите проект из этого кеша:
+
+```shell
+cmake --build ~/CMakeBuilds/weather-forecast --target weather-forecast
+```
+
+* Введите ключ от [Yandex Geocoder API](https://yandex.ru/dev/geocode/doc/ru/) и
+  запишите его в соответсвующий файл:
+
+```shell
+read -r API_KEY && echo "$API_KEY" > "./.config/yandex_api_key.apikey"
+```
+
+* Скопируйте в конфигурационный каталог файлы конфигурации:
+
+```shell
+cp -r ./.config ~/.config/weather-forecast
+```
+
+* Создайте символьную ссылку на исполняемый файл (`~/weather-forecast.run`):
+
+```shell
+ln -s ~/CMakeBuilds/weather-forecast/bin/weather-forecast ~/weather-forecast.run
+```
+
+* Запустите программу:
+
+```shell
+~/weather-forecast.run
+```
+
+#### Windows (`cmd.exe`)
 
-## Задача
+* Создайте Release-кеш CMake:
 
-Реализовать консольное приложение, отображающие прогноз погоды для выбранного списка городов, используя сторонние библиотеки.
+```shell
+cmake -S . -B "%userprofile%\CMakeBuilds\weather-forecast" -DCMAKE_BUILD_TYPE=Release
+```
 
-## Источник данных
+* Соберите проект из этого кеша:
 
-- [Open-Meteo](https://open-meteo.com/en/docs#latitude=59.94&longitude=30.31&hourly=temperature_2m&forecast_days=16) для прогноза
-- [Api-Ninjas](https://api-ninjas.com/api/city) для определения координат по названию города
+```shell
+cmake --build "%userprofile%\CMakeBuilds\weather-forecast" --target weather-forecast
+```
 
-## Функциональные требования
+* Введите ключ от [Yandex Geocoder API](https://yandex.ru/dev/geocode/doc/ru/) и
+  запишите его в соответсвующий файл:
 
- - Отображать прогноз погоды на несколько дней вперед (значение по умолчанию задается конфигом)
- - Обновлять с некоторой частотой (задается конфигом)
- - Переключаться между городами с помощью клавиш "n", "p"
- - Заканчивать работу программы по Esc
- - Увеличивать\уменьшать количество дней прогноза по нажатие клавиш "+", "-"
+```shell
+SET /P API_KEY="Enter your Yandex Geocoder API key: " && echo %API_KEY% > ".config\yandex_api_key.apikey"
+```
 
-Список городов, частота обновления, количество дней прогноза должны быть определены в конфиге(например в формате ini, json, xml)
+* Скопируйте в конфигурационный каталог файлы конфигурации:
 
-## Отображение
+```shell
+xcopy /si .config "%userprofile%\.config\weather-forecast"
+```
 
-В качестве образца для визуализации предлагается взять следующий:
+* Скопируйте исполняемый файл и библиотеки в каталог `%userprofile%\weather-forecast` для быстрого доступа
 
-![image](assets/interface.png) Скриншот взят с  https://wttr.in
+```shell
+mkdir "%userprofile%\weather-forecast"
+copy "%userprofile%\CMakeBuilds\weather-forecast\weather-forecast.exe" "%userprofile%\weather-forecast\weather-forecast.exe"
+copy "%userprofile%\CMakeBuilds\weather-forecast\libcpr.dll" "%userprofile%\weather-forecast\libcpr.dll"
+copy "%userprofile%\CMakeBuilds\weather-forecast\libcurl.dll" "%userprofile%\weather-forecast\libcurl.dll"
+```
 
-## Реализация
+* Создайте символьную ссылку на исполняемый файл (`%userprofile%\weather-forecast\weather-forecast.exe`):
 
-В данной лабораторной работе вам не запрещено использовать другие библиотеки.
+```shell
+mklink "%userprofile%\weather-forecast.exe" "%userprofile%\weather-forecast\weather-forecast.exe"
+```
 
-В качестве библиотеки для [HTTP-запросов](https://en.wikipedia.org/wiki/HTTP) требуется воспользоваться [C++ Requests](https://github.com/libcpr/cpr)
+> Для Windows запуск такой ссылки из командной строки или иного эмулятора терминала
+> полноценно невозможен, только из Проводника.
 
+* Запустите программу:
 
-В данной работе, при взаимодействии с внешними сервисами, может возникать достаточно большое количество коллизий и краевых случаев. Внимательно, подумайте об этом! Ваша программа должна корректно работать и "не падать"
+```shell
+cd %userprofile%\weather-forecast && .\weather-forecast.exe
+```
 
-## Deadline
+## Использование
 
-1. 20.02.24 0.85
-2. 27.02.24 0.65
-3. 05.03.24 0.5
+Программа weather-forecast - консольное приложение для просмотра погоды.
+Предусмотрен показ погоды для локаций, перечисленных в конфигурационном файле, на
+текущий момент, а также на утро, день, вечер и ночь некоторого количества дней.
+Программа в один момент времени отображает непосредственно прогноз на три дня, для
+просмотра прочих следует использовать навигации. 
+В случае отсутствия Интернет-соединения программа запустится, однако не будет отображать 
+актуальную информацию. 
+Для получения актуальных данных возобновите подключение и обновите данные в программе.
+
+> Поскольку программа использует
+[Yandex Geocoder API](https://yandex.ru/dev/geocode/doc/ru/), для работы
+> требуется валидный API-ключ.
+> Бесплатная версия поддерживает 1000 запросов в сутки.
+
+### Пример интерфейса
+
+![image](/assets/weather_forecast_1.png)
+
+### Вызов
+
+Программа может быть вызвана без аргументов - будут применены значения по умолчанию.
+Порядок аргументов не имеет значения.
+
+#### Аргументы командной строки:
+
+* `-l` или `--location` - строка с названием первой локации, для которой будет
+  предоставлен прогноз погоды. 
+  Если аргумент не указан, первая локация получается из конфигурационного файла.
+* `-c` или `--config` - строка с именем файла конфигурации в формате JSON.
+  Значения по умолчанию получают из
+  [файла конфигурации по умолчанию](/.config/default_config.json).
+  Документ должен содержать строковое поле `api_key_file` с относительным путем к
+  файлу, содержащему ключ к
+  [Yandex Geocoder API](https://yandex.ru/dev/geocode/doc/ru/); поле `locations`,
+  содержащее список локаций (строк, содержащие адрес или название города на
+  английском языке) для показа погоды; поле `defaults`, содержащее следующие
+  значения параметров по умолчанию:
+    * `interval` - как аргумент `--interval`.
+    * `days_count` - как аргумент `--days-count`
+    * `location_index` - целое неотрицательное число, являющееся индексом локации
+      по умолчанию из списка `locations`. 
+      Строго меньше количества локаций.
+* `-L` или `--log-file` - строка с именем файла для записи логов. 
+  Имя файла должно быть валидным, в частности, не являться именем каталога. 
+  Если параметр не указан, логи выводятся в стандартный поток вывода.
+* `-d` или `--days-count` - целое положительное число, определяющее количество дней
+  прогноза, отображаемых при запуске программы. 
+  Не может превышать 15. 
+  Если аргумент не указан, частота обновления получается из конфигурационного файла.
+* `-i` или `--interval` - целое положительное число, определяющее частоту
+  обновлений в часах. 
+  Не может превышать 48. 
+  Если аргумент не указан, частота обновления получается из конфигурационного файла.
+* `-v` или `--verbose` - флаг, при истинности которого происходит вывод логов работы
+  программы.
+* `-h` или `--help` - флаг, при истинности которого вместо выполнения программы
+  происходит вывод справки и завершение работы.
+
+### Использование
+
+Навигация в программе происходит с помощью нажатий клавиш.
+
+#### Список управляющих клавиш
+
+* `Esc` или `q` - выход из программы.
+* `F5` или `r` - обновление данных.
+* `+` - увеличение количества отображаемых дней на единицу, но не более 15.
+* `-` - уменьшение количества отображаемых дней на единицу, но не менее 3.
+  При этом в том случае, если фокус направлен на последни день, происходит
+  смещение фокуса вверх.
+* `w` или `ArrowUp` - смещение фокуса отображения вверх (меньшая дата) на единицу.
+* `s` или `ArrowDown` - смещение фокуса отображения вверх (меньшая дата) на единицу.
+* `n`, `d` или `ArrowRight` - переход к следующей локации из списка. 
+  При достижении конца списка следующим считается первый элемент.
+* `p`, `a` или `ArrowLeft` - переход к предыдущей локации из списка. 
+  При достижении начала списка предыдущим считается последний элемент.

TASK.md

@@ -0,0 +1,43 @@
+# Лабораторная работа 7
+
+Прогноз погоды. Внешние библиотеки.
+
+## Задача
+
+Реализовать консольное приложение, отображающие прогноз погоды для выбранного списка городов, используя сторонние библиотеки.
+
+## Источник данных
+
+- [Open-Meteo](https://open-meteo.com/en/docs#latitude=59.94&longitude=30.31&hourly=temperature_2m&forecast_days=16) для прогноза
+- [Api-Ninjas](https://api-ninjas.com/api/city) для определения координат по названию города
+
+## Функциональные требования
+
+- Отображать прогноз погоды на несколько дней вперед (значение по умолчанию задается конфигом)
+- Обновлять с некоторой частотой (задается конфигом)
+- Переключаться между городами с помощью клавиш "n", "p"
+- Заканчивать работу программы по Esc
+- Увеличивать\уменьшать количество дней прогноза по нажатие клавиш "+", "-"
+
+Список городов, частота обновления, количество дней прогноза должны быть определены в конфиге(например в формате ini, json, xml)
+
+## Отображение
+
+В качестве образца для визуализации предлагается взять следующий:
+
+![image](assets/interface.png) Скриншот взят с  https://wttr.in
+
+## Реализация
+
+В данной лабораторной работе вам не запрещено использовать другие библиотеки.
+
+В качестве библиотеки для [HTTP-запросов](https://en.wikipedia.org/wiki/HTTP) требуется воспользоваться [C++ Requests](https://github.com/libcpr/cpr)
+
+
+В данной работе, при взаимодействии с внешними сервисами, может возникать достаточно большое количество коллизий и краевых случаев. Внимательно, подумайте об этом! Ваша программа должна корректно работать и "не падать"
+
+## Deadline
+
+1. 20.02.24 0.85
+2. 27.02.24 0.65
+3. 05.03.24 0.5

docs/README.md

@@ -8,8 +8,4 @@
 * [Проблема](dev/problem.md)
 * [Требования](dev/requirements.md)
 * [Архитектура](dev/architecture.md)
-
-## Итоговая документация 
-
-* [Модуль ArgParser](../lib/argparser/docs/README.md)
-* [Мануал weather-forecast](WeatherForecast.md)
+* [Модуль ArgParser, v1.1.0](https://github.com/bialger/ArgParser/blob/v1.1.0/lib/argparser/docs/README.md)