utils/table-generator/convert.py: додав захист від повторної обробки файлів таблиць та виправив декілька помилок

Reviewed-on: #22

docs/requirements/README.md

@@ -1,14 +1,13 @@
 # Розроблення вимог до системи
 
 ## Вступ
-У даному розділі проводиться аналіз предметної області, пов'язаної з системою організації та управління експертними опитуваннями.
+У даному розділі проводиться аналіз предметної області, пов'язаної з системою організації та управління експертними опитуваннями. Представлені такі категорії:
-Аналіз методів експертного опитування розкриє їхні переваги та недоліки. 
 
-Розпишемо підходи та методи організації систем організації та опитування експертів.
+- [Основні визначення](#основні-визначення), котрі можна зустріти в сфері експертних опитувань
-Ми визначимо доцільність розробки нового проєкту шляхом аналізу переваг та недоліків наявних інструментів, а також їх зіставлення з нашим майбутнім.
+- [Підходи та способи вирішення завдання](#підходи-та-способи-вирішення-завдання) опитування експертів
-В глосарії опишемо основні терміни та поняття, котрі можна зустріти в сфері експертних опитувань.
+- [Порівняльна характеристика наявних засобів вирішення завдання](#порівняльна-характеристика-існуючих-засобів-вирішення-завдання) опитування експертів
-
+- [Висновки](#висновки) щодо доцільності розробки нової системи
-У висновку сформуємо ключові аспекти, на які слід звертати увагу, щоб забезпечити успішну та ефективну реалізацію проєкту.
+- [Література](#література), де наведені посилання на джерела інформації
 
 ## Основні визначення
 ### Технічні визначення
@@ -102,7 +101,9 @@ SQL (англ. Structured query language — мова структуровани
  
 Мінуси: відсутність структури; можливість домінування деяких учасників.
 
-Тепер давайте розглянемо найпопулярніші інструменти для проведення анкетувань.
+## Порівняльна характеристика існуючих засобів вирішення завдання
+
+Розглядатимемо такі найпопулярніші інструменти для проведення анкетувань:
 
 [Google Forms](https://uk.wikipedia.org/wiki/Google_Форми)
 
@@ -115,26 +116,6 @@ Google Slides, Google Drawings, Google Sites і Google Keep. Google Форми
 в режимі реального часу. Зібрану інформацію можна автоматично внести в 
 електронну таблицю.
 
-Цілком можливо, що Google Forms є одним із найпоширеніших конструкторів 
-форм, доступних сьогодні. Враховуючи численні переваги Google Forms, 
-величезна популярність програми не повинна бути несподіванкою. 
-
-Однак, як будь-яка інша програма, Google Forms також має деякі помітні 
-недоліки. 
-
-Переваги Google Forms:
-- Зручність 
-- Простота використання
-- Це безкоштовно
-- Співпраця з колегами 
-- Необмежена кількість форм
-- Потужні функції (кілька типів запитань, поле завантаження файлу, умовна 
-логіка)
-- Кілька варіантів розповсюдження
-- Частина екосистеми Google
-
-![GoogleForms](http://139.162.162.130:16660/img/img-1.1.jpg)
-
 [SurveyMonkey](https://en.wikipedia.org/wiki/SurveyMonkey)
 
 SurveyMonkey - це служба як для створення простих і невеликих опитувань, 
@@ -145,32 +126,6 @@ SurveyMonkey - це служба як для створення простих
 та наочні звіти, захищати дані та інтегрувати засоби з MailChimp, 
 GroSocial та іншими сервісами.
 
-Функції, які може запропонувати сервіс:
-- 51 шаблон опитувань та 15 типів питань.
-- Підтримка всіх мов (Unicode).
-- Логіка сторінок та питань.
-- Випадковий розкид питань та конвеєрна організація.
-- Користувальницькі готові теми та звіти.
-- Сортування варіантів відповідей та випадковий розкид.
-- Індикатор пройдених питань.
-- Автонумерація сторінок та питань.
-- Переадресація після завершення та сторінка подяк.
-- Версія PDF для друку.
-- Можливість надіслати опитування за веб-посиланням, поштою, у Twitter 
-або Facebook.
-- Настроювана URL-адреса.
-- Можливість вставити опитування на веб-сторінку або на спливаюче вікно.
-- Розсилання опитувань диспетчером.
-- Підвищена безпека (SSL).
-- Підсумки в режимі реального часу.
-- Аналітика тексту.
-- Інтеграція SPSS(пакету програм, який використовується для аналізу 
-статистичних даних).
-- Фільтри та перехресні таблиці відповідей за критеріями.
-- Загальний доступ до відповідей.
-
-![SurveyMonkey](http://139.162.162.130:16660/img/img-1.2.jpg)
-
 [Responsly](https://www.responsly.com)
 
 Responsly - платформа, яка дозволяє створювати онлайн-опитування та 
@@ -179,18 +134,6 @@ Responsly - платформа, яка дозволяє створювати о
 надає широкий вибір типів питань для опитувань, вибраних спеціально для 
 певної аудиторії.
 
-Функції, які може запропонувати сервіс:
-- 25+ типів питань
-- Автоматизація та інтеграція - планування надсилань опитувань і 
-створення власних сповіщення. 
-- Калькулятор - можливість обчислення балів, цін та інших змінних на 
-основі відповідей людей. Створення різних кінцевих сторінок на основі 
-балів.
-- Багатомовні опитування.
-- Безпека корпоративного рівня.
-
-![Responsly](http://139.162.162.130:16660/img/img-1.3.jpg)
-
 [Jotform](https://en.wikipedia.org/wiki/Jotform)
 
 Jotform — це потужна онлайн програма, яка дозволяє будь-кому швидко 
@@ -202,53 +145,13 @@ Jotform — це потужна онлайн програма, яка дозво
 відповіді безпосередньо в електронних листах та створювати PDF форми для 
 заповнення. 
 
-Функції, які може запропонувати сервіс:
-- Тисячі готових до використання безкоштовних шаблонів, які допоможуть 
-користувачу створювати форми.
-- Вбудований інструмент умовної логіки, який може показувати або 
-приховувати будь-які вибрані користувачем поля форми, залежно від того, 
-як люди відповідають на запитання.
-- Не потрібний досвід програмування.
-- Jotform дуже серйозно ставиться до безпеки даних користувачів.
-- Легка інтеграція платежів.
-- Інтеграція віджетів.
-
-![Jotform](http://139.162.162.130:16660/img/img-1.4.jpg)
-
 [QuestionPro](https://questionpro.com/)
 
 QuestionPro — це програмне забезпечення для створення та розповсюдження 
 опитувань. Воно складається з інтуїтивно зрозумілого інтерфейсу для 
 створення запитань для опитувань, інструментів для їх  розповсюдження 
 електронною поштою або на веб-сайті та інструментів для аналізу та 
-перегляду результатів. 
+перегляду результатів.
-
-Достатньо просто створити опитування та надіслати його електронною поштою 
-потенційним респондентам. QuestionPro подбає про збір і запис відповідей, 
-а результати будуть доступні в реальному часі.
-
-Функції, які може запропонувати сервіс:
-- Необмежена кількість опитувань.
-- Необмежена кількість відповідей.
-- 20+ професійних тем опитування.
-- Додавання свого логотипу.
-- Експорт необроблених даних.
-- Цілодобова підтримка електронною поштою.
-- Індекс підтримки споживача (NPS).
-- Багатомовні опитування.
-- Розширена логіка розгалуження.
-- Мобільний додаток QuestionPro.
-- Експорт SPSS (пакету програм, який використовується для аналізу 
-статистичних даних).
-- Цілодобовий чат і телефонна підтримка.
-- Аналіз тональності тексту (клас методів контент-аналізу в комп'ютерній 
-лінгвістиці, призначений для автоматизованого виявлення в текстах 
-емоційно забарвленої лексики).
-- Функції інтеграції опитувань.
-- Функції автоматизації опитувань.
-- Адміністрування опитування та функції безпеки.
-
-![QuestionPro](http://139.162.162.130:16660/img/img-1.5.jpg)
 
 [Fillout](https://www.fillout.com/)
 
@@ -260,23 +163,7 @@ Fillout. Для компаній із суворими вимогами щодо
 іншими вимогами Fillout пропонує корпоративне рішення для безпечного 
 отримання даних у будь-якому масштабі.
 
-Функції може запропонувати сервіс:
+Порівняймо наведені вище сервіси із нашим проєктом.
-- Fillout пропонує широкий вибір шаблонів опитувань, придатних для різних 
-цілей, включаючи відгуки клієнтів, дослідження ринку, задоволеність 
-працівників тощо. Кожен шаблон розроблено, щоб допомогти отримати 
-користувачу цінну інформацію, і його легко налаштувати відповідно до 
-потреб.
-- Fillout забезпечує легку інтеграцію з різними платформами, забезпечуючи 
-безпроблемну передачу та аналіз даних, які збирає користувач під час 
-своїх опитувань. 
-- Функція масового імпорту питань.
-- Потужна інтуїтивна логіка.
-
-![Fillout](http://139.162.162.130:16660/img/img-1.6.jpg)
-
-## Порівняльна характеристика існуючих засобів вирішення завдання
-
-Серед наявних наразі сервісів порівняймо ті, що були описані вище, із нашим проєктом.
 
 Умовні позначення в таблиці порівняння:
 - 🔴 засіб не відповідає критерію
@@ -315,5 +202,20 @@ Fillout. Для компаній із суворими вимогами щодо
 |Онлайн-підтримка| 🟢 | $72/рік | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
 
 ## Висновки
+Завдяки проведеному дослідженню ринку бачимо, що більшість сучасних платформ не надають безкоштовної можливості налаштовувати умовні переходи між сторінками опитування, а також значно обмежують максимальну кількість зібраних відповідей. Комбінація цих функцій у безкоштовній версії нашого сервісу може стати вагомою перевагою для певних груп користувачів.
 
-*[Робляться висновки щодо доцільності розробки нової або модифікації існуючої інформаційної системи, необхідності та способів інтеграції з системами(сервісами) третіх сторін, тощо.]*
+Також додаткові функції (такі як квоти відповідей або перегляд недозаповнених форм), що наявні в безкоштовній версії продукту, можуть привабити додаткових користувачів, що бажають отримати такі інструменти, проте не хочуть віддавати чималі гроші за коштовні сервіси. З огляду на це вважаємо, що розробка такого проєкту має сенс.
+
+## Література
+
+1. [https://uk.wikipedia.org/wiki/База_даних](https://uk.wikipedia.org/wiki/База_даних)
+2. [https://uk.wikipedia.org/wiki/SQL](https://uk.wikipedia.org/wiki/SQL)
+3. [https://uk.wikipedia.org/wiki/Опитування](https://uk.wikipedia.org/wiki/Опитування)
+4. [https://ela.kpi.ua/server/api/core/bitstreams/8a8030cf-bfc1-4586-b197-1c7e3bf02700/content](https://ela.kpi.ua/server/api/core/bitstreams/8a8030cf-bfc1-4586-b197-1c7e3bf02700/content)
+5. [http://elbib.in.ua/vidi-ekspertnogo-opituvannya-metodologiya-ta-metodi-sotsiologichnih-doslidjen.html](http://elbib.in.ua/vidi-ekspertnogo-opituvannya-metodologiya-ta-metodi-sotsiologichnih-doslidjen.html)
+6. [https://uk.wikipedia.org/wiki/Google_Форми](https://uk.wikipedia.org/wiki/Google_Форми)
+7. [https://en.wikipedia.org/wiki/SurveyMonkey](https://en.wikipedia.org/wiki/SurveyMonkey)
+8. [https://www.responsly.com](https://www.responsly.com)
+9. [https://en.wikipedia.org/wiki/Jotform](https://en.wikipedia.org/wiki/Jotform)
+10. [https://questionpro.com/](https://questionpro.com/)
+11. [https://www.fillout.com/](https://www.fillout.com/)

docs/requirements/stakeholders-needs.md

@@ -0,0 +1,86 @@
+# Запити зацікавлених осіб
+
+## Вступ
+
+*[Вступ повинен містити короткий огляд всього документу.]*
+
+### Мета 
+
+*[Визначення мети цієї сукупності вимог. Зазвичай такою метою є створення та впровадження 
+ інформаційної системи відповідного призначення.]*
+
+### Контекст
+
+*[Короткий опис того, з якими проектами пов'язаний цей документ, на що він впливає.]*
+
+
+### Основні визначення та скорочення
+
+*[Розділ містить визначення всіх термінів та скорочень, необхідних для правильного
+тлумачення вимог. Можна зробити посилання на документ, в якому поданий аналіз предметної області.]*
+
+
+### Посилання
+
+*[Розділ містить повний список всіх документів, про які згадується.]*
+
+
+## Короткий зміст
+
+*[Розділ містить опис того, про що йдеться в еій частині цього документу, що залишилася. 
+Також тут описана структура документу.]*
+
+## Характеристика ділових процесів
+
+*[В цьому розділі визначаються зовнішні фактори, що впливають на бізнес (бізнес-актори), 
+та внутрішні фактори (робітники), дається загальна характеристика діяльності бізнес-акторів 
+та робітників, яка здійснюється за допомогою бізнесу.*
+
+*Дається опис бізнес-сценаріїв взаємодії бізнес-акторів, робітників і, можливо, інформаційної системи за допомогою наступної
+специфікації:*
+
+   
+***ID:***
+    
+***НАЗВА:***
+    
+***УЧАСНИКИ:***
+
+***ПЕРЕДУМОВИ:***
+
+***РЕЗУЛЬТАТ:***
+
+***ВИКЛЮЧНІ СИТУАЦІЇ:***
+
+***ОСНОВНИЙ СЦЕНАРІЙ:***
+
+*Кількість сценаріїв визначається у відповідності до специфіки завдання та необхідного 
+рівня деталізації (зазвичай, 5-6 сценаріїв).*
+
+## Короткий огляд продукту
+
+*[Визначається границя системи та категорії її користувачів. Дається загальна характеристика категорій користувачів
+системи]*
+
+*[Нижче йде опис FURPS:]*
+
+
+## Функціональність
+
+*[Functionality (функциональні вимоги)]*
+
+## Практичність
+
+*[Usability (вимоги до зручності роботи)]*
+
+## Надійність
+
+*[Reliability (вимоги до надійності)]*
+
+## Продуктивність
+
+*[Performance (вимоги до продуктивності)]*
+
+## Експлуатаційна придатність
+
+*[Supportability (вимоги до підтримки)]*

utils/table-generator/convert.py

@@ -0,0 +1,160 @@
+#!/bin/python3
+
+import sys
+
+# magic values
+NO   = 0
+AUTO = 1
+YES  = 2
+
+def convert_generic_v1(data):
+    split_raw_lines = [i.strip().split("|") for i in data.split("\n") if i]
+    
+    return generate_table(split_raw_lines)
+
+def convert_usecase_v1(filename, data):
+    split_raw_lines_from_file = [i.split(" | ") for i in data.split("\n") if i]
+
+    if '/' in filename:
+        use_case_name = filename.rsplit("/", 1)[1].upper()
+    elif '\\' in filename:
+        use_case_name = filename.rsplit("\\", 1)[1].upper()
+    else:
+        use_case_name = filename.upper()
+
+    split_raw_lines = [["ID", use_case_name]] + split_raw_lines_from_file
+
+    merged_lines = []
+    for i in split_raw_lines:
+        if i[0] == "":
+            merged_lines[-1][1] += "<br>" + i[1]
+        else:
+            merged_lines.append(i)
+
+    return generate_table(merged_lines)
+
+def generate_table(raw_table_data):
+    table_lines = raw_table_data
+    transposed_table = list(zip(*table_lines))
+
+    field_sizes = [max([max([len(k)+2 for k in j.split("\n")]) for j in i]) for i in transposed_table]
+
+    formatted_table_lines = []
+
+    l = "|"
+    for i, field in enumerate(table_lines[0]):
+        l += field.center(field_sizes[i])
+        l += "|"
+
+    formatted_table_lines.append(l)
+    formatted_table_lines.append(f"|{'|'.join([':'+'-'*(i-2)+':' for i in field_sizes])}|")
+
+    for line in table_lines[1:]:
+        l = "|"
+        for i, field in enumerate(line):
+            l += field.center(field_sizes[i])
+            l += "|"
+
+        formatted_table_lines.append(l)
+
+    return "\n".join(formatted_table_lines)
+
+
+if __name__=="__main__":
+    # parse args
+    files = []
+    write_to_file = AUTO
+    write_to_stdout = AUTO
+    usecase_formatting = AUTO
+    verbose = AUTO
+    process_table_files = AUTO
+
+    # 1 pass (argument harvest)
+    for i in sys.argv[1:]:
+        if i.startswith("-"):
+            # записувати таблицю в файл
+            if i in ["-f", "--file"]:
+                write_to_file = YES
+            elif i in ["-nf", "--no-file"]:
+                write_to_file = NO
+
+            # виводити таблицю у стандартний вивід
+            elif i in ["-o", "--stdout"]:
+                write_to_stdout = YES
+            elif i in ["-no", "--no-stdout"]:
+                write_to_stdout = NO
+
+            # форматувати таблицю як use-case
+            elif i in ["-u", "--usecase", "--use-case"]:
+                usecase_formatting = YES
+            elif i in ["-nu", "--no-usecase", "--no-use-case"]:
+                usecase_formatting = NO
+
+            # виводити на екран додаткову інформацію
+            elif i in ["-v", "--verbose"]:
+                verbose = YES
+            elif i in ["-nv", "--no-verbose"]:
+                verbose = NO
+
+            elif i in ["-t", "--process-table"]:
+                process_table_files = YES
+            elif i in ["-nt", "--no-process-table"]:
+                process_table_files = NO
+
+    # 2 pass (filename harvest)
+    for i in sys.argv[1:]:
+        if not i.startswith("-"):
+            if i.endswith(".table") and process_table_files <= AUTO:
+                print(f"[Warning]: Excluding {i} to prevent processing of an already processed file (pass --process-table to override this behaviour)")
+            else:
+                files.append(i)
+
+    if len(files) < 1:
+        print("You need to pass at least one file as CLI argument", file=sys.stderr)
+        print("Exiting...", file=sys.stderr)
+        exit(1)
+
+    if len(files) == 1:
+        name = files[0]
+        data = open(name, encoding = "utf-8").read()
+
+        if usecase_formatting == YES:
+            if verbose == YES:
+                print(f"Force-formatting {name} as a use-case\n")
+            formatted_table_data = convert_usecase_v1(name.rsplit(".", 1)[0], data)
+        elif (name.endswith(".usecase") or name.endswith(".uc")) and usecase_formatting >= AUTO:
+            if verbose == YES:
+                print(f"Auto-detected use-case in file {name}\n")
+            formatted_table_data = convert_usecase_v1(name.rsplit(".", 1)[0], data)
+        else:
+            formatted_table_data = convert_generic_v1(data)
+
+        if write_to_stdout >= AUTO:
+            print(formatted_table_data)
+        
+        if write_to_file > AUTO:
+            open(name + ".table", 'w', encoding = "utf-8").write(formatted_table_data+"\n")
+
+        exit(0)
+
+    for no, name in enumerate(files):
+        print(f"Converting {no+1}/{len(files)}")
+
+        data = open(name, encoding = "utf-8").read()
+
+        if usecase_formatting == YES:
+            if verbose >= AUTO:
+                print(f"Force-formatting {name} as a use-case")
+            formatted_table_data = convert_usecase_v1(name.rsplit(".", 1)[0], data)
+        elif (name.endswith(".usecase") or name.endswith(".uc")) and usecase_formatting >= AUTO:
+            if verbose >= AUTO:
+                print(f"Auto-detected use-case in file {name}")
+            formatted_table_data = convert_usecase_v1(name.rsplit(".", 1)[0], data)
+        else:
+            formatted_table_data = convert_generic_v1(data)
+
+        if write_to_stdout > AUTO:
+            print(formatted_table_data)
+        
+        if write_to_file >= AUTO:
+            open(name + ".table", 'w', encoding = "utf-8").write(formatted_table_data+"\n")