> ## Documentation Index
> Fetch the complete documentation index at: https://ziva.zeleza.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# API Функции

> Глобальные функции Ziva для настройки окружения, локализации и оптимизации

# API-функции Ziva

Помимо задач и очередей Ziva предоставляет набор глобальных функций. Они помогают настроить язык интерфейса, выбрать цветовую схему, оптимизировать работу на встроенных устройствах и управлять строковыми операциями.

<Info>
  Все функции находятся в пакете `ziva`. Достаточно подключить библиотеку: `import "github.com/qzeleza/ziva"`.
</Info>

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

### SetLanguage(lang string) string

Устанавливает активный язык интерфейса (`"ru"`, `"en"`, `"tr"`, ...). Возвращает фактически применённый язык (если запрошенный недоступен, вернётся значение по умолчанию).

```go theme={null}
active := ziva.SetLanguage("ru")
fmt.Println("Текущий язык:", active)
```

### SetDefaultLanguage(lang string) string

Задаёт язык, который будет использоваться до первого вызова `SetLanguage`.

```go theme={null}
func init() {
    ziva.SetDefaultLanguage("ru")
}
```

### CurrentLanguage() string

Возвращает код текущей локали.

```go theme={null}
if ziva.CurrentLanguage() != "ru" {
    fmt.Println("Переключаемся на русский")
    ziva.SetLanguage("ru")
}
```

### SupportedLanguages() \[]string

Список поддерживаемых языков. Можно использовать для выпадающего списка настроек.

```go theme={null}
for _, code := range ziva.SupportedLanguages() {
    fmt.Println("Доступен язык:", code)
}
```

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

### AutoConfigure()

Анализирует систему и включает оптимизации (лимиты памяти, упрощённые режимы отображения) — полезно на встроенных устройствах.

```go theme={null}
func main() {
    ziva.AutoConfigure()
    // далее ваши задачи/очереди
}
```

### Is64Bit() bool

Проверяет архитектуру рантайма. Можно переключать алгоритмы в зависимости от результата.

```go theme={null}
if !ziva.Is64Bit() {
    ziva.EnableASCIIMode()
}
```

### DisableCompletionDelay()

Отключает короткую «паузу завершения», когда Ziva ненадолго удерживает последнюю задачу на экране. Полезно для CI, автотестов и сценариев, где важно мгновенно перейти к следующему шагу.

```go theme={null}
func init() {
    // В автоматизированных сценариях задержка не нужна
    ziva.DisableCompletionDelay()
}
```

### EnableEmbeddedMode()

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

### EnableASCIIMode()

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

### IsEmbeddedColorMode() bool

Показывает, активен ли в данный момент «встроенный» режим.

```go theme={null}
if ziva.IsEmbeddedColorMode() {
    fmt.Println("Работаем в упрощённой палитре")
}
```

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

### SetErrorColor(message, status lipgloss.TerminalColor)

Настраивает цвета ошибок и меток статуса.

```go theme={null}
ziva.SetErrorColor(
    lipgloss.Color("#FF6B6B"), // текст ошибки
    lipgloss.Color("#FFE66D"), // ярлык статуса
)
```

### ResetErrorColors()

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

```go theme={null}
ziva.ResetErrorColors()
```

### SetExitMenuItemStyle(style lipgloss.Style)

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

```go theme={null}
// Сделать «Выход» визуально таким же, как остальные строки меню
ziva.SetExitMenuItemStyle(ziva.MenuItemDefaultStyle())

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

### SetBackMenuItemStyle(style lipgloss.Style)

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

```go theme={null}
// Сделать пункт «Назад» нейтральным
ziva.SetBackMenuItemStyle(ziva.MenuItemDefaultStyle())

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

### ResetExitMenuItemStyle()

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

```go theme={null}
ziva.ResetExitMenuItemStyle()
```

### ResetBackMenuItemStyle()

Возвращает подсветку пункта «Назад» к значениям по умолчанию.

```go theme={null}
ziva.ResetBackMenuItemStyle()
```

### MenuActionDefaultStyle() lipgloss.Style

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

```go theme={null}
multi.WithSelectAll("Включить всё", "Убрать всё", ziva.MenuActionDefaultStyle())
```

### MenuItemDefaultStyle() lipgloss.Style

Возвращает стиль, совпадающий с обычными пунктами меню (белый текст).

```go theme={null}
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

Схлопывает повторяющиеся пробелы и переносы строк.

```go theme={null}
header := ziva.FastConcat(
    ziva.RepeatEfficient("=", 40), "\n",
    "ОТЧЁТ\n",
    ziva.RepeatEfficient("=", 40),
)
```

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

### InternString(s string) string

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

### GetCacheStats() (size, capacity int)

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

### ClearInternCache()

Очищает кэш — полезно при завершении работы CLI или после крупной операции.

```go theme={null}
size, cap := ziva.GetCacheStats()
log.Printf("cache %d/%d", size, cap)

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

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

### CalculateLayoutWidth(screenWidth int) int

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

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

Если нужен валидатор вне фабрики `DefaultValidators`, используйте функции-конструкторы.

```go theme={null}
passwordValidator := ziva.NewPasswordValidator(10)
emailValidator    := ziva.NewEmailValidator()
ipv4Validator     := ziva.NewIPv4Validator()
domainValidator   := ziva.NewDomainValidator()
textValidator     := ziva.NewTextValidator(5, 120)
```

Все функции возвращают объект с методами `Validate` и `Description`, поэтому их можно комбинировать с собственными проверками.

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

```go theme={null}
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 или в вашем приложении вручную.