---
name: onescript
description: Пишет и структурирует код на OneScript (BSL без 1С). Использовать при работе с файлами .os, проектами OneScript, packagedef, opm, директивой #Использовать, классами и модулями.
---

# OneScript

Навык для написания и структурирования кода на OneScript — кроссплатформенном интерпретаторе языка 1С:Предприятие 8 без платформы 1С. Код выполняется из текстовых файлов `.os`, аналогично Python или Node.js.

## Структура модуля

Модуль — текстовый файл с расширением `.os`. Три секции (сверху вниз):

1. **Секция переменных** — `Перем ИмяПеременной;`
2. **Секция методов** — процедуры и функции
3. **Секция тела модуля** — код, выполняемый при запуске (обязательно внизу файла)

Минимальный скрипт:

```bsl
Сообщить("Привет, Мир!");
```

Процедуры и функции:

```bsl
Процедура МояПроцедура(Параметр1, Параметр2)
    // операторы
КонецПроцедуры

Функция МояФункция(Параметр1, Параметр2)
    Возврат Параметр1 + Параметр2;
КонецФункции
```

## Типы и литералы

Типизация динамическая. Примитивы: Строка, Число, Булево, Дата; специальные: Неопределено, Null.

- Число: `12345.899`
- Строка: `"Текст"`, кавычка внутри — `""`. Многострочная: новая строка начинается с `|`, пробелы до `|` отбрасываются.
- Дата: `'20250212235959'` или `'2025-02-12 23:59:59'`

## Блоки кода

Условие:

```bsl
Если Условие Тогда
    // ...
ИначеЕсли ДругоеУсловие Тогда
    // ...
Иначе
    // ...
КонецЕсли;
```

Циклы:

```bsl
Для Счетчик = 0 По 10 Цикл
    Сообщить(Счетчик);
КонецЦикла;

Для Каждого Элемент Из Массив Цикл
    Сообщить(Элемент);
КонецЦикла;

Пока Условие Цикл
    // ...
КонецЦикла;
```

Исключения:

```bsl
Попытка
    // код
Исключение
    Сообщить(ОписаниеОшибки());
    ВызватьИсключение;  // rethrow
КонецПопытки;

ВызватьИсключение "Текст ошибки";
```

## Структура проекта

Рекомендуемая структура каталогов:

- `src/` — исходный код (в дистрибутив)
- `src/Классы/` — файлы `.os`, подключаемые как классы (создание через `Новый`)
- `src/Модули/` — файлы `.os`, подключаемые как общие модули
- `tests/` — тесты
- `tasks/` — служебные скрипты (сборка, тесты)
- Корень: `packagedef` (манифест), README, LICENSE

Точка входа (например `src/main.os`) должна импортировать свой каталог:

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

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

## Манифест packagedef

В корне проекта — файл без расширения `packagedef`. Минимум: имя, версия, состав.

```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");
```

Основные свойства: `Имя`, `Версия`, `ВерсияСреды`, `ЗависитОт`, `ВключитьФайл`, `ИсполняемыйФайл`.

## Библиотеки и #Использовать

Подключение в начале модуля (до переменных):

- По имени (поиск в каталогах библиотек): `#Использовать json`, `#Использовать fs`
- По пути (относительно файла): `#Использовать "."`, `#Использовать "lib/mylib"`

Класс из библиотеки — новый тип, создаётся через `Новый ИмяКласса()`. Модуль — глобальный объект с методами: `ИмяМодуля.Метод()`.

Стандартный загрузчик: файлы из подкаталога `Классы` регистрируются как классы, из `Модули` — как модули. Имя файла (без .os) = идентификатор класса/модуля.

## OPM

- Сборка пакета из каталога с манифестом: `opm build .`
- Публикация в хаб: `opm push my-file.ospx --token ТОКЕН`
- Установка пакета: через opm или клонирование в каталог библиотек

## Дополнительно

Подробности синтаксиса, отличия от 1С (Формат/ДФ, вызов конструктора в выражении, параметризованные исключения, rethrow с ИнформацияОбОшибке) — в [reference.md](reference.md).

Документация: [oscript.io/learn](https://oscript.io/learn/).