EvGen (Event Generator)

EvGen — это инструмент для генерации кода событий аналитики для различных платформ. Он позволяет создать единое описание событий в YAML-формате и автоматически генерировать код на разных языках программирования, а также документацию в различных форматах.

Использование

Для работы нужны Node.js и pnpm.

pnpm install
pnpm evgen -e events -c evgen.yaml

Поддерживаемые языки

• Kotlin
• Java
• Swift
• TypeScript
• Dart
• C#

Содержание

• Основные концепции
• Конфигурационный файл evgen.yaml
• Файл событий events.yaml
• Типы данных
• Глобальные типы (.GlobalTypes)
• Интерфейсы
• Платформозависимые параметры
• Шаблоны
• Примеры использования
• Логика работы

Основные концепции

EvGen работает с двумя основными параметрами:

1. events(или events.yaml) - yaml-файл или папка с yaml-файлами с событиями
2. evgen.yaml - конфигурация генерации кода и документации

Инструмент генерирует:

• Код для различных платформ
• Документацию в форматах Markdown, TXT, YAML
• Проверяет совместимость событий с интерфейсами

Конфигурационный файл evgen.yaml

Основная структура

code:
  # Конфигурации для генерации кода
  ConfigName1:
    platform: string          # Название платформы
    output_dir: string         # Папка для генерируемого кода
    language: string           # Язык программирования
    class_name: string         # Имя генерируемого класса
    only_last_version: boolean # Генерировать только последние версии (опционально)
    param_name_case: string    # Стиль именования параметров (опционально)
    template_dir: string       # Путь к пользовательским шаблонам (опционально)
    disable_sending_meta: boolean # Отключить _meta для этой платформы (опционально)
    meta_to_send: array           # Какие поля включить в _meta: ['event', 'interfaces'] (опционально)

doc:
  # Конфигурации для генерации документации
  DocName1:
    extension: string          # Расширение файлов (md, txt, yaml)
    output_dir: string         # Папка для документации
    template_dir: string       # Путь к пользовательским шаблонам (опционально)
    tag: string               # Фильтр по тегам (опционально)

options:
  keepParametersOrder: boolean # Сохранять порядок параметров в событиях согласно YAML
  disable_sending_meta: boolean # Отключить добавление _meta атрибута в событиях
  meta_to_send: array           # Какие поля включить в _meta: ['event', 'interfaces']

Поддерживаемые языки

• kotlin - Kotlin для Android
• java - Java для Android
• swift - Swift для iOS
• type_script - TypeScript для веб-платформ
• dart - Dart для Flutter
• c_sharp - C# для Unity

Пример конфигурации

code:
  AndroidKotlin:
    platform: 'Android'
    output_dir: 'android_kotlin'
    language: 'kotlin'
    class_name: 'EvgenAnalytics'
    only_last_version: true
    param_name_case: 'camelCase'

  iOSSwift:
    platform: 'iOS'
    output_dir: 'ios_swift'
    language: 'swift'
    class_name: 'EvgenAnalytics'

doc:
  Markdown:
    extension: 'md'
    output_dir: 'md_doc'
  
  Txt:
    extension: 'txt' 
    output_dir: 'txt_doc'

options:
  keepParametersOrder: true

Опции конфигурации

keepParametersOrder

Сохраняет порядок параметров в событиях согласно YAML-спецификации.

• false (по умолчанию) — параметры, включённые через _included, располагаются перед остальными (для совместимости с предыдущими версиями)
• true — порядок параметров соответствует порядку в YAML

disable_sending_meta

Отключает добавление атрибута _meta и генерацию функции makeMeta в сгенерированном коде.

• false (по умолчанию) — атрибут _meta добавляется к каждому событию с информацией о версии и интерфейсах
• true — атрибут _meta и функция makeMeta не генерируются

Эту опцию можно задать глобально в options, а также переопределить для конкретной платформы в конфигурации code. Настройка платформы имеет приоритет над глобальной.

Пример с глобальным отключением:

options:
  disable_sending_meta: true  # Отключено для всех платформ

code:
  Android:
    platform: 'Android'
    output_dir: 'android'
    language: 'kotlin'

Пример с переопределением для платформы:

options:
  disable_sending_meta: false  # Включено глобально

code:
  Android:
    platform: 'Android'
    output_dir: 'android'
    language: 'kotlin'
    disable_sending_meta: true  # Но отключено для Android

  iOS:
    platform: 'iOS'
    output_dir: 'ios'
    language: 'swift'
    # Использует глобальную настройку (false)

meta_to_send

Позволяет выборочно указать, какие поля включать в атрибут _meta. Работает только если disable_sending_meta не установлен в true.

• Массив, который может содержать значения: 'event', 'interfaces'
• По умолчанию (не указано) — включаются все поля: ['event', 'interfaces']

Доступные значения:

• 'event' — включает информацию о версии события ({ event: { version: N } })
• 'interfaces' — включает информацию об интерфейсах ({ interfaces: {...} })

Эту опцию можно задать глобально в options, а также переопределить для конкретной платформы.

Важно: disable_sending_meta: true имеет больший приоритет — если он установлен, meta_to_send игнорируется.

Пример — отправлять только версию события:

options:
  meta_to_send: ['event']  # Только версия события, без интерфейсов

code:
  Android:
    platform: 'Android'
    output_dir: 'android'
    language: 'kotlin'

Пример — разная конфигурация для разных платформ:

options:
  meta_to_send: ['event', 'interfaces']  # Полная мета для всех

code:
  Android:
    platform: 'Android'
    output_dir: 'android'
    language: 'kotlin'
    meta_to_send: ['event']  # Только версия для Android

  iOS:
    platform: 'iOS'
    output_dir: 'ios'
    language: 'swift'
    disable_sending_meta: true  # Полностью отключить _meta для iOS

Файл событий (один events.yaml в простейшем случае, но так же может быть и папка с такими файлами)

Основная структура

# Глобальные параметры (добавляются ко всем событиям)
.GlobalParams:
  parameters:
    globalParam:
      type: String
      description: "Глобальный параметр"
  description: "Глобальные параметры"

# Платформозависимые параметры (добавляются ко всем событиям платформы)
.PlatformParams:
  Android:
    description: "Параметры для Android"
    parameters:
      appVersion:
        type: String
        description: "Версия приложения"

# События
Events:
  Namespace:
    EventName:
      v1:
        description: "Описание события"
        parameters:
          param1:
            type: String
            description: "Описание параметра"
        platforms:
          Android:
            app_versions: "1.0.0"
            ticket: "https://tracker.com/TICKET-123"

# Интерфейсы
Interfaces:
  InterfaceName:
    v1:
      description: "Описание интерфейса"
      parameters:
        requiredParam:
          type: String
          description: "Обязательный параметр"

Поля события

| Поле | Тип | Обязательное | Описание | |------|-----|--------------|----------| | description | string | Да | Описание события | | parameters | object | Нет | Параметры события | | platforms | object | Да | Поддерживаемые платформы | | comment | string | Нет | Дополнительный комментарий | | interface | string/array | Нет | Интерфейсы, которым должно соответствовать событие | | namespaces | array | Нет | Дополнительные пространства имен | | force_event_name | string | Нет | Принудительное имя события | | tags | string/array | Нет | Теги для фильтрации | | meta | object | Нет | Произвольные метаданные, доступные в шаблонах (не попадают в parameters) |

Поля параметра

| Поле | Тип | Обязательное | Описание | |------|-----|--------------|----------| | type | string/object | Да | Тип данных параметра | | description | string | Нет | Описание параметра | | default_value | any | Нет | Значение по умолчанию | | abstract | boolean | Нет | Абстрактный параметр | | optional | boolean | Нет | Опциональный параметр | | element_type | string/object | Нет | Тип элементов для списков |

Поля платформы

| Поле | Тип | Обязательное | Описание | |------|-----|--------------|----------| | app_versions | string/number | Да | Версия приложения или статус | | ticket | string | Нет | Ссылка на задачу в трекере |

Специальные значения для app_versions:

• in_progress - в разработке
• not_supported - не поддерживается
• Конкретная версия (например, "1.0.0", 42)

Типы данных

Примитивные типы

parameters:
  stringParam:
    type: String
    description: "Строковый параметр"
    
  intParam:
    type: Int
    description: "Целочисленный параметр"
    
  longIntParam:
    type: "Long Int"
    description: "Длинное целое число"
    
  boolParam:
    type: Bool
    description: "Булевый параметр"
    
  doubleParam:
    type: Double
    description: "Параметр с плавающей точкой"

Перечисления (Enum)

parameters:
  # Простое перечисление
  enumParam:
    type:
      Enum:
        name: MyEnum  # Опциональное имя
        values:
          - option1
          - option2
          - option3
    description: "Перечисление"
    default_value: option1

  # Перечисление с описаниями
  enumWithDescriptions:
    type:
      Enum:
        name: PagesEnum
        values:
          - value: screen_1
            description: "Первый экран"
          - value: screen_2  
            description: "Второй экран"

  # Числовое перечисление
  enumInt:
    type:
      Enum:
        values: [1, 2, 3]

Словари (Dict)

parameters:
  # Простой словарь (String -> element_type)
  dictParam:
    type: Dict
    description: "Про