Перейти к основному содержанию

​
API-функции Ziva

Помимо задач и очередей Ziva предоставляет набор глобальных функций. Они помогают настроить язык интерфейса, выбрать цветовую схему, оптимизировать работу на встроенных устройствах и управлять строковыми операциями.
Все функции находятся в пакете ziva. Достаточно подключить библиотеку: import "github.com/qzeleza/ziva".

​
Локализация

​
SetLanguage(lang string) string

Устанавливает активный язык интерфейса ("ru", "en", "tr", …). Возвращает фактически применённый язык (если запрошенный недоступен, вернётся значение по умолчанию). 
active := ziva.SetLanguage("ru")
fmt.Println("Текущий язык:", active)

​
SetDefaultLanguage(lang string) string

Задаёт язык, который будет использоваться до первого вызова SetLanguage. 
func init() {
    ziva.SetDefaultLanguage("ru")
}

​
CurrentLanguage() string

Возвращает код текущей локали. 
if ziva.CurrentLanguage() != "ru" {
    fmt.Println("Переключаемся на русский")
    ziva.SetLanguage("ru")
}

​
SupportedLanguages() []string

Список поддерживаемых языков. Можно использовать для выпадающего списка настроек. 
for _, code := range ziva.SupportedLanguages() {
    fmt.Println("Доступен язык:", code)
}

​
Автоконфигурация и окружение

​
AutoConfigure()

Анализирует систему и включает оптимизации (лимиты памяти, упрощённые режимы отображения) — полезно на встроенных устройствах. 
func main() {
    ziva.AutoConfigure()
    // далее ваши задачи/очереди
}

​
Is64Bit() bool

Проверяет архитектуру рантайма. Можно переключать алгоритмы в зависимости от результата. 
if !ziva.Is64Bit() {
    ziva.EnableASCIIMode()
}

​
DisableCompletionDelay()

Отключает короткую «паузу завершения», когда Ziva ненадолго удерживает последнюю задачу на экране. Полезно для CI, автотестов и сценариев, где важно мгновенно перейти к следующему шагу. 
func init() {
    // В автоматизированных сценариях задержка не нужна
    ziva.DisableCompletionDelay()
}

​
EnableEmbeddedMode()

Включает упрощённую цветовую схему и макет для терминалов с ограниченными возможностями.

​
EnableASCIIMode()

Заменяет символы псевдографики на ASCII-аналоги.

​
IsEmbeddedColorMode() bool

Показывает, активен ли в данный момент «встроенный» режим. 
if ziva.IsEmbeddedColorMode() {
    fmt.Println("Работаем в упрощённой палитре")
}

​
Управление цветами

​
SetErrorColor(message, status lipgloss.TerminalColor)

Настраивает цвета ошибок и меток статуса. 
ziva.SetErrorColor(
    lipgloss.Color("#FF6B6B"), // текст ошибки
    lipgloss.Color("#FFE66D"), // ярлык статуса
)

​
ResetErrorColors()

Возвращает цвета ошибок к значениям по умолчанию. 
ziva.ResetErrorColors()

​
SetExitMenuItemStyle(style lipgloss.Style)

Меняет стиль отображения локализованных пунктов меню «Выход» в задачах со списками. По умолчанию пункт подсвечивается бирюзовым жирным стилем (ziva.MenuActionDefaultStyle()). 
// Сделать «Выход» визуально таким же, как остальные строки меню
ziva.SetExitMenuItemStyle(ziva.MenuItemDefaultStyle())

// Настроить собственный вариант подсветки
altExit := ziva.MenuActionDefaultStyle().Foreground(lipgloss.Color("#FFB000"))
ziva.SetExitMenuItemStyle(altExit)

​
SetBackMenuItemStyle(style lipgloss.Style)

Меняет стиль отображения локализованных пунктов меню «Назад». По умолчанию используется тот же подсвеченный стиль, что и для «Выход». 
// Сделать пункт «Назад» нейтральным
ziva.SetBackMenuItemStyle(ziva.MenuItemDefaultStyle())

// Вернуть стандартную подсветку позже
ziva.ResetBackMenuItemStyle()

​
ResetExitMenuItemStyle()

Возвращает подсветку пункта «Выход» к значениям по умолчанию. 
ziva.ResetExitMenuItemStyle()

​
ResetBackMenuItemStyle()

Возвращает подсветку пункта «Назад» к значениям по умолчанию. 
ziva.ResetBackMenuItemStyle()
Возвращает бирюзовый жирный стиль для специальных пунктов меню. 
multi.WithSelectAll("Включить всё", "Убрать всё", ziva.MenuActionDefaultStyle())
Возвращает стиль, совпадающий с обычными пунктами меню (белый текст). 
multi.WithSelectAll("Включить всё", "Убрать всё", ziva.MenuItemDefaultStyle())

​
Строковые и производительные утилиты

​
RepeatEfficient(s string, count int) string

Создаёт строку повторением s — минимизирует аллокации.

​
JoinEfficient(parts []string, sep string) string

Быстро объединяет срез строк с разделителем.

​
FastConcat(parts …string) string

Соединяет несколько строк без промежуточных аллокаций.

​
CleanWhitespaceEfficient(s string) string

Схлопывает повторяющиеся пробелы и переносы строк. 
header := ziva.FastConcat(
    ziva.RepeatEfficient("=", 40), "\n",
    "ОТЧЁТ\n",
    ziva.RepeatEfficient("=", 40),
)

​
Кэш интернирования строк

​
InternString(s string) string

Возвращает общую ссылку на строку, если она уже встречалась. Удобно для повторяющихся заголовков/подписей.

​
GetCacheStats() (size, capacity int)

Статистика кэша интернированных строк.

​
ClearInternCache()

Очищает кэш — полезно при завершении работы CLI или после крупной операции. 
size, cap := ziva.GetCacheStats()
log.Printf("cache %d/%d", size, cap)

if size > cap/2 {
    ziva.ClearInternCache()
}

​
Макет и списки

​
CalculateLayoutWidth(screenWidth int) int

Подсказывает оптимальную ширину вывода с учётом отступов Ziva.

​
Валидаторы верхнего уровня

Если нужен валидатор вне фабрики DefaultValidators, используйте функции-конструкторы. 
passwordValidator := ziva.NewPasswordValidator(10)
emailValidator    := ziva.NewEmailValidator()
ipv4Validator     := ziva.NewIPv4Validator()
domainValidator   := ziva.NewDomainValidator()
textValidator     := ziva.NewTextValidator(5, 120)
Все функции возвращают объект с методами Validate и Description, поэтому их можно комбинировать с собственными проверками.

​
Комплексный пример

func configureEmbeddedCLI() {
    ziva.SetDefaultLanguage("ru")
    ziva.AutoConfigure()
    ziva.EnableEmbeddedMode()
    ziva.EnableASCIIMode()

    if !ziva.Is64Bit() {
    }

    ziva.SetErrorColor(
        lipgloss.Color("#FFD166"),
        lipgloss.Color("#EF476F"),
    )
}

​
Когда использовать эти функции

  • Перед запуском очередей. Настройка языка, автоматическая конфигурация и режимы отображения должны быть выполнены в начале программы.
  • Вспомогательные пакеты. Утилиты работы со строками удобно использовать при подготовке сообщений/шаблонов.
  • Экономия памяти. Интернирование эффективно в долгоживущих CLI, где много повторяющихся строк.
  • Переиспользование валидаторов. Фабричные функции помогают описать правила, которые не вошли в DefaultValidators.
Остальные настройки (например, цвета тем или логотип) задаются в конфигурации Mintlify или в вашем приложении вручную.