dotenv

Разбор файлов .env для OneScript: тот же файл конфигурации, что читают Docker Compose и инструменты других языков.

Конфигурация приложения хранится в файле рядом с проектом, а не в исходном коде: пароли и адреса не попадают в репозиторий, а окружения различаются одним файлом.

# .env
DB_HOST=localhost
DB_PORT=5432
DB_URL=postgres://${DB_HOST}:${DB_PORT}/шоп
SECRET="ключ с # и пробелами"

Установка

opm install dotenv

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

Загрузка в окружение процесса

#Использовать dotenv

DotEnv.Загрузить();   // читает ./.env

Сообщить(ПолучитьПеременнуюСреды("DB_URL"));   // postgres://localhost:5432/шоп

Уже установленные переменные окружения имеют приоритет: значения из файла их не затирают. Так переменные, заданные в CI или в консоли, всегда выигрывают у файла разработчика.

// Файл побеждает окружение
DotEnv.Загрузить(".env.test", Новый Структура("Перезаписывать", Истина));

// Отсутствие файла - ошибка
DotEnv.Загрузить(".env", Новый Структура("ОбязательныйФайл", Истина));

Разбор без побочных эффектов

Значения = DotEnv.Разобрать("KEY=значение");
Сообщить(Значения["KEY"]);                    // значение

// То же самое, но из файла - окружение не меняется
Настройки = DotEnv.ПрочитатьФайл("config/.env.example");

Конфигурация структурой

Конфигурация = DotEnv.ЗагрузитьВСтруктуру(".env");

Сообщить(Конфигурация.DB_HOST);

Публичный API

Модуль DotEnv

Метод	Возвращает	Описание
Загрузить(ПутьКФайлу = ".env", Параметры = Неопределено)	Соответствие	Читает файл и записывает переменные в окружение процесса
Разобрать(Текст, Параметры = Неопределено)	Соответствие	Разбирает содержимое .env, окружение не меняется
ЗагрузитьВСтруктуру(ПутьКФайлу = ".env", Параметры = Неопределено)	Структура	То же, что Загрузить, но результат - структура
ПрочитатьФайл(ПутьКФайлу, Параметры = Неопределено)	Соответствие	Читает и разбирает файл, окружение не меняется

Возвращаемое соответствие всегда содержит все разобранные переменные - в том числе те, что не попали в окружение из-за приоритета уже установленных.

Параметры

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

Свойство	Тип	По умолчанию	Назначение
Перезаписывать	Булево	Ложь	Замещать уже установленные переменные окружения
Кодировка	КодировкаТекста, Строка	UTF-8	Кодировка файла, например "windows-1251"
Подстановка	Булево	Истина	Раскрывать ссылки ${ИМЯ}
ОбязательныйФайл	Булево	Ложь	Выбрасывать исключение, если файла нет

Формат файла

# строка целиком комментарий
KEY=значение              # хвост после значения без кавычек отбрасывается
export KEY=значение       # префикс export игнорируется
EMPTY=                    # пустая строка
JSON={"foo": "bar"}       # внутренние кавычки сохраняются
SPACED   =   значение     # пробелы вокруг ключа и знака равенства не значимы
EQUALS=a=b                # значение a=b: разделителем считается первый знак равенства

DOUBLE="перенос\nстроки и решётка # внутри"
SINGLE='буквально: \n не раскрывается, ${VAR} тоже'
BACKTICK=`буквально, но с 'любыми' "кавычками" внутри`

MULTILINE="первая
вторая"

BASE=/opt
PATH=${BASE}/bin          # подстановка ранее разобранного значения
PORT=${PORT:-8080}        # значение по умолчанию
LITERAL=\${BASE}          # экранированная ссылка остаётся литералом

Ключ состоит из букв, цифр, подчёркивания, точки и дефиса. Строки без знака равенства и строки с недопустимым ключом пропускаются молча.

Подстановка ищет значение сначала среди переменных, разобранных выше в этом же файле, затем в окружении процесса. Пустое значение считается отсутствующим, поэтому ${ИМЯ:-запасное} срабатывает и для незаданной, и для пустой переменной. Внутри одинарных и обратных кавычек подстановка не выполняется.

Совместимость файла

Файл, написанный для Docker Compose или для сервиса на другом языке, разбирается здесь так же: пустые строки и комментарии пропускаются, у значений без кавычек обрезаются пробелы, внутри кавычек сохраняются, пустое значение допустимо, внутренние кавычки сохраняются, значение может занимать несколько строк, поддержаны обратные кавычки и префикс export, а уже установленная переменная окружения имеет приоритет над файлом.

Там, где распространённые реализации расходятся между собой, выбор такой:

• Escape-последовательности в двойных кавычках раскрываются шире минимума: кроме \n и \r - ещё \t, \\ и \". Нераспознанная последовательность сохраняется как есть.
• Ссылки только в фигурных скобках. Поддерживается ${ИМЯ}, но не $ИМЯ: иначе значение с $ внутри - например пароль - искажалось бы. По той же причине из двух форм умолчания поддержана только ${ИМЯ:-значение}: форма ${ИМЯ-значение} неотличима от ссылки на ключ с дефисом.
• Обратные кавычки буквальны, как одинарные: ни escape-последовательности, ни ссылки ${ИМЯ} в них не раскрываются.
• Кириллица в именах допустима. Ключ КЛЮЧ=значение разбирается, хотя привычное ограничение - [A-Za-z0-9_.-]. Файлы, укладывающиеся в это ограничение, разбираются одинаково.
• Незакрытая кавычка «съедает» следующие строки до ближайшей такой же: отличить забытую кавычку от многострочного значения невозможно.

Особенности платформы, о которых стоит знать:

• OneScript не различает переменную окружения, установленную в пустую строку, и отсутствующую. Поэтому KEY= из файла не создаёт переменную окружения, хотя в возвращаемом соответствии значение присутствует.
• Имена, недопустимые для свойства структуры, ЗагрузитьВСтруктуру приводит к допустимым: точка и дефис заменяются подчёркиванием, имя, начинающееся с цифры, получает префикс подчёркивания.

Тесты

opm install -l
oneunit execute -d ./tests

Лицензия

MIT