OneScript

Оформление

Создание нового проекта ​

Под "проектом" мы понимаем решение, которое состоит из нескольких модулей, а не является одним временным одноразовым скриптом. Как правило, проекты используют сторонние библиотеки, имеют в своем составе тесты и т.п.

Начало работы ​

Создадим пустой каталог и откроем его в VS Code с помощью меню File -> Open Folder. Этот режим открывает папку, как каталог проекта. Это основной режим разработки проектов для 1Скрипт. В нем мы работаем с содержимым папки, как с единым проектом.

Организация корневого каталога репозитория ​

Далее, стоит определиться со структурой каталогов. Рекомендуется следующий подход:

  • Корень репозитория не содержит собственно кода и служит контейнером для всех ресурсов, связанных с проектом: кода, тестов, документации, вспомогательных инструментов
  • Код проекта, рекомендуется размещать в подпапке src. Содержимое этой папки должно быть удобно отправлять на запуск или сборку и упаковку в дистрибутив. Желательно, чтобы в ней не было ничего лишнего, что в дистрибутив попадать не должно.
  • Тесты проекта рекомендуется размещать в папке tests
  • В папке tasks рекомендуется размещать служебные скрипты, которые помогают разработчику: запускают тесты, собирают дистрибутив, еще что-то.

Также в корне проекта рекомендуется размещать манифест пакета, по которому собирается дистрибутив и отправляется в хаб пакетов

Файлы README и LICENSE лучше создать заранее. На начальном этапе разработки они не нужны, но когда проект будет готов к публикации, они напомнят о том, что их надо заполнить.

Заполнение манифеста ​

Каждый пакет, будь то приложение или библиотека для переиспользования в других проектах, должна иметь файл манифеста. Это файл с именем packagedef, который описывает состав пакета: исходники, используемые библиотеки, название и версию, действия при установке и удалении пакета.

Технически, манифест представляет собой файл скрипта и может содержать исполняемый код. Этот скрипт обрабатывается пакетным менеджером opm при сборке пакета.

Минимально необходимый манифест ​

В манифесте обязательно должны быть указаны:

  • Имя пакета
  • Версия пакета
  • Состав пакета

Как правило, также указываются зависимости, которые надо установить вместе с пакетом. На примере ниже указаны зависимости от библиотек fs и asserts.

bsl
Описание.Имя("my-package")
    .Версия("1.0.0")
    .ВерсияСреды("2.0.0")
    .ЗависитОт("fs", "1.0.0")
    .ЗависитОт("asserts", "1.3.0")
    .ВключитьФайл("packagedef")
    .ВключитьФайл("src")
    .ВключитьФайл("oscript_modules")
    .ИсполняемыйФайл("src/my-script.os");

Свойства манифеста ​

  • ВерсияСреды - минимально необходимая версия движка 1Скрипт, на которой будет работать пакет
  • ЗависитОт - указание библиотеки, которую использует наш пакет и, опционально, минимальный номер ее версии
  • ВключитьФайл - файл или каталог, который входит в состав пакета и будет включен в дистрибутив
  • ИсполняемыйФайл - если мы разрабатываем не библиотеку, а самостоятельное приложение, то здесь указываем путь к точке входа

Информация

Полный перечень настроек манифеста содержится в документации к пакетному менеджеру opm.

Структура каталогов ​

Большинство проектов не состоят из единственного файла, а разбиты на разные модули. 1Скрипт может загружать другие скрипты в виде двух сущностей: классы и модули

Класс ​

Под классом понимается новый тип в системе типов приложения. Экземпляры объектов этого типа создаются через оператор Новый.

bsl
    // подключаем функционал JSON
    #Использовать json

    Парсер = Новый ПарсерJSON(); // Тип ПарсерJSON объявлен в библиотеке

Модуль ​

Модуль это то же самое, что ОбщийМодуль в системе 1С:Предприятие. Модуль - это свойство в глобальном контексте, методы которого мы можем вызывать из языка.

bsl
    // подключаем функционал JSON
    #Использовать json

    Студент = Новый Структура("Имя,Фамилия", "Иван", "Петров");
    // Модуль "РаботаСJSON" объявлен в библиотеке и доступен благодаря директиве #Использовать
    РаботаСJSON.ЗаписатьОбъект(Студент, "C:\students.json");

Стандартный загрузчик ориентируется на структуру каталогов. Внутри каталога src рекомендуется создать папки Классы и Модули. Все файлы *.os из каталога "Классы" будут подключены как классы (и их можно создать через Новый), а файлы *.os из каталога "Модули" - как общие модули.

Информация

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

Подключение собственных модулей пакета ​

Для того, чтобы загрузчик отработал, необходимо в стартовом скрипте написать директиву импорта папки, в которой лежат подкаталоги Классы и Модули.

Например, пусть наш стартовый скрипт my-script.os лежит в каталоге src корня репозитория. Рядом с ним лежат 2 каталога Классы и Модули. В них расположены файлы классов и модулей соответственно. Для того, чтобы my-script.os увидел эти классы и модули, нам надо отправить в загрузчик "приказ" о загрузке библиотеки. Однако, в данном случае, библиотекой являемся мы сами, наш собственный проект и мы сами себя должны импортировать в пространство стартового скрипта my-script.os.

Делается это с помощью директивы Использовать, в качестве аргумента которой мы указываем текущий каталог (точку)

bsl
// Файл my-script.os
// Импортируем текущую папку (в ней лежат подпапки Классы и Модули, которые обработает загрузчик)

#Использовать "."

// Использование модуля
Сообщить(МойМодуль.КакойТоМетодМодуля())