Init commit

materials/7 principles of structural programming.md

@@ -0,0 +1,20 @@
+# Принципы структурного программирования
+
+Становление и развитие структурного программирования связано с именем Эдсгера Дейкстры.
+* Принцип 1. Следует отказаться от использования оператора безусловного перехода goto.
+* Принцип 2. Любая программа строится из трёх базовых управляющих конструкций: последовательность, ветвление, цикл.
+* Принцип 3. В программе базовые управляющие конструкции могут быть вложены друг в друга произвольным образом. Никаких других средств управления последовательностью выполнения операций не предусматривается.
+* Принцип 4. Повторяющиеся фрагменты программы можно оформить в виде подпрограмм (процедур и функций). Таким же образом (в виде подпрограмм) можно оформить логически целостные фрагменты программы, даже если они не повторяются.
+* Принцип 5. Каждую логически законченную группу инструкций следует оформить как блок. Блоки являются основой структурного программирования.
+* Принцип 6. Все перечисленные конструкции должны иметь один вход и один выход.
+* Принцип 7. Разработка программы ведётся пошагово, методом «сверху вниз» (top-down method).
+
+Следствия и дополнения вышеизложенных принципов:
+
+1. Запрет на использование глобальных переменных
+2. Не более одного выхода из функции. Исключение составляет предварительная проверка аргументов функции.
+3. Не более одного выхода из цикла - это может быть как условие, так и ключевое слово break
+4. Вложенность любых блоков не должна превышать 4
+5. Размер функций ограничен по строкам и составляет 40-50 строк
+
+![goto](../misc/eng/images/GOTO.png)

materials/from_developers.txt

@@ -0,0 +1,32 @@
+Message from developers: 
+Hello, dear friend! 
+Let's play a game. 
+Something like the good old text-based adventure games with elements of a puzzle. 
+Each Task is a challenge, usually some kind of a hurdle you need to overcome. 
+Only those who tackle them all will be able to move further. 
+
+Below are several tips to help you find your way: 
+1. During the entire journey, you will be accompanied by the feeling of uncertainty and a severe shortage of information: THAT'S OK. It's a part of the game. Remember that the information in the repository and Google are always there for you. Just like other players. Communicate. Search. Collect. Do not be afraid to make a mistake. 
+2. There may be a game inside the game, and another game inside it. That's normal. Just like in real life. Recursion is beautiful.
+3. Levels can be very different from one another. That's normal. It's a part of the game. You can't just learn one recipe and apply it everywhere. The only way to achieve the goal is by continuously learning and adapting. 
+4. It's a multiplayer game, even if it doesn't seem like it in the beginning.
+5. You will, however, be able to get through most of it on your own.
+6. Be careful with information sources. Check. Think. Analyze. Compare. Do not trust.
+7. Pay attention to the text of the task. Think. Check.
+8. If the task seems unclear or impossible–it only seems like it. Take your time, sit down in silence or with your favorite music. Get back to the task in 10–15 minutes and read the entire text once again. 
+9. If tip #8 hasn't helped–search for a guide. You are surrounded by many wanderers just like you and they will be happy to help you find the exit.
+10. Watch the time! It's deceitful. You have to complete at least one challenge a day!
+11. Be attentive and do not miss important things. Check the repository carefully!
+12. Always push only to the develop branch! The master branch will be ignored. Work in the src directory.
+13. Remember that each task undergoes a series of checks: code style check, static analyzer check, check for correct work with memory, check with a set of autotests, check with a checklist. Be careful.
+14. You will come across different tasks on your way. The tasks marked with the asterisk (*) are only for the most reckless ones. They are more difficult and not compulsory. But if you complete them, you will gain extra experience and knowledge.
+15. Some things may seem important but they are actually not. 
+16. Remember that ultimately the fact of completing the challenge is not as important as HOW you complete it.
+17. The main goal of our journey is to understand what "HOW" means.
+18. Separate the wheat from the chaff.
+19. Divide and rule. Decompose. 
+20. Think about the main thing (good code, obviously). Move from the general to the specific.
+21. Do not cheat, do not try to deceive the system and others. First of all, you will deceive yourself.
+22. Do not write off, but if you use help - always figure it out to the end. Otherwise, your journey will not make any sense.
+23. Check "materials" folder often. There can be a lot of useful things there!
+24. Reread these tips several times.

materials/from_developers_rus.txt

@@ -0,0 +1,33 @@
+От разработчиков: 
+Здравствуй, дорогой друг! 
+Мы предлагаем сыграть тебе в игру. 
+Игру, в духе старых добрых текстовых квестовых игр-бродилок с элементами головоломки. 
+Каждый Task — это очередное испытание,  обычно некоторое препятствие, которое необходимо преодолеть. 
+Лишь тот, кто пройдет все — сможет двинуться дальше. 
+
+Ниже приведено несколько напутствий, они помогут тебе найти свой путь: 
+1. Всю дорогу тебя будет сопровождать чувство неопределенности и острого дефицита информации: ЭТО НОРМАЛЬНО. Это часть игры. Не забывай, что информация в репозитории и Google — всегда с тобой. Как и другие игроки. Общайся. Ищи. Собирай. Не бойся ошибиться. 
+2. В игре может быть другая игра, в которой будет еще одна. Это нормально. Все как в жизни. Рекурсия — это красиво.
+3. Уровни могут сильно отличаться друг от друга. Это нормально. Это часть игры. Нельзя выучить один рецепт и его везде применять. Лишь непрерывно обучаясь и адаптируясь ты сможешь достигнуть цели. 
+4. Наша игра — многопользовательская, даже если сначала тебе покажется иначе.
+5. Хотя, большую часть пути ты сможешь преодолеть и один.
+6. Будь внимателен к источникам информации. Проверяй. Думай. Анализируй. Сравнивай. Не доверяй.
+7. Будь внимателен к тексту задания. Думай. Проверяй.
+8. Если задание кажется непонятным или невыполнимым — это только так кажется. Просто посиди спокойно, в тишине, или включи любимую музыку. Вернись к заданию через 10-15 минут и перечитай его полностью. 
+9. Если п.8 не помог — поищи проводника. Вокруг тебя — много таких же путников, как ты, они с радостью помогут найти тебе выход.
+10. Следи за временем! Оно коварно. В день ты должен преодолевать минимум одно испытание!
+11. Будь внимателен — и не упусти важное. Внимательно изучай репозиторий!
+12. Всегда делай push только в ветку develop! Ветка master будет проигнорирована. Работай в директории src.
+13. Помни, что каждое задание проходит ряд проверок: проверка на стиль кода, проверка статическим анализатором, проверка на корректную работу с памятью, проверка набором автотестов, проверка с помощью чеклиста. Будь внимателен. 
+14. На твоем пути тебе встретятся разные задания. Те, что помечены звездочкой (*) — подходят только для самых отчаянных. Они с повышенной сложностью и в целом не являются обязательными к выполнению. Но если ты их сделаешь, то получишь дополнительный опыт и знания.
+15. Иногда то, что кажется важным — не есть важное. 
+16. Помни, в конечном счете, факт преодоления препятствия не так важен, как то, КАК ты его преодолел.
+17. Главная цель нашего путешествия — осознать, что такое “КАК”.
+18. Отделяй зерна от плевел.
+19. Разделяй и властвуй. Декомпозируй. 
+20. Думай о главном (о хорошем коде, разумеется). Следуй от общего к частному.
+21. Не жульничай, не пытайся обмануть систему и окружающих. В первую очередь ты обманешь себя.
+22. Не списывай, а если пользуешься помощью - всегда разбирайся до конца, почему, как и зачем. Иначе твое путешествие не будет иметь никакого смысла.  
+23. Почаще заглядывай в папку materials. Там может быть много полезного!
+24. Перечитай напутствия несколько раз.
+

materials/instructions_for_testing.md

@@ -0,0 +1,67 @@
+# Instructions for running tests.
+
+In addition to testing for correct output data, the autotest system will check your program and its source code for the
+following points:
+
+* **Style tests.** To check how much the beauty of your code meets the standards, for example, you can test your code
+  using the _clang-format_ utility. The ```materials/linters``` folder contains the ```.clang-format``` file, which
+  contains the necessary settings for the style test. This configuration file extends its action to all files that lie
+  with it in the directory or in the directories below. So in order for these settings to apply to your source code
+  files, copy ```.clang-format``` to the ```src``` folder. \
+  \
+  To run the style check, run the following command: \
+  ```clang-format -n src/sourcefile_name.c``` \
+  \
+  To download _clang-format_, enter one of the following commands in the terminal: \
+  ```brew install clang-format``` \
+  or if you have root rights (for Ubuntu / Linux Mint / Debian) \
+  ```sudo apt install clang-format```
+
+  Required version of clang-format: \
+  **Mac** 14.0.5 \
+  **Linux** 13.0.1
+
+  Google Style: https://google.github.io/styleguide/cppguide.html
+
+
+* **Test for correct operation with memory.** When writing C programs, it is very important to watch for memory leaks.
+  To do this the _valgrind_ utility is quite often used in Unix-like operating systems. However, OS X has some troubles
+  with _valgrind_ support, so it is possible to use the _leaks_ utility instead. We will not go into the mechanism of
+  operation of these utilities now — if you are interested, you can read about it on Google.
+
+  **_LEAKS_**
+
+  To run your executable file using this utility, type in the terminal: \
+  ```leaks -atExit -- ./main.out | grep LEAK:```
+
+  Pay your attention that there is ```| grep LEAK:``` command. We use it to short leaks output to see only lines with
+  leaks if they are there. If you want to see the whole output, just remove this command.
+
+  When you run your executable file using _leaks_ you may see an error:
+  > dyld: could not load inserted library ‘/usr/local/lib/libLeaksAtExit.dylib’ because image not found
+
+  It’s because _leaks_ did not find _libLeaksAtExit.dylib_ library. \
+  You need to type the following commands in this case.
+  ```sh
+  cd /usr/local/lib  
+  sudo ln -s /Applications/Xcode.app/Contents/Developer/usr/lib/libLeaksAtExit.dylib
+  ```
+
+  _Additionally:_  \
+  Use the ```-exclude``` option of _leaks_ to filter out leaks in functions with known memory leaks. This option helps
+  reduce the amount of extra information reported by _leaks_.
+
+  **_VALGRIND_**
+  
+  To install it on your computer, type one of the following commands: \
+   ```brew install valgrind``` \
+   or if you have root rights (for Ubuntu / Linux Mint / Debian) \
+   ```sudo apt install valgrind``` \
+   To run your executable file using this utility, type in the terminal: \
+   ```valgrind --tool=memcheck --leak-check=yes. /main. out```
+   
+   It is strongly recommended not to use _valgrind_ utility in OS X, use _leaks_ utility instead.
+
+* **Build test.** The program can be checked for correct build on a test system environment. This will require _Docker_
+  installed. If the system has a docker, then you can go to the `materials/build` directory and run the run.sh script
+  from there. The script will wrap your solution in docker and run it along with a typical build script.

materials/instructions_for_testing_rus.md

@@ -0,0 +1,67 @@
+# Инструкция по запуску тестов.
+
+Помимо тестов на корректные выходные данные система автотестирования будет проверять вашу программу и ее исходный код по
+следующим пунктам:
+
+* **Стилевые тесты.** Чтобы проверить, насколько красота вашего кода соответствует стандартам, вы можете протестировать
+  ваш код с помощью утилиты _clang-format_. В папке ```materials/linters``` лежит файл ```.clang-format```, который
+  содержит необходимые настройки для стилевого теста. Данный конфигурационный файл распространяет свое действие на все
+  файлы, которые лежат с ним в директории или в директориях ниже. Поэтому, чтобы данные настройки применились к вашим
+  файлам с исходным кодом, скопируйте ```.clang-format``` в папку ```src```. \
+  \
+  Чтобы запустить проверку на стиль, выполните следующую команду: \
+  ```clang-format -n src/sourcefile_name.c``` \
+  \
+  Чтобы скачать _clang-format_, введите в терминал одну из следующих команд: \
+  ```brew install clang-format``` \
+  или, если у вас есть root-права (для Ubuntu / Linux Mint / Debian) \
+  ```sudo apt install clang-format```
+
+  Необходимая версия clang-format: \
+  **Mac** 14.0.5 \
+  **Linux** 13.0.1
+
+  Google Style: https://google.github.io/styleguide/cppguide.html
+
+
+* **Тест на корректную работу с памятью.** При написании C-программ очень важно следить за утечками памяти. Для этого в
+  Unix-подобных операционных системах довольно часто используют утилиту _valgrind_. Однако, на OS X имеются проблемы с
+  поддержкой _valgrind_, поэтому вместо нее можно использовать утилиту _leaks_. Вдаваться в механизм работы этих утилит
+  мы сейчас не будем — если интересно, можете почитать в гугле.
+
+  **_LEAKS_**
+
+  Чтобы запустить ваш исполняемый файл с помощью этой утилиты, наберите в терминале: \
+  ```leaks -atExit -- ./main.out | grep LEAK:```
+
+  Обратите внимание на команду ```| grep LEAK:```. Мы используем ее для короткого вывода, чтобы видеть только линии с
+  утечками, если они есть. Если вы хотите увидеть весь вывод, просто удалите эту команду.
+
+  При запуске исполняемого файла с помощью _leaks_ может появиться сообщение об ошибке:
+  > dyld: could not load inserted library ‘/usr/local/lib/libLeaksAtExit.dylib’ because image not found
+
+  Ошибка возникает из-за того, что _leaks_ не может найти библиотеку _libLeaksAtExit.dylib_. \
+  В этом случае вам необходимо ввести следующие команды:
+  ```sh
+  cd /usr/local/lib  
+  sudo ln -s /Applications/Xcode.app/Contents/Developer/usr/lib/libLeaksAtExit.dylib
+  ```
+
+  _Дополнительно:_ \
+  Используйте флаг ```-exclude``` утилиты _leaks_ для того, чтобы отфильтровать утечки в функциях, где известно об
+  утечках памяти. Этот флаг позволяет уменьшить количество посторонней информации, сообщаемой _leaks_.
+
+  **_VALGRIND_**
+
+  Чтобы установить _valgrind_ на компьютер, введите одну из следующих команд: \
+  ```brew install valgrind``` \
+  или, если у вас есть root-права (для Ubuntu / Linux Mint / Debian) \
+  ```sudo apt install valgrind``` \
+  Чтобы запустить ваш исполняемый файл с помощью этой утилиты, наберите в терминале: \
+  ```valgrind --tool=memcheck --leak-check=yes  ./main.out```
+
+  Не рекомендуется использовать _valgrind_ на OS X, вместо нее лучше использовать _leaks_.
+
+* **Тест сборки.** Программу можно проверить на корректность сборки на тестовой системе. Для этого потребуется
+  установленный _Docker_. Если на системе есть докер, то можно зайти в директорию `materials/build` и запустить оттуда
+  скрипт run.sh. Скрипт обернет ваше решение в докер и запустит его вместе с типовым сценарием сборки.

materials/library-specification.md

@@ -0,0 +1,38 @@
+# Спецификация для библиотеки игры из коллекции игр BrickGame
+
+Это задание является первым из серии BrickGame. Всего будет четыре проекта, в каждой - своя игра и свои технологии. Но помимо разработки новых проектов, необходимо будет поддерживать и старые игры, и добавлять поддержку новых игр в старые проекты. В этот раз интерфейс будет консольным, в следующем - десктопный, и так далее. Для того чтобы поддерживать старые и новые игры необходимо заранее определиться как будет устроено АПИ интерфейсов и библиотек, чтобы в дальнейшем не приходилось переписывать уже сданные проекты.
+
+Игровое поле представляется как матрица размерностью десять на двадцать. Каждый элемент матрицы соответствует "пикселю" игрового поля и может находится в одном из двух состояний: пустой и заполненный. Кроме игрового поля у каждой игры есть дополнительная информация, которая выводится в боковой панели справа от игрового поля. Для дополнительной информации, не используемой во время игры, предусмотреть заглушки.
+
+Каждая библиотека с игрой должна иметь функцию, принимающую на вход пользовательский ввод. У консоли имеется восемь физических кнопок: начало игры, пауза, завершение игры, действие и четыре стрелочки.
+
+Функция `userInput` принимает на вход пользовательское действие `action` и дополнительный параметр `hold`, который отвечает за зажатие клавиши.
+
+Функция `updateCurrentState` предназначена для получения данных для отрисовки в интерфейсе. Она возвращает структуру, содержащую информацию о текущем состоянии игры. Например, для тетриса истечение таймера приводит к смещению фигуры вниз на один ряд. Эта функция должна вызываться из интерфейса с некоторой периодичностью для поддержания интерфейса в актуальном состоянии.
+
+```c
+typedef enum {
+    Start,
+    Pause,
+    Terminate,
+    Left,
+    Right,
+    Up,
+    Down,
+    Action
+} UserAction_t;
+
+typedef struct {
+    int **field;
+    int **next;
+    int score;
+    int high_score;
+    int level;
+    int speed;
+    int pause;
+} GameInfo_t;
+
+void userInput(UserAction_t action, bool hold);
+
+GameInfo_t updateCurrentState();
+```

materials/linters/.clang-format

@@ -0,0 +1,2 @@
+---
+BasedOnStyle: Google

materials/topics-list.md

@@ -0,0 +1,14 @@
+# Topoics list
+
+Hello, student of School21!😉
+
+To make it easier for you to navigate the material, we have prepared a list of topics that you will learn in this project.
+
+We will study:
+
+- finite-state machine;
+- working with matrixes;
+- working with files;
+- working with GUI library.
+
+Now, knowing what awaits you in this project, you can slowly begin to study the topics listed above.😇

materials/topics-list_RUS.md

@@ -0,0 +1,12 @@
+# Topics list
+
+Привет, участник Школы21!😉
+
+Чтобы тебе было проще, мы подготовили список тем, на которые следует обратить особое внимание при выполнении данного проекта:
+
+- конечные автоматы;
+- работа с матрицами;
+- работа с файлами;
+- работа с графическими интерфейсами.
+
+Теперь, когда известен список тем, знания которых потребуются в проекте, можешь приступать к изучению.😇