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

Обсудить

Описание

Библиотека проекта 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.