Чтение/запись параметров для скриптов OneScript

Обсудить Join the chat at https://gitter.im/EvilBeaver/oscript-library GitHub release Build Status

Описание

Библиотека проекта oscript.io для автоматизации использования различных настроек для командных приложений/скриптов OneScript.

Возможности:

  • чтение настроек из произвольных json-файлов
    • из явно заданных файлов
    • из файлов с именем по умолчанию
  • чтение настроек из иерархических json-файлов
  • чтение настроек из "вложенных" json-файлов, которые связаны ссылками
  • чтение настроек из переменных среды
  • чтение настроек из командной строки, в т.ч. с передачей нескольких файлов в одном параметре
  • одновременное использование вышеуказанных возможностей согласно приоритетам

Установка

используйте пакетный менеджер opm из стандартной поставки дистрибутива oscript.io

opm install params

После чего доступно использование модулей и классов библиотеки через #Использовать params в коде скриптов.

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

1. Вызов из командной строки

Примеры вызова:

my-app command --settings my-settings.json --options 2

или

my-app command --settings server.json;"storage.json"

или

my-app command --spec-settings-key server.json;"storage.json"

или при использовании файла по умолчанию params.json (или другого, установленного в коде продукта)

my-app command --options 1

2. Форматы json-файлов настроек

  • Иерархический файл настройки
{
    "default": {
        "--ibconnection": "/F./build/ib",
        "--db-user": "Администратор",
        "--db-pwd": "",
        "--ordinaryapp": "0"
    },

    "vanessa": {
        "--vanessasettings": "./tools/VBParams.json",
        "--workspace": ".",
        "--pathvanessa": "./tools/vanessa-behavior/vanessa-behavior.epf",
        "--additional": "/DisplayAllFunctions /L ru"
    }
}

Параметры команды (vanessa) имеют более высокий приоритет, чем настройки ключа default

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

  • Другой вариант, без явного ключа default
{
    "--ibconnection": "/F./build/ib",

    "vanessa": {
        "--vanessasettings": "./tools/VBParams.json",
    }
}
  • Плоский файл настройки
{
    "--ibconnection": "/F./build/ib",
    "--db-user": "Администратор",
    "--db-pwd": "",
    "--ordinaryapp": "0",

    "--vanessasettings": "./tools/VBParams.json",
    "--workspace": ".",
    "--pathvanessa": "./tools/vanessa-behavior/vanessa-behavior.epf",
    "--additional": "/DisplayAllFunctions /L ru"
}
  • Возможно чтение вложенных файлов (по ссылке)

    • Если в файле параметров указать имя параметра, которое начинается с ReadFile,
    • а в значении путь к файлу (в том числе относительно текущего файла),
      • то будут прочитан так же и указанный файл.
    • возможно любая вложенность
{
    "ReadFile": "main.json",
    "ReadFile.server1c": "c:\tools\settings\server1c.json",
    "ReadFile.storage": "./storage.json"
}
  • Возможно русские имена параметров
  • Возможно использование чисел и булевых параметров
{
    "таймаут": 10,
    "ИспользоватьТаймаут": true,
    "ИспользоватьТиповуюВыгрузку": false
}

или

{
    "таймаут": 10,
    "ИспользоватьТаймаут": Истина,
    "ИспользоватьТиповуюВыгрузку": Ложь
}
  • Возможно использование подстановок значений

При разработке очень желательно указывать один параметр всего единожды, в одном месте файла/файлов.

  • Например, когда изменится версия платформы 1С на сервере - нужно изменить только один параметр, а не множество файлов.
{
    "v8version": "8.3.10.2299",
    "bin": "c:/program Files (x86)/1cv8/%v8version%/bin/1cv8.exe"
}
  • Возможно использование обычных комментариев 1С
{
    // простой комментарий
    "таймаут": 10 // комментарий-продолжение строки
}

3. Переопределение параметров

В случае необходимости переопределения параметров запуска используется схема приоритетов.

Приоритет в порядке возрастания (от минимального до максимального приоритета)

  • params.json (в корне проекта)
    • явно заданный json-файл по умолчанию, явно указаннный припрограммной установке
  • --settings ../env.json (указание файла настроек вручную)
    • или другой ключ командной строки, явно указаннный при программной установке
  • явно_заданный_префикс_* (из переменных окружения)
    • по умолчанию префикс ONESCRIPT_APP_
  • ключи командной строки

Описание:

  • На первоначальном этапе читаются настройки из файла настроек, указанного в ключе команды --settings tools/vrunner.json
  • Потом, если настройка есть в переменной окружения, тогда берем из еe.
  • Если же настройка есть, как в файле json, так и в переменной окружения и непосредственно в командной строке, то берем настройку из командной строки.

Например:

  • Переопределение переменной окружения:
  1. Допустим, в файле vrunner.json указана настройка

    "--db-user":"Администратор"
    

    а нам для определенного случая надо переопределить имя пользователя, тогда можно установить переменную: set RUNNER_DBUSER=Иванов и в данный параметр будет передано значение Иванов

  2. Очистка значения после установки

    set RUNNER_DBUSER=Иванов
    set RUNNER_DBUSER=
    

    в данном случаи установлено полностью пустое значение и имя пользователя будет взято из tools/vrunner.json, если оно там есть.

  3. Установка пустого значения:

    set RUNNER_DBUSER=""
    set RUNNER_DBUSER=''
    

    Если необходимо установить в поле пустое значение, тогда указываем кавычки и в параметр --db-user будет установлена пустая строка.

  4. Переопределение через параметры командной строки.

    Любое указание параметра в командной строке имеет наивысший приоритет.

Программный интерфейс

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

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

1. Модуль ЧтениеПараметров

Используется для обычного/простого использования библиотеки в своем приложении.

Прочитать

// Выполнить основной анализ и получить финальные параметры с учетом командной строки, переменных среды, файлов настроек
//
// Параметры:
//   Парсер - <ПарсерАргументовКоманднойСтроки> - ранее инициализированный парсер со всеми настройками командной строки (из пакета cmdline)
//   Аргументы - <Массив>, необязательный - набор аргументов командной строки, 
//		Если не указан, используется штатная коллекция АргументыКоманднойСтроки
//   КлючФайлаНастроек - <Строка>, необязательный - именованный параметр командной строки, 
//		который указывает на json-файл настройки 
//		Если не указан, используется ключ "--settings"
//   ПрефиксПеременныхСреды - <Строка>, необязательный - 
//		Если не указан, используется ключ "ONESCRIPT_APP_"
//
//  Возвращаемое значение:
//   <Соответствие> - итоговые параметры
//
Функция Прочитать(Парсер, Знач Аргументы = Неопределено, 
		Знач КлючФайлаНастроек = "", Знач ПрефиксПеременныхСреды = "") Экспорт
  • Пример использования в своем скрипте
#Использовать params

Парсер = Новый ПарсерАргументовКоманднойСтроки();
Парсер.ДобавитьИменованныйПараметр("Параметр");

Параметры = ЧтениеПараметров.Прочитать(Парсер, АргументыКоманднойСтроки);

Если Параметры["Параметр"] = "Успешно" Тогда
	ЗавершитьРаботу(0);
Иначе
	ЗавершитьРаботу(1);
КонецЕсли;

Получить

// Получает значение параметра по имени ключа
// Предварительно нужно прочитать параметры с помощью метода Прочитать
//
// Параметры:
//   КлючПараметра - <Строка> - произвольный ключ
//
//  Возвращаемое значение:
//   <Любой> - значение по ключу
//
  • Дополнительные параметры настроек библиотеки:

КлючКомандыВФайлеНастроекПоУмолчанию

// Возвращает ключ по умолчанию в файле настройки для всех параметров, которые не заданы в настройке команды
//
//  Возвращаемое значение:
//   <Строка> "default"

КлючФайлаНастроек

// Возвращает ключ командной строки для файла настроек
//
//  Возвращаемое значение:
//   <Строка> "--settings"

ПрефиксПеременныхОкружения

// Возвращает префикс переменных окружения по умолчанию
//
//  Возвращаемое значение:
//   <Строка> "ONESCRIPT_APP_"

ИмяФайлаНастроекПоУмолчанию

// Возвращает имя по умолчанию для файла с настройками
//
//  Возвращаемое значение:
//   <Строка> "params.json"

ПрефиксКлючаДляЧтенияВложенногоФайлаНастроек

// Возвращает префикс ключа для чтения вложенного файла настроек
//
//  Возвращаемое значение:
//   <Строка> "ReadFile"
//

2. Класс ЧитательПараметров

Прочитать

+ метод Функция Прочитать(Парсер, Знач Аргументы = Неопределено, 
		Знач КлючФайлаНастроек = "", Знач ПрефиксПеременныхСреды = "") Экспорт
  • описание аналогично ЧтениеПараметров.Прочитать

Получить

Функция Получить(КлючПараметра) Экспорт
  • описание аналогично ЧтениеПараметров.Получить

Дополнительные методы:

УстановитьТекущийКаталогПроекта

// Установить текущий каталог проекта-клиента
//
// Параметры:
//   ПарамТекущийКаталогПроекта - <Строка> - путь каталога

ПолучитьТекущийКаталогПроекта

// Получить текущий каталог проекта-клиента
//
//  Возвращаемое значение:
//   <Строка> - путь каталога

УстановитьФайлПоУмолчанию

// Установить путь к файлу настроек по умолчанию
//
// Параметры:
//   НовыйПутьФайлаНастроек - <Строка> - путь файла

ЗагрузитьСоответствиеПеременныхОкруженияПараметрамКоманд

// Загрузить соответствие переменных окружения параметрам команд
//
// Параметры:
//   Источник - <Соответствие или ФиксированноеСоответствие> - откуда загружаем
//		ключ - имя переменной окружения
//		значение - имя соответствующего ключа/параметра настройки
//

Вывод отладочной информации

Управление выводом логов выполняется с помощью типовой для oscript-library настройки логирования через пакет logos.

Основной лог проекта имеет название oscript.lib.params.

Доступные версии пакета

В разработке

Репозиторий

https://github.com/oscript-library/params

Актуальная версия

params-1.0.0