From f8af9ef45d54ec15450a3c43ac688bebcae04935 Mon Sep 17 00:00:00 2001 From: Ivan Karlo Date: Wed, 29 Apr 2026 11:11:34 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B0=D0=BA=D1=82=D1=83=D0=B0=D0=BB?= =?UTF-8?q?=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20=D0=B4=D0=BE=D0=BA=D1=83?= =?UTF-8?q?=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D0=B8=20=D0=BF=D1=80?= =?UTF-8?q?=D0=BE=D0=B5=D0=BA=D1=82=D0=B0=20=D0=BF=D0=BE=D0=B4=20.NET=208?= =?UTF-8?q?=20=D0=B8=20=D1=84=D0=B0=D0=BA=D1=82=D0=B8=D1=87=D0=B5=D1=81?= =?UTF-8?q?=D0=BA=D1=83=D1=8E=20=D1=81=D1=82=D1=80=D1=83=D0=BA=D1=82=D1=83?= =?UTF-8?q?=D1=80=D1=83=20=D0=BA=D0=BE=D0=B4=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md / README-EN.md: убрано устаревшее упоминание .net6 (фактический таргет — net8.0), команды переведены на `dotnet msbuild`; добавлены отсутствовавшие таргеты `GatherLibrary`, `Test`, `UnitTests`, `ScriptedTests`, `PublishNuget` и параметры `NoCppCompiler`, `Configuration`; добавлены разделы «Тестирование» (с командами для модульных C# и приёмочных BSL-тестов через tests/run-bsl-tests.*) и «Документация для разработчиков» со ссылками на docs/ и CODESTYLE.md. Русская и английская версии приведены к одинаковой структуре. - docs/developer_docs.md: починена поломанная нумерация разделов (3.1–3.4, 7., 3.6–3.10 → последовательно 3.1–3.10), убран дубль заголовка в разделе про OneScript.Core, уточнены реальные пути к файлам (PreprocessingLexer.cs и LocalizedErrors.cs — в SyntaxAnalysis/; CompilerBackendSelector вместо BackendSelector; ExecutionFrame вместо Frame; ValueList/, ValueTable/, ValueTree/ как подкаталоги Collections/; актуальные классы OneScript.DebugServices и StandaloneRunner), исправлена опечатка ContextValuesMarhaller → ContextValuesMarshaller, добавлены ссылки на README.md, contexts.md, CODESTYLE.md и .github/copilot-instructions.md. - docs/contexts.md: починена битая ссылка docs/arhitecture_overview.md → docs/developer_docs.md; заголовки приведены к markdown-разметке; оглавление сделано кликабельным; дописаны обещанные в содержании, но отсутствовавшие разделы (i18n для API, Депрекейшен и едупреждения, Тестирование C# и BSL, Документация (OneScriptDocumenter), Безопасность, Чек-лист готовности). В C#-шаблонах исправлены using-и: `OneScript.Execution` вместо несуществующего `OneScript.Core.Execution`, добавлен `ScriptEngine.Machine` для IValue/ValueFactory; сверено с живыми контекстами из OneScript.StandardLibrary. --- README-EN.md | 83 ++++++++--- README.md | 84 ++++++++--- docs/contexts.md | 266 +++++++++++++++++++++++---------- docs/developer_docs.md | 330 ++++++++++++++++++++++------------------- 4 files changed, 499 insertions(+), 264 deletions(-) diff --git a/README-EN.md b/README-EN.md index 531111fc8..9c1476095 100644 --- a/README-EN.md +++ b/README-EN.md @@ -57,50 +57,97 @@ The OneScript distribution already includes a set of the most commonly used pack ## Preparation -Links to distributions are provided below, however, please note that links may change over time and their relevance is not guaranteed. You need dotnet SDK and C++ compiler, which can be downloaded from anywhere you can find. +To build the project you need: -* Install [MS BuildTools](https://visualstudio.microsoft.com/ru/thank-you-downloading-visual-studio/?sku=buildtools&rel=16), when installing enable targeting for .net6, .net4.8, install C++ compiler. +* [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) (the project's target framework is `net8.0`). +* A C++ compiler — only required to build the native bridge `ScriptEngine.NativeApi` (support for native add-ins compatible with the 1C NativeApi). On Windows the easiest way to get one is to install [MS Build Tools](https://visualstudio.microsoft.com/visual-studio-build-tools/) or Visual Studio with the "Desktop development with C++" workload. If a C++ compiler is not available, see the `NoCppCompiler` parameter below. + +> Distribution links may change over time, their relevance is not guaranteed. ## Build -Launch Developer Command Prompt (will appear in the Start menu after installing MSBuildTools or Visual Studio). Navigate to the OneScript repository directory. The following are commands in the Developer Command Prompt console. -Build is performed using msbuild. Targets: +The build is driven by MSBuild via the `Build.csproj` script in the repository root. Commands can be run with `msbuild` (Developer Command Prompt installed together with MS Build Tools/Visual Studio) or with `dotnet msbuild` (cross-platform). + +Main targets: -* CleanAll - clean previous build results -* BuildAll - prepare files for distribution -* MakeCPP;MakeFDD;MakeSCD;BuildDebugger - separate build targets for preparing different types of distributions -* PrepareDistributionFiles - build full distribution packages (including libraries) -* PackDistributions - prepare ZIP archives for distribution -* CreateNuget - create packages for publishing to NuGet +* `CleanAll` — clean previous build results; +* `BuildAll` — build binary files for distribution (FDD, SCD, debugger; native components are also built when a C++ compiler is available); +* `MakeCPP`, `MakeFDD`, `MakeSCD`, `BuildDebugger` — individual targets that build specific parts of the distribution; +* `GatherLibrary` — download and stage the base set of libraries (`opm`, `asserts`, `logos`, `fs`, `tempfiles`, `cli`); +* `PrepareDistributionFiles` — build full distribution contents (including libraries and documentation); +* `PackDistributions` — pack the distribution contents into ZIP archives for all supported platforms; +* `BuildDocumentation` — generate the platform reference (markdown + json); +* `CreateNuget` / `PublishNuget` — build and publish NuGet packages; +* `Test` (`UnitTests`, `ScriptedTests`) — run unit and acceptance (BSL) tests. **Build parameters** -* VersionPrefix - release number prefix, its main part, for example, 2.0.0 -* VersionSuffix - version suffix, which usually acts as an arbitrary versioning suffix according to semver, for example, beta-786 (optional) -* NoCppCompiler - if True - C++ compiler is not installed, C++ components (NativeApi support) will not be added to the build +* `VersionPrefix` — main part of the release number, for example `2.0.0` (defaults to `2.0.0`); +* `VersionSuffix` — optional SemVer suffix, for example `beta-786`; +* `NoCppCompiler` — when set to `True`, native C++ components (NativeApi) are not built and not included in the distribution (use it when no C++ compiler is installed); +* `Configuration` — build configuration, defaults to `Release`. For a debug build on Linux use `LinuxDebug`. -All distribution files will be placed in the `built` directory at the root of the 1Script repository +All build artifacts are placed in the `built` directory at the repository root. ### Building distribution contents in a separate directory ```bat -msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles +dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles ``` ### Building with manual version specification ```bat -msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0 +dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0 ``` ### Building ZIP distributions ```bat -msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223 +dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223 +``` + +### Building without C++ components (no NativeApi) + +```bat +dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:NoCppCompiler=True ``` ### Documentation generation ```bat -msbuild Build.csproj /t:BuildDocumentation +dotnet msbuild Build.csproj /t:BuildDocumentation ``` + +# Testing + +The project has two layers of tests: + +* **C# unit tests** — located in `src/Tests/*` (xUnit/NUnit). Run them via `dotnet test` in the corresponding test project directory or all at once: + ```bat + dotnet msbuild Build.csproj /t:UnitTests + ``` +* **BSL acceptance tests** — located in the `tests/` directory and executed by `testrunner.os` against a freshly built `oscript`. The repository includes wrapper scripts: + ```bat + rem Windows + tests\run-bsl-tests.cmd src\oscript\bin\Debug\net8.0\oscript.exe + ``` + + ```bash + # Linux/macOS + tests/run-bsl-tests.sh src/oscript/bin/Debug/net8.0/oscript + ``` + + Before running the acceptance tests, build `oscript`: + ```bat + dotnet build src/oscript/oscript.csproj + ``` + +# Developer documentation + +If you want to contribute to the project, take a look at the additional documents in the [`docs/`](docs/) directory: + +* [`docs/developer_docs.md`](docs/developer_docs.md) — project architecture, solution layout and guided tour of the source code. +* [`docs/contexts.md`](docs/contexts.md) — a practical guide to adding BSL contexts, methods, properties and global functions. +* [`CODESTYLE.md`](CODESTYLE.md) — C# code style requirements. + diff --git a/README.md b/README.md index 959253f91..95779d67d 100644 --- a/README.md +++ b/README.md @@ -57,50 +57,96 @@ OneScript позволяет создавать и выполнять текст ## Подготовка -Ниже приведены ссылки на дистрибутивы, однако, учтите, что ссылки могут меняться со временем и их актуальность не гарантируется. Нужен dotnet SDK и компилятор C++, скачать можно из любого места, которое нагуглится. +Для сборки потребуется: -* Установить [MS BuildTools](https://visualstudio.microsoft.com/ru/thank-you-downloading-visual-studio/?sku=buildtools&rel=16), при установке включить таргетинг на .net6, .net4.8, установить компилятор C++. +* [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) (целевой фреймворк проекта — `net8.0`). +* Компилятор C++ — нужен только для сборки нативного моста `ScriptEngine.NativeApi` (поддержка внешних компонент стандарта 1С NativeApi). На Windows проще всего получить его, поставив [MS Build Tools](https://visualstudio.microsoft.com/visual-studio-build-tools/) или Visual Studio с компонентом «Разработка классических приложений на C++». Если C++ компилятора нет, см. параметр `NoCppCompiler` ниже. + +> Ссылки на дистрибутивы могут меняться со временем, их актуальность не гарантируется. ## Сборка -Запустить Developer Command Prompt (появится в меню Пуск после установки MSBuildTools или Visual Studio). Перейти в каталог репозитория OneScript. Далее приведены команды в консоли Developer Command Prompt -Сборка выполняется с помощью msbuild. Таргеты: +Сборка выполняется с помощью MSBuild и сценария `Build.csproj` в корне репозитория. Команды можно запускать как через `msbuild` (Developer Command Prompt после установки MS Build Tools/Visual Studio), так и через `dotnet msbuild` (кросс-платформенно). + +Основные таргеты: -* CleanAll - очистка результатов предыдущих сборок -* BuildAll - подготовить файлы для поставки -* MakeCPP;MakeFDD;MakeSCD;BuildDebugger - отдельные таргеты сборки для подготовки разных типов поставки -* PrepareDistributionFiles - сборка полных пакетов поставки (включая библиотеки) -* PackDistributions - подготовка ZIP архивов поставки -* CreateNuget - создать пакеты для публикации в NuGet +* `CleanAll` — очистка результатов предыдущих сборок; +* `BuildAll` — собрать бинарные файлы для поставки (FDD, SCD, отладчик; при наличии C++ — нативные компоненты); +* `MakeCPP`, `MakeFDD`, `MakeSCD`, `BuildDebugger` — отдельные таргеты сборки разных частей поставки; +* `GatherLibrary` — скачать и сложить базовый набор библиотек (`opm`, `asserts`, `logos`, `fs`, `tempfiles`, `cli`); +* `PrepareDistributionFiles` — собрать полные содержимые дистрибутивов (вкл. библиотеки и документацию); +* `PackDistributions` — упаковать содержимое в ZIP-архивы под все поддерживаемые платформы; +* `BuildDocumentation` — сгенерировать справку по платформе (markdown + json); +* `CreateNuget` / `PublishNuget` — собрать и опубликовать NuGet-пакеты; +* `Test` (`UnitTests`, `ScriptedTests`) — прогнать модульные и приёмочные (BSL) тесты. **Параметры сборки** -* VersionPrefix - префикс номера релиза, его основная часть, например, 2.0.0 -* VersionSuffix - суффикс номера, который обычно выступает в качестве произвольного суффикса версионирования по semver, например, beta-786 (необязателен) -* NoCppCompiler - если True - не установлен компилятор C++, в сборку не будут добавлены компоненты C++ (поддержка NativeApi) +* `VersionPrefix` — основная часть номера релиза, например `2.0.0` (по умолчанию `2.0.0`); +* `VersionSuffix` — необязательный suffix по SemVer, например `beta-786`; +* `NoCppCompiler` — если `True`, нативные компоненты C++ (NativeApi) не собираются и не включаются в дистрибутив (используйте, если компилятор C++ не установлен); +* `Configuration` — конфигурация сборки, по умолчанию `Release`. Для отладочной сборки на Linux используется `LinuxDebug`. -Все поставляемые файлы будут размещены в каталоге `built` в корне репозитория 1Script +Все артефакты сборки размещаются в каталоге `built` в корне репозитория. ### Сборка содержимого дистрибутивов в отдельном каталоге ```bat -msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles +dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles ``` ### Сборка с ручным указанием версии ```bat -msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0 +dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0 ``` ### Сборка ZIP-дистрибутивов ```bat -msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223 +dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223 +``` + +### Сборка без C++-компонент (без NativeApi) + +```bat +dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:NoCppCompiler=True ``` ### Генерация документации ```bat -msbuild Build.csproj /t:BuildDocumentation -``` \ No newline at end of file +dotnet msbuild Build.csproj /t:BuildDocumentation +``` + +# Тестирование + +В проекте есть два уровня тестов: + +* **Модульные тесты на C#** — расположены в `src/Tests/*` (xUnit/NUnit), запускаются через `dotnet test` в каталоге соответствующего тестового проекта или одной командой: + ```bat + dotnet msbuild Build.csproj /t:UnitTests + ``` +* **Приёмочные тесты на BSL** — расположены в каталоге `tests/` и запускаются через `testrunner.os` на свежесобранном `oscript`. Для удобства в репозитории есть скрипты-обёртки: + ```bat + rem Windows + tests\run-bsl-tests.cmd src\oscript\bin\Debug\net8.0\oscript.exe + ``` + + ```bash + # Linux/macOS + tests/run-bsl-tests.sh src/oscript/bin/Debug/net8.0/oscript + ``` + + Перед запуском приёмочных тестов нужно собрать `oscript`: + ```bat + dotnet build src/oscript/oscript.csproj + ``` + +# Документация для разработчиков + +Если вы хотите контрибьютить в проект, познакомьтесь с дополнительными документами в каталоге [`docs/`](docs/): + +* [`docs/developer_docs.md`](docs/developer_docs.md) — архитектура проекта, состав решения и навигация по исходному коду. +* [`docs/contexts.md`](docs/contexts.md) — практическое руководство по добавлению BSL-контекстов, методов, свойств и глобальных функций. +* [`CODESTYLE.md`](CODESTYLE.md) — требования к стилю кода на C#. diff --git a/docs/contexts.md b/docs/contexts.md index 69b55c98f..f82c05f9e 100644 --- a/docs/contexts.md +++ b/docs/contexts.md @@ -1,52 +1,51 @@ # BSL-контексты и глобальные методы: руководство разработчика -Этот документ — практическая инструкция по добавлению в OneScript новых BSL‑контекстов (классов), методов и свойств, а также глобальных методов. Здесь собраны готовые сниппеты, чек‑лист и ссылки на ключевые места в исходниках. +Этот документ — практическая инструкция по добавлению в OneScript новых BSL-контекстов (классов), методов и свойств, а также глобальных методов. Здесь собраны готовые сниппеты, чек-лист и ссылки на ключевые места в исходниках. -См. также «Архитектурный обзор»: docs/arhitecture_overview.md (карта компонентов и «куда лезть»). +См. также [`docs/developer_docs.md`](developer_docs.md) — карта компонентов и «куда лезть» при доработках. -Содержание +## Содержание -- Что такое BSL‑контекст -- Добавление нового BSL‑класса (контекста) -- Добавление свойства -- Добавление метода -- Создание глобального контекста и глобальных методов -- Регистрация библиотек и package‑loader.os -- i18n для API (двуязычные имена) -- Депрекейшен и предупреждения -- Тестирование (C# и BSL) -- Документация (OneScriptDocumenter) -- Безопасность -- Чек‑лист готовности +1. [Что такое BSL-контекст](#1-что-такое-bsl-контекст) +2. [Добавление нового BSL-класса (контекста)](#2-добавление-нового-bsl-класса-контекста) +3. [Добавление свойства](#3-добавление-свойства) +4. [Добавление метода](#4-добавление-метода) +5. [Создание глобального контекста и глобальных методов](#5-создание-глобального-контекста-и-глобальных-методов) +6. [Регистрация библиотек и package-loader.os](#6-регистрация-библиотек-и-package-loaderos) +7. [i18n для API (двуязычные имена)](#7-i18n-для-api-двуязычные-имена) +8. [Депрекейшен и предупреждения](#8-депрекейшен-и-предупреждения) +9. [Тестирование (C# и BSL)](#9-тестирование-c-и-bsl) +10. [Документация (OneScriptDocumenter)](#10-документация-onescriptdocumenter) +11. [Безопасность](#11-безопасность) +12. [Чек-лист готовности](#12-чек-лист-готовности) -1. Что такое BSL‑контекст +## 1. Что такое BSL-контекст -- Контекст — это .NET‑класс, методы/свойства которого доступны из BSL. Экземпляр контекста может создаваться оператором Новый (класс‑контекст) или предоставляться глобально (глобальный контекст). +- Контекст — это .NET-класс, методы и свойства которого доступны из BSL. Экземпляр контекста может создаваться оператором `Новый` (класс-контекст) или предоставляться глобально (глобальный контекст). - Отражение и метаданные описываются атрибутами: - - [ContextClass("РусИмя", "EngName")] - - [ContextMethod("РусИмя", "EngName")] - - [ContextProperty("РусИмя", "EngName", CanRead = true, CanWrite = false, ...)] - - [GlobalContext(...)] для глобального контекста - - [ScriptConstructor] для создания объектов через Новый -- Двуязычные имена обязательны: все элементы публичного API должны иметь пару имен Рус/Eng. + - `[ContextClass("РусИмя", "EngName")]` — класс-контекст; + - `[ContextMethod("РусИмя", "EngName")]` — метод (процедура/функция); + - `[ContextProperty("РусИмя", "EngName", CanRead = true, CanWrite = false, ...)]` — свойство; + - `[GlobalContext(...)]` — глобальный контекст; + - `[ScriptConstructor]` — фабричный метод для создания объектов через `Новый`. +- Двуязычные имена обязательны: все элементы публичного API должны иметь пару имён Рус/Eng. -Где в коде смотреть +Где в коде смотреть: -- Атрибуты и метаданные: src/OneScript.Core/Contexts/* -- Базовые помощники контекстов: src/ScriptEngine/Machine/Contexts/* -- Глобальные контексты (база): GlobalContextBase — src/ScriptEngine/Machine/Contexts/GlobalContextBase.cs +- Атрибуты и метаданные: `src/OneScript.Core/Contexts/*`. +- Базовые помощники контекстов: `src/ScriptEngine/Machine/Contexts/*`. +- База глобальных контекстов: `GlobalContextBase` — `src/ScriptEngine/Machine/Contexts/GlobalContextBase.cs`. -2. Добавление нового BSL‑класса (контекста) +## 2. Добавление нового BSL-класса (контекста) -Минимальный шаблон +### Минимальный шаблон ```csharp -using OneScript.Core.Contexts; -using OneScript.Core.Types; -using OneScript.Core.Values; -using ScriptEngine; +using OneScript.Contexts; // ContextClass, ContextMethod, ContextProperty, ScriptConstructor +using OneScript.Execution; // IBslProcess +using OneScript.Types; // TypeActivationContext +using ScriptEngine.Machine; // IValue, ValueFactory using ScriptEngine.Machine.Contexts; // AutoContext -using OneScript.Core.Execution; // IBslProcess [ContextClass("ПримерКласс", "SampleClass")] public class SampleClass : AutoContext @@ -60,7 +59,7 @@ public class SampleClass : AutoContext [ContextProperty("Версия", "Version", CanWrite = false)] public IValue Version => ValueFactory.Create("1.0"); - // Процедура с доступом к bsl-процессу (возможность запускать свой код bsl из кода c#) + // Процедура с доступом к bsl-процессу (можно запускать BSL-код из C#) [ContextMethod("Сообщить", "Message")] public void Message(IBslProcess process, IValue text) { @@ -78,22 +77,20 @@ public class SampleClass : AutoContext } ``` -Комментарии к шаблону +### Комментарии к шаблону -- Наследуемся от AutoContext — это стандартная база для классов‑контекстов. -- [ScriptConstructor] — статический фабричный метод, возможно, принимающий TypeActivationContext. Можно объявить несколько перегрузок. -- IBslProcess можно внедрять первым параметром метода, чтобы получить доступ к сервисам/окружению выполнения. +- Наследуемся от `AutoContext` — это стандартная база для классов-контекстов. +- `[ScriptConstructor]` — статический фабричный метод, возможно принимающий `TypeActivationContext`. Можно объявить несколько перегрузок для разных сигнатур конструктора. +- `IBslProcess` можно внедрять первым параметром метода, чтобы получить доступ к сервисам/окружению выполнения. - Возвраты: - - Процедура — метод без возвращаемого значения (void). - - Функция — возвращает IValue или конвертируемый тип C# (см. ContextValuesMarshaller). + - **Процедура** — метод без возвращаемого значения (`void`). + - **Функция** — возвращает `IValue` или конвертируемый тип C# (см. `ContextValuesMarshaller`). -Регистрация в движке +### Регистрация в движке -- При старте ContextDiscoverer просканирует сборку и автоматически зарегистрирует в движке все классы, помеченные атрибутами ContextClass, GlobalContext, EnumerationType +При старте `ContextDiscoverer` (`src/ScriptEngine/Machine/Contexts/ContextDiscoverer.cs`) сканирует подключённые сборки и автоматически регистрирует все классы, помеченные атрибутами `ContextClass`, `GlobalContext` и `EnumerationType`. Дополнительная ручная регистрация при этом не требуется. -3. Добавление свойства - -Шаблон +## 3. Добавление свойства ```csharp [ContextProperty("Порог", "Threshold", CanRead = true, CanWrite = true)] @@ -102,44 +99,44 @@ public IValue Threshold get => ValueFactory.Create(_threshold); set => _threshold = value.AsNumber(); } + private decimal _threshold = 0m; ``` -Заметки - -- CanRead/CanWrite управляют доступностью геттера/сеттера из BSL, если не указаны, берутся наличия стандартных get/set у свойства. -- Маршаллинг значений свойства автоматический. +Заметки: +- `CanRead`/`CanWrite` управляют доступностью геттера и сеттера из BSL. Если параметры не указаны, используется наличие стандартных `get`/`set` у свойства. +- Маршаллинг значения свойства автоматический через `ContextValuesMarshaller`. +- Для значений, которые часто читаются и не меняются, имеет смысл вычислять и кешировать `IValue` в поле, а не пересоздавать его в геттере. -4. Добавление метода - -Шаблон процедуры и функции +## 4. Добавление метода ```csharp -// Процедура, изменяющая параметр по ссылке +// Функция, возвращающая удвоенное значение [ContextMethod("УдвоитьЧисло", "DoubleNumber")] public int DoubleNumber(int number) { - var doubled = number * 2; - return doubled; + return number * 2; } ``` -Значения параметров и результат метода будут автоматически сконвертированы из типов C# в тиаы bsl. +Значения параметров и результат метода будут автоматически сконвертированы из типов C# в типы BSL. -Заметки +Заметки: -- Для передачи аргумента по ссылке: используйте тип IVariable — в него можно присвоить новое значение через .Value. -- По значению: используйте типы C# напрямую, если они поддерживаются маршаллером, или IValue. +- **Передача аргумента по ссылке** — используйте тип `IVariable` в сигнатуре метода. В него можно присвоить новое значение через `.Value`. +- **Передача по значению** — используйте типы C# напрямую, если они поддерживаются маршаллером, или `IValue`. +- **Необязательные параметры** — задавайте через значения по умолчанию C# (`int count = 0`, `string mode = null`). Эти значения будут видны вызывающему коду BSL. +- **Перегрузки** — поддерживаются: можно объявить несколько методов с одним и тем же `ContextMethod`-именем, но с разными сигнатурами. -5. Создание глобального контекста и глобальных методов +## 5. Создание глобального контекста и глобальных методов -Глобальный контекст +### Глобальный контекст ```csharp -using OneScript.Core.Contexts; -using OneScript.Core.Values; -using ScriptEngine.Machine.Contexts; +using OneScript.Contexts; // GlobalContext, ContextMethod, IAttachableContext +using ScriptEngine.Machine; // IValue, ValueFactory +using ScriptEngine.Machine.Contexts; // GlobalContextBase [GlobalContext(Category = "Мои функции")] public class MyGlobals : GlobalContextBase @@ -155,20 +152,137 @@ public class MyGlobals : GlobalContextBase } ``` -Заметки +Заметки: -- По умолчанию глобальные контексты регистрируются автоматически (ManualRegistration = false). Достаточно, чтобы сборка была добавлена в окружение. -- Вручную можно внедрить через HostedScriptEngine.InjectObject или IRuntimeEnvironment.InjectObject. +- По умолчанию глобальные контексты регистрируются автоматически (`ManualRegistration = false`). Достаточно, чтобы сборка с контекстом была подключена к окружению. +- При необходимости можно внедрить контекст вручную через `HostedScriptEngine.InjectObject` или `IRuntimeEnvironment.InjectObject`. -Добавление метода в существующий глобальный контекст +### Добавление метода в существующий глобальный контекст -- Например, StandardGlobalContext: добавьте [ContextMethod] в соответствующий класс и реализуйте логику. +- Например, в `StandardGlobalContext` (`src/OneScript.StandardLibrary/StandardGlobalContext.cs`): добавьте `[ContextMethod]` в соответствующий класс и реализуйте логику. - Внимание: изменение публичного API стандартной библиотеки требует обсуждения с мэйнтейнерами. -6. Регистрация библиотек и package‑loader.os +## 6. Регистрация библиотек и package-loader.os + +- `HostedScript` ищет библиотеку и вызывает `package-loader.os` (дефолтный или кастомный из самой библиотеки). +- Основные операции загрузчика (см. `src/ScriptEngine.HostedScript/LibraryLoader.cs`): + - `ДобавитьКласс`/`AddClass("path", "ИмяКласса")` — регистрирует новый BSL-тип; + - `ДобавитьМодуль`/`AddModule("path", "ИмяМодуля")` — подключает модуль как глобальный; + - `ДобавитьМакет`/`AddTemplate` — регистрирует шаблон. +- Для отладки разрешения зависимостей полезно посмотреть `FileSystemDependencyResolver.cs` — порядок поиска и защита от циклических зависимостей. + +## 7. i18n для API (двуязычные имена) + +- Каждый публичный элемент API (класс, метод, свойство, перечисление, элемент перечисления) должен иметь две формы имени — русскую и английскую — задаваемые в атрибутах: + + ```csharp + [ContextClass("ИмяНаРусском", "EnglishName")] + [ContextMethod("ВыполнитьДействие", "Perform")] + [ContextProperty("Размер", "Size")] + ``` + +- Имена должны быть согласованы с уже существующим API: смотрите `OneScript.StandardLibrary` и сгенерированный справочник (см. раздел [Документация](#10-документация-onescriptdocumenter)). +- Имена параметров и текст исключений переводить не нужно — они остаются на одном языке (как правило, на русском, в соответствии с привычным стилем 1С). +- Категории глобальных контекстов (`GlobalContext(Category = "...")`) тоже желательно делать осмысленными — они используются в подсказках и группировках в редакторах. + +## 8. Депрекейшен и предупреждения + +Для обозначения устаревших имён, классов, методов и свойств используется атрибут `DeprecatedNameAttribute` (`src/OneScript.Core/Contexts/DeprecatedNameAttribute.cs`): + +```csharp +[ContextMethod("НоваяФункция", "NewFunc")] +[DeprecatedName("СтараяФункция")] +[DeprecatedName("OldFunc")] +public IValue NewFunc() { /* ... */ } +``` + +- Аргумент `name` — устаревший псевдоним. При обращении к нему из BSL вызов всё ещё работает, но в системный лог пишется предупреждение. +- Параметр `throwOnUse: true` превращает использование устаревшего имени в ошибку выполнения. Применяется, когда нужно жёстко удалить старый псевдоним. +- Атрибут можно ставить и на сам элемент (`[DeprecatedName("OldName")]` рядом с `[ContextMethod]`), и на отдельные перечисления/типы. +- Для классов, которые сами по себе устарели, реализуйте интерфейс `ISupportsDeprecation` (`src/OneScript.Core/Contexts/ISupportsDeprecation.cs`) — возвращайте `IsDeprecated = true`. Тогда система сможет логировать факт использования такого типа. + +Изменение и удаление публичных имён без депрекейшена считается ломающим изменением — старайтесь сначала пройти этап с предупреждением. + +## 9. Тестирование (C# и BSL) + +В проекте принято покрывать новые контексты двумя слоями тестов. + +### Модульные тесты (xUnit/NUnit) + +- Тесты лежат в `src/Tests/*` (xUnit/NUnit). +- Для контекстов из `OneScript.StandardLibrary` подходит проект `src/Tests/OneScript.StandardLibrary.Tests`. Там же есть пример проверки атрибута `DeprecatedName` (`ObsoleteEnumTest.cs`). +- Для проверки кода, который должен компилироваться, используйте инфраструктуру из `src/Tests/OneScript.Dynamic.Tests` (`CompilerTestBase`, `CompileHelper`). +- Запуск: `dotnet test` в каталоге соответствующего проекта или одной командой: + + ```bat + dotnet msbuild Build.csproj /t:UnitTests + ``` + +### Приёмочные тесты на BSL + +- Поведенческие сценарии лежат в каталоге `tests/*.os` и совместимы с форматом xUnitFor1C. +- Для нового контекста создайте файл `tests/<ваш-контекст>.os` со списком тестов. Минимальный шаблон: + + ```bsl + Перем юТест; + + Функция ПолучитьСписокТестов(ЮнитТестирование) Экспорт + юТест = ЮнитТестирование; + ВсеТесты = Новый Массив; + ВсеТесты.Добавить("ТестДолжен_СоздатьЭкземпляр"); + Возврат ВсеТесты; + КонецФункции + + Процедура ТестДолжен_СоздатьЭкземпляр() Экспорт + Объект = Новый ПримерКласс(); + юТест.ПроверитьРавенство("1.0", Объект.Версия); + КонецПроцедуры + ``` + +- Запуск всего набора тестов через свежесобранный `oscript` (см. [`README.md`](../README.md), раздел «Тестирование»): + + ```bat + rem Windows + dotnet build src/oscript/oscript.csproj + tests\run-bsl-tests.cmd src\oscript\bin\Debug\net8.0\oscript.exe + ``` + + ```bash + # Linux/macOS + dotnet build src/oscript/oscript.csproj + tests/run-bsl-tests.sh src/oscript/bin/Debug/net8.0/oscript + ``` + +- Запуск одного теста: `<путь к oscript> tests/testrunner.os -run tests/<имя файла>.os`. + +## 10. Документация (OneScriptDocumenter) + +- Утилита `OneScriptDocumenter` (см. `src/OneScriptDocumenter`) формирует справку по платформе из XML-документации сборок и оглавления `default_toc.json`. +- Чтобы ваш контекст попал в справку: + - включите для проекта генерацию XML-документации (это сделано во всех публичных проектах через `oscommon.targets`); + - снабдите класс/методы/свойства XML-комментариями ``, ``, ``, `` — они извлекаются документатором; + - при необходимости — отредактируйте оглавление `src/OneScriptDocumenter/default_toc.json`, чтобы новый раздел появился в нужном месте. +- Сгенерировать локально: `dotnet msbuild Build.csproj /t:BuildDocumentation`. Результат окажется в `built/docs/` (markdown + json). + +## 11. Безопасность + +- Не выполняйте произвольный код, поступивший «снаружи». Если контекст исполняет BSL, который пришёл от пользователя, делайте это только через явные точки расширения (`IBslProcess.Run`/`Eval`), осознавая, какие глобальные имена и контексты доступны. +- При работе с файловой системой и сетью валидируйте пути и URL, проверяйте кодировки и таймауты. Для долгих операций предусматривайте отмену. +- Не логируйте секреты (пароли, токены, заголовки `Authorization`) в открытом виде. +- Не доверяйте внешним десериализаторам: для JSON/XML используйте уже существующие в `OneScript.StandardLibrary` обёртки и не добавляйте отключение защит «по умолчанию». +- Если ваш контекст представляет собой обёртку поверх системного API, явно указывайте в XML-документации, какие побочные эффекты возможны (запись на диск, запуск процессов, сетевые вызовы). +- При добавлении опасных по умолчанию операций предусматривайте явный «согласный» флаг в API, а не включайте их «втихую». + +## 12. Чек-лист готовности + +Перед открытием Pull Request убедитесь, что выполнены пункты: -- HostedScript ищет библиотеку и вызывает package‑loader.os (дефолтный или кастомный). -- Основные операции загрузчика (см. src/ScriptEngine.HostedScript/LibraryLoader.cs): - - ДобавитьКласс/AddClass("path", "ИмяКласса") — регистрирует новый BSL‑тип; - - ДобавитьМодуль/AddModule("path", "ИмяМодуля") — подключает модуль как глобальный; - - ДобавитьМакет/AddTemplate — регистрирует шаблон. \ No newline at end of file +- [ ] У всех публичных элементов API заданы оба имени — русское и английское. +- [ ] Класс/метод/свойство снабжены XML-комментариями (``, ``, ``). +- [ ] Параметры с разумными значениями по умолчанию указаны через дефолты C#, а не через перегрузки-обёртки. +- [ ] Если переименовываете существующее имя — добавлен `DeprecatedName` со старым псевдонимом. +- [ ] Добавлены модульные тесты на C# и/или приёмочные тесты на BSL. +- [ ] Все тесты проходят локально (`dotnet msbuild Build.csproj /t:Test`). +- [ ] Соблюдены требования [`CODESTYLE.md`](../CODESTYLE.md). +- [ ] Проверено, что новый контекст корректно отображается в справке (`/t:BuildDocumentation`), если он публичный. +- [ ] Описание изменений в PR содержит мотивацию и ссылки на тесты/issue. diff --git a/docs/developer_docs.md b/docs/developer_docs.md index b3c38febe..017e824fc 100644 --- a/docs/developer_docs.md +++ b/docs/developer_docs.md @@ -2,200 +2,228 @@ Этот документ помогает быстро разобраться, что лежит в репозитории, зачем это нужно, как устроено внутри и как использовать. -## 1 Картина целиком: из чего состоит OneScript +См. также: -OneScript — реализация языка, совместимого с синтаксисом 1С/BSL. В основе - стековая виртуальная машина. Проект включает реализацию компилятора, исполняющей среды, системы типов и стандартной библиотеки BSL. Поверх этого — инструменты (CLI, раннер), отладка (DAP), веб-обёртки и API для нативных расширений. +- [`README.md`](../README.md) — общее описание, установка, сборка, тесты; +- [`docs/contexts.md`](contexts.md) — практическое руководство по добавлению BSL-контекстов и глобальных методов; +- [`CODESTYLE.md`](../CODESTYLE.md) — требования к стилю кода на C#. -OneScript — открытая реализация языка 1С/BSL поверх .NET, со стековой ВМ и стандартной библиотекой. Сценарии исполняются CLI oscript либо внедряются в приложения через HostedScript. +## 1. Картина целиком: из чего состоит OneScript + +OneScript — открытая реализация языка, совместимого с синтаксисом 1С/BSL, поверх .NET. В основе — стековая виртуальная машина. Проект включает реализацию компилятора, исполняющей среды, системы типов и стандартной библиотеки BSL. Поверх этого — инструменты (CLI, раннер), отладка (DAP), веб-обёртки и API для нативных расширений. + +Сценарии исполняются CLI `oscript` либо встраиваются в приложения через `HostedScript`. Слои (сверху вниз): + - Приложения и инструменты: - - src/oscript — консольный хост, основное приложение; - - src/VSCode.DebugAdapter — адаптер DAP; - - src/OneScriptDocumenter — генерация документации; - - src/TestApp, src/Component — примеры использования. -- Хостинг и сервисы: src/ScriptEngine.HostedScript, src/OneScript.DebugServices, src/OneScript.Web.Server. + - `src/oscript` — консольный хост, основное приложение; + - `src/VSCode.DebugAdapter` — адаптер DAP; + - `src/OneScriptDocumenter` — генерация документации; + - `src/TestApp`, `src/Component` — примеры использования. +- Хостинг и сервисы: + - `src/ScriptEngine.HostedScript`, + - `src/OneScript.DebugServices`, + - `src/OneScript.Web.Server`. - Рантайм (компиляция/исполнение, встроенные функции): - - src/ScriptEngine (стековая ВМ) - - src/OneScript.Native (нативный бэкенд). + - `src/ScriptEngine` — стековая ВМ; + - `src/OneScript.Native` — нативный бэкенд (Expression Trees). - Ядро/язык: - - OneScript.Core (типы/контексты) — основные инфраструктурные компоненты для обоих рантаймов - - OneScript.Language (лексер/парсер/AST) + - `src/OneScript.Core` — типы/контексты, базовая инфраструктура для обоих рантаймов; + - `src/OneScript.Language` — лексер/парсер/AST. - Стандартная библиотека языка BSL: - - OneScript.StandardLibrary — реализация стандартных прикладных классов (массивы, работа с файлами, сетью и пр.) -- Интеграции: ScriptEngine.NativeApi (Мост к внешним компонентам на C++, совместимым с NativeApi 1С). -- Инструмент генерации автодокументации OneScriptDocumenter + - `src/OneScript.StandardLibrary` — стандартные прикладные классы (массивы, работа с файлами, сетью и пр.). +- Интеграции: + - `src/ScriptEngine.NativeApi` — мост к внешним компонентам на C++, совместимым с NativeApi 1С. +- Инструмент генерации автодокументации `src/OneScriptDocumenter`. + +## 2. Быстрый старт для контрибьютора -## 2 Быстрый старт для контрибьютора -- Где собирать: решение src/1Script.sln. -- Входной CLI: src/oscript (консольное приложение для запуска .os‑скриптов). -- Запуск тестов: проекты src/Tests/* (C#) и папка tests/* (скрипты .os). -- Если добавляете новый контекст/тип — обычно правки в OneScript.Core/ScriptEngine/StandardLibrary, плюс модульные тесты. +- Где собирать: решение `src/1Script.sln`. +- Целевой фреймворк: `net8.0` (см. `src/oscommon.targets`), `LangVersion 8.0`. +- Входной CLI: `src/oscript` (консольное приложение для запуска `.os`-скриптов). +- Запуск тестов: + - модульные C#-тесты — проекты `src/Tests/*` (xUnit/NUnit); + - приёмочные BSL-скрипты — каталог `tests/*.os`, запуск через `tests/run-bsl-tests.cmd`/`tests/run-bsl-tests.sh`. +- Сценарий полной сборки и прогона тестов описан в [`README.md`](../README.md) и [`.github/copilot-instructions.md`](../.github/copilot-instructions.md). +- Если добавляете новый контекст/тип — обычно правки в `OneScript.Core`/`ScriptEngine`/`StandardLibrary`, плюс модульные тесты. Подробности — в [`docs/contexts.md`](contexts.md). -Псевдонимы API приняты двуязычные: РусИмя/EngName (см. атрибуты ContextClass/Method/Property). +Соглашения: -Соглашение по ссылкам: указываются относительные пути репозитория. +- Псевдонимы API двуязычные: `РусИмя`/`EngName` (см. атрибуты `ContextClass`/`ContextMethod`/`ContextProperty`). +- Все ссылки в этом документе указываются относительно корня репозитория. -## 3 Обзор проектов (назначение, ключевые узлы) +## 3. Обзор проектов (назначение, ключевые узлы) Ниже по каждому проекту — зачем он нужен, где искать основную логику и какие классы отвечают за ключевые задачи. -### 3.1 OneScript.Language — лексер/препроцессор/парсер/AST +### 3.1. OneScript.Language — лексер/препроцессор/парсер/AST -Назначение: преобразует исходный BSL‑код в токены и синтаксическое дерево, обрабатывает директивы препроцессора. -Проект сделан максимально независимым и отчуждаемым, и должен иметь возможность использоваться в других решениях, не связанных с 1Script, как просто парсер BSL. +Назначение: преобразует исходный BSL-код в токены и синтаксическое дерево, обрабатывает директивы препроцессора. Проект сделан максимально независимым и отчуждаемым: его можно использовать в других решениях, не связанных с 1Script, как просто парсер BSL. -- Где в коде: - - LexicalAnalysis/* — лексер. DefaultLexer.cs, различные состояния (String/Number/Comment/PreprocessorDirective/etc). - - SyntaxAnalysis/* — парсер и AST: DefaultBslParser.cs, BslSyntaxWalker.cs, AstNodes/* (ModuleNode, MethodNode, CallNode, TryExceptNode, *LoopNode, Binary/UnaryOperationNode и др.). - - Препроцессор: PreprocessingLexer.cs, PreprocessorHandlers.cs, RegionDirectiveHandler.cs, ImportDirectivesHandler.cs, ModuleAnnotationDirectiveHandler.cs. - - Диагностика: CodeError.cs, ErrorPositionInfo.cs, SyntaxErrorException.cs, LocalizedErrors.cs. +- Где в коде (пути относительно `src/OneScript.Language/`): + - `LexicalAnalysis/*` — лексер. `DefaultLexer.cs`, различные состояния (`String`/`Number`/`Comment`/`PreprocessorDirective`/etc). + - `SyntaxAnalysis/*` — парсер и AST: `DefaultBslParser.cs`, `BslSyntaxWalker.cs`, `AstNodes/*` (`ModuleNode`, `MethodNode`, `CallNode`, `TryExceptNode`, `*LoopNode`, `BinaryOperationNode`/`UnaryOperationNode` и др.). + - Препроцессор (в `SyntaxAnalysis/`): `PreprocessingLexer.cs`, `PreprocessorHandlers.cs`, `RegionDirectiveHandler.cs`, `ImportDirectivesHandler.cs`, `ModuleAnnotationDirectiveHandler.cs`. + - Диагностика: `CodeError.cs`, `ErrorPositionInfo.cs`, `SyntaxErrorException.cs` (в корне проекта) и `SyntaxAnalysis/LocalizedErrors.cs`. - Жизненный цикл: - 1) Лексер производит Lexem с типом/токеном. - 2) Препроцессор обрабатывает директивы (#Если/#Область/#Использовать). - 3) Парсер строит AST (BslSyntaxNode), восстанавливается после ошибок (IErrorRecoveryStrategy). - 4) AST передаётся компилятору (CompilerFrontend) рантайма. + 1. Лексер производит `Lexem` с типом/токеном. + 2. Препроцессор обрабатывает директивы (`#Если`/`#Область`/`#Использовать`). + 3. Парсер строит AST (`BslSyntaxNode`), восстанавливается после ошибок (`IErrorRecoveryStrategy`). + 4. AST передаётся компилятору (`CompilerFrontend`) рантайма. - Точки расширения: - - собственные директивы препроцессора (IDirectiveHandler -> зарегистрировать в DI); - - обход AST через BslSyntaxWalker. + - собственные директивы препроцессора (`IDirectiveHandler` → зарегистрировать в DI); + - обход AST через `BslSyntaxWalker`. + +На выходе вы получаете `ModuleNode`/AST, пригодный для компиляции рантаймом/бэкендом или для обработки статическим анализатором. -На выходе вы получаете ModuleNode/AST, пригодный для компиляции рантаймом/бэкендом или обработки статическим анализатором. +### 3.2. OneScript.Core — система типов, значения, отражение контекстов -### 3.2 OneScript.Core — система типов, значения, отражение контекстов -Назначение: общий объектный каркас значений BSL, контекстов (объекты/методы/свойства), аннотаций и исключений. +Назначение: общий объектный каркас значений BSL, контекстов (объекты/методы/свойства), аннотаций и исключений. Содержит базовые `IValue`/`BslValue`, ссылки на значения, метаданные контекстов (классов/методов/свойств), атрибуты, исключения, символы компилятора. -OneScript.Core — система типов и контекстная модель -- Назначение: базовые IValue/BslValue, ссылки на значения, метаданные контекстов (классов/методов/свойств), атрибуты, исключения, символы компилятора. - Где в коде: - - Values/* — BslValue и производные: строки/числа/дата/Null/Undefined/Type/Object, сравнения/преобразования; ссылки: IValueReference/Variable/PropertyValueReference/IndexedValueReference. - - Contexts/* — атрибуты ContextClass/ContextMethod/ContextProperty, GlobalContextAttribute, ScriptConstructorAttribute; построители Bsl*Info, отражение классов, поддержка устаревания (ISupportsDeprecation, DeprecatedNameAttribute). - - Compilation/Binding/* — SymbolTable, SymbolScope, SymbolBinding, *Symbol интерфейсы. - - Exceptions/* — RuntimeException, TypeConversionException, PropertyAccessException и др. + - `Values/*` — `BslValue` и производные: строки/числа/дата/`Null`/`Undefined`/`Type`/`Object`, сравнения/преобразования; ссылки: `IValueReference`/`Variable`/`PropertyValueReference`/`IndexedValueReference`. + - `Contexts/*` — атрибуты `ContextClass`/`ContextMethod`/`ContextProperty`, `GlobalContextAttribute`, `ScriptConstructorAttribute`; построители `Bsl*Info`, отражение классов, поддержка устаревания (`ISupportsDeprecation`, `DeprecatedNameAttribute`). + - `Compilation/Binding/*` — `SymbolTable`, `SymbolScope`, `SymbolBinding`, `*Symbol`-интерфейсы. + - `Exceptions/*` — `RuntimeException`, `TypeConversionException`, `PropertyAccessException` и др. - Жизненный цикл контекстов: - 1) ContextDiscoverer (ScriptEngine.Machine.Contexts) сканирует сборки, находит [ContextClass]/[GlobalContext]/[EnumerationType]/[SystemEnum]. - 2) Регистрирует типы/глобальные контексты в IRuntimeEnvironment/IGlobalsManager. - 3) Отражение формирует Bsl*Info для рантайма/документации. + 1. `ContextDiscoverer` (в `ScriptEngine.Machine.Contexts`) сканирует сборки, находит `[ContextClass]`/`[GlobalContext]`/`[EnumerationType]`/`[SystemEnum]`. + 2. Регистрирует типы/глобальные контексты в `IRuntimeEnvironment`/`IGlobalsManager`. + 3. Отражение формирует `Bsl*Info` для рантайма/документации. -### 3.3 ScriptEngine — движок выполнения (стековая ВМ и бэкенд компилятора для стековой машины) +### 3.3. ScriptEngine — движок выполнения (стековая ВМ и бэкенд компилятора для стековой машины) Основная среда исполнения на базе стековой виртуальной машины. Назначение: организует выполнение скриптов, стек вызовов, области видимости, глобальные функции и интеграцию с отладкой. -- Где в коде: - - Compiler/* — CompilerFrontend, BackendSelector; StackMachineCodeGenerator (байткод), EvalCompiler; CodeGenerationFlags. - - Machine/* — StackMachineExecutor, MachineInstance (командный цикл, стек/кадры/исключения/итераторы), ExecutionContext/Frame, BuiltinFunctions, ValueFactory, GlobalInstancesManager. CodeStat/* — статистика покрытия кода. - - Hosting/* — DefaultEngineBuilder, DI (TinyIoC), EngineBuilderExtensions (регистрация сервисов, предобработчики). - - ScriptingEngine.cs — фасад движка: загрузка сборок, Initialize, NewProcess, компиляция. - - ContextValuesMarhaller — маршаллер (преобразователь) типов C# в типы BSL и обратно. +- Где в коде (пути относительно `src/ScriptEngine/`): + - `Compiler/*` — `CompilerFrontend`, `CompilerBackendSelector`, `StackMachineCodeGenerator` (байткод), `EvalCompiler`, `CodeGenerationFlags`. + - `Machine/*` — `StackMachineExecutor`, `MachineInstance` (командный цикл, стек/кадры/исключения/итераторы), `ExecutionContext`/`ExecutionFrame`, `BuiltinFunctions`, `ValueFactory`, `GlobalInstancesManager`. `CodeStat/*` — статистика покрытия кода. + - `Hosting/*` — `DefaultEngineBuilder`, DI (`TinyIoC`), `EngineBuilderExtensions` (регистрация сервисов, предобработчики). + - `ScriptingEngine.cs` — фасад движка: загрузка сборок, `Initialize`, `NewProcess`, компиляция. + - `ContextValuesMarshaller` — преобразователь типов C# в типы BSL и обратно. - Точки расширения: - - дополнительные IExecutorProvider (альтернативные рантаймы); - - предопределённые интерфейсы/итераторы (Interfaces/Iterables handlers); - - сбор кода-статистики (ICodeStatCollector) + - дополнительные `IExecutorProvider` (альтернативные рантаймы); + - предопределённые интерфейсы/итераторы (`Interfaces`/`Iterables` handlers); + - сбор статистики покрытия (`ICodeStatCollector`). + +### 3.4. OneScript.Native — нативный бэкенд (Expression Trees) — компилятор/исполнитель и встроенные функции -### 3.4 OneScript.Native — нативный бэкенд (Expression Trees) компилятор/исполнитель, встроенные функции +Альтернативная среда исполнения (не основная). Предоставляет компиляцию BSL в Expression Trees фреймворка .NET. Имеет ряд ограничений и в целом является экспериментом. В какой именно среде будет исполнен скрипт, решает директива в начале скрипта: -Альтернативная среда исполнения (не основная). Предоставляет компиляцию BSL в ExpressionTrees фреймворка .NET. -Данная среда исполнения имеет ряд ограничений и в целом является экспериментом. В какой именно среде будет исполнен скрипт решает директива в начале скрипта: +- `#native` — скрипт будет скомпилирован в Native Runtime; +- `#stack` или отсутствие директивы — скрипт будет исполнен основной стековой средой. -* `#native` - скрипт будет скомпилировать в Native Runtime -* `#stack` или отсутствие директивы - скрипт будет использован основной средой исполнения. +Назначение: преобразует AST + символы в исполняемую форму и предоставляет нативный бэкенд выполнения, включая встроенные функции. -Назначение: преобразует AST+символы в исполняемую форму и предоставляет нативный бэкенд выполнения, включая встроенные функции. -- Компиляция: Compiler/ - - ModuleCompiler.cs, MethodCompiler.cs — генерация модулей/методов. - - ExpressionTreeGeneratorBase.cs, BinaryOperationCompiler.cs — выражения/операции. - - BuiltInFunctionsCache.cs, ContextMethodsCache.cs — кеширование метаданных/встроенных функций. -- Исполнение: Runtime/ - - NativeExecutorProvider.cs — провайдер исполнителя. - - BuiltInFunctions.cs — реализации встроенных функций. - - DynamicOperations.cs — динамические операции. +- Компиляция: `Compiler/` + - `ModuleCompiler.cs`, `MethodCompiler.cs` — генерация модулей/методов. + - `ExpressionTreeGeneratorBase.cs`, `BinaryOperationCompiler.cs` — выражения/операции. + - `BuiltInFunctionsCache.cs`, `ContextMethodsCache.cs` — кеширование метаданных/встроенных функций. +- Исполнение: `Runtime/` + - `NativeExecutorProvider.cs` — провайдер исполнителя. + - `BuiltInFunctions.cs` — реализации встроенных функций. + - `DynamicOperations.cs` — динамические операции. -- Ограничения: может не поддерживать полный паритет со стековой машиной; выбор режима делает CompilerBackendSelector по соответствующим директивам в начале файла. +Ограничения: может не поддерживать полный паритет со стековой машиной. Выбор режима делает `CompilerBackendSelector` по соответствующим директивам в начале файла. + +### 3.5. ScriptEngine.HostedScript — хостинг, загрузка библиотек, конфигурация + +Назначение: безопасная обвязка движка для встраивания, инициализация стандартного глобального контекста, загрузка библиотек, конфигурирование. -7. ScriptEngine.HostedScript — хостинг, загрузка библиотек, конфигурация -- Назначение: безопасная обвязка движка для встраивания, инициализация стандартного глобального контекста, загрузка библиотек, конфигурирование. - Где в коде: - - HostedScriptEngine.cs — инициализация, глобальные контексты (SystemGlobalContext, DynamicLoadingFunctions), создание процессов. - - LibraryLoader.cs — package-loader.os, подключение .os модулей/классов/макетов; FileSystemDependencyResolver.cs — поиск библиотек, цикл обработки, защита от циклических зависимостей. - - Extensions/EngineBuilderExtensions.cs — UseSystemConfigFile/UseEnvironmentVariableConfig/UseEntrypointConfigFile; UseImports/UseFileSystemLibraries/UseNativeRuntime/UseEventHandlers. + - `HostedScriptEngine.cs` — инициализация, глобальные контексты (`SystemGlobalContext`, `DynamicLoadingFunctions`), создание процессов. + - `LibraryLoader.cs` — `package-loader.os`, подключение `.os`-модулей/классов/макетов; `FileSystemDependencyResolver.cs` — поиск библиотек, цикл обработки, защита от циклических зависимостей. + - `Extensions/EngineBuilderExtensions.cs` — `UseSystemConfigFile`/`UseEnvironmentVariableConfig`/`UseEntrypointConfigFile`; `UseImports`/`UseFileSystemLibraries`/`UseNativeRuntime`/`UseEventHandlers`. - Жизненный цикл: - 1) Читает настройки из системного `oscript.cfg`, файла `oscript.cfg` рядом с entrypoint, и переменной окружения OSCRIPT_CONFIG (в порядке возрастания приоритета, то есть переменная окружения перезаписывает все предыдущие настройки). - 2) Инициализация HostedScriptEngine → глобальные объекты → процесс → компиляция/исполнение модуля. - 3) Загрузка библиотек: default или кастомный package-loader.os, последующая регистрация символов и компиляция задержанных модулей. + 1. Читает настройки из системного `oscript.cfg`, файла `oscript.cfg` рядом с entrypoint и переменной окружения `OSCRIPT_CONFIG` (в порядке возрастания приоритета — переменная окружения перезаписывает все предыдущие настройки). + 2. Инициализация `HostedScriptEngine` → глобальные объекты → процесс → компиляция/исполнение модуля. + 3. Загрузка библиотек: дефолтный или кастомный `package-loader.os`, последующая регистрация символов и компиляция отложенных модулей. + +### 3.6. OneScript.StandardLibrary — стандартная библиотека -### 3.6 OneScript.StandardLibrary — стандартная библиотека Назначение: коллекции, файлы/потоки, текст и кодировки, сеть/HTTP, JSON/XML, ZIP, процессы, таймзоны и др. -- Коллекции: Collections/ - - ArrayImpl.cs, MapImpl.cs, StructureImpl.cs, ValueListImpl.cs. - - Таблицы/деревья значений: ValueTable.cs (+ ValueTableColumn/Row), ValueTree.cs. -- Файлы/потоки/текст: FileOperations.cs, FileContext.cs, Text/* (TextReadImpl.cs, TextWriteImpl.cs), CustomLineFeedStreamReader.cs. -- Сеть/HTTP: Http/* (HttpRequestContext.cs, HttpResponseContext.cs, HttpRequestBody*, InternetProxyContext.cs). -- JSON: Json/* (JSONReader.cs, JSONWriter.cs, JSONDataExtractor.cs, JSONWriterSettings.cs). -- XML/XSLT: Xml/* (XmlReaderImpl.cs, XmlWriterImpl.cs, XSLTransform.cs). -- ZIP: Zip/* (ZipReader.cs, ZipWriter.cs и перечисления параметров). -- Процессы: Processes/* (ProcessContext.cs, GlobalProcessesFunctions.cs). - - StandardGlobalContext.cs — набор полезных глобальных функций/свойств (например, Символы, Приостановить/Sleep, ЗначениеЗаполнено и т.п.). -- Разное: RandomNumberGenerator.cs, StringOperations.cs, Timezones/*. - -### 3.7 OneScript.Web.Server — веб-обёртки для BSL (ASP.NET Core) + +- Коллекции: `Collections/` + - `ArrayImpl.cs`, `MapImpl.cs`, `StructureImpl.cs`, `ValueList/ValueListImpl.cs`. + - Таблицы/деревья значений: `ValueTable/ValueTable.cs` (+ `ValueTableColumn.cs`/`ValueTableRow.cs`), `ValueTree/ValueTree.cs`. +- Файлы/потоки/текст: `FileOperations.cs`, `FileContext.cs`, `Text/*` (`TextReadImpl.cs`, `TextWriteImpl.cs`), `CustomLineFeedStreamReader.cs`. +- Сеть/HTTP: `Http/*` (`HttpRequestContext.cs`, `HttpResponseContext.cs`, `HttpRequestBody*`, `InternetProxyContext.cs`). +- JSON: `Json/*` (`JSONReader.cs`, `JSONWriter.cs`, `JSONDataExtractor.cs`, `JSONWriterSettings.cs`). +- XML/XSLT: `Xml/*` (`XmlReaderImpl.cs`, `XmlWriterImpl.cs`, `XSLTransform.cs`). +- ZIP: `Zip/*` (`ZipReader.cs`, `ZipWriter.cs` и перечисления параметров). +- Процессы: `Processes/*` (`ProcessContext.cs`, `GlobalProcessesFunctions.cs`). +- `StandardGlobalContext.cs` — набор полезных глобальных функций/свойств (например, `Символы`, `Приостановить`/`Sleep`, `ЗначениеЗаполнено` и т.п.). +- Разное: `RandomNumberGenerator.cs`, `StringOperations.cs`, `Timezones/*`. + +### 3.7. OneScript.Web.Server — веб-обёртки для BSL (ASP.NET Core) + Назначение: адаптеры поверх ASP.NET Core API, чтобы работать с HTTP/WebSocket из BSL. -- WebServer.cs — базовая обвязка. -- Http*Wrapper.cs — HttpContext/Request/Response/Cookies. -- WebSockets/* — WebSocketWrapper, WebSocketsManagerWrapper. - -### 3.8 Отладка: OneScript.DebugProtocol, OneScript.DebugServices, VSCode.DebugAdapter -- Протокол (OneScript.DebugProtocol): - - TcpServer/* (DefaultMessageServer.cs, JsonDtoChannel.cs, DispatchingServer.cs) — транспорт и сериализация. - - Модель отладки: Breakpoint.cs, StackFrame.cs, Variable.cs, DebuggerSettings.cs. -- Сервисы (OneScript.DebugServices): - - DefaultDebugService.cs, DefaultDebugController.cs — серверные сервисы отладки. - - ThreadManager.cs, TcpDebugServer.cs — управление потоками и TCP‑сервер. -- Адаптер для VS Code (VSCode.DebugAdapter): - - DebugSession.cs, OscriptDebugSession.cs — основная сессия и проксирование событий. - - ServerProcess.cs, DebugeeProcess.cs — управление процессом отлаживаемого приложения. - -### 3.9 Приложения/утилиты -- oscript (CLI): src/oscript - - Program.cs — входная точка. - - ConsoleHostBuilder.cs — сборка консольного хоста. - - Поведения (режимы): ExecuteScriptBehavior.cs, CheckSyntaxBehavior.cs, ShowVersionBehavior.cs, DebugBehavior.cs и др. -- StandaloneRunner: сборка самодостаточных пакетов/запуск - - Program.cs, StandaloneRunner.cs, ProcessLoader.cs. -- OneScriptDocumenter: генерация документации по сборкам - - На вход получает список DLL (в каталоге с ними рядом должны лежать файлы xml-docs от этих dll) и файл оглавления (в репозитории уже лежит готовый файл оглавления OneScriptDocumenter\default_toc.json) - - На выходе формирует файл с документацией формата Json и/или каталог с документацией в формате markdown. + +- `WebServer.cs` — базовая обвязка. +- `Http*Wrapper.cs` — `HttpContext`/`Request`/`Response`/`Cookies`. +- `WebSockets/*` — `WebSocketWrapper`, `WebSocketsManagerWrapper`. + +### 3.8. Отладка: OneScript.DebugProtocol, OneScript.DebugServices, VSCode.DebugAdapter + +- Протокол (`OneScript.DebugProtocol`): + - `TcpServer/*` (`DefaultMessageServer.cs`, `JsonDtoChannel.cs`, `DispatchingServer.cs`) — транспорт и сериализация. + - Модель отладки: `Breakpoint.cs`, `StackFrame.cs`, `Variable.cs`, `DebuggerSettings.cs`. +- Сервисы (`OneScript.DebugServices`): + - `DefaultDebugger.cs`, `DefaultBreakpointManager.cs`, `DefaultVariableVisualizer.cs` — серверные сервисы отладки и визуализации переменных. + - `ThreadManager.cs`, `TcpDebugServer.cs` — управление потоками и TCP-сервер. +- Адаптер для VS Code (`VSCode.DebugAdapter`): + - `DebugSession.cs`, `OscriptDebugSession.cs` — основная сессия и проксирование событий. + - `ServerProcess.cs`, `DebugeeProcess.cs` — управление процессом отлаживаемого приложения. + +### 3.9. Приложения/утилиты + +- `oscript` (CLI): `src/oscript` + - `Program.cs` — входная точка. + - `ConsoleHostBuilder.cs` — сборка консольного хоста. + - Поведения (режимы): `ExecuteScriptBehavior.cs`, `CheckSyntaxBehavior.cs`, `ShowVersionBehavior.cs`, `DebugBehavior.cs` и др. +- `StandaloneRunner` — сборка самодостаточных пакетов/запуск: + - `Program.cs`, `ProcessLoader.cs`, `StandaloneApplicationHost.cs`, `StandaloneProcess.cs`, `StandaloneTemplateFactory.cs`. +- `OneScriptDocumenter` — генерация документации по сборкам: + - на вход получает список DLL (рядом должны лежать xml-docs от этих dll) и файл оглавления (готовый `OneScriptDocumenter/default_toc.json` лежит в репозитории); + - на выходе формирует файл документации в формате JSON и/или каталог с документацией в формате Markdown. - Примеры/демо: - - Component — простая .NET‑библиотека/компонент и примеры использования. - - TestApp — WPF‑приложение‑песочница (подсветка синтаксиса, запуск модулей). + - `Component` — простая .NET-библиотека/компонент и примеры использования. + - `TestApp` — WPF-приложение-песочница (подсветка синтаксиса, запуск модулей). + +### 3.10. ScriptEngine.NativeApi — C++ API для нативных расширений -### 3.10 ScriptEngine.NativeApi — C++ API для нативных расширений -- Основные файлы: NativeApiProxy.cpp, NativeInterface.cpp, include/* (AddInDefBase.h, ComponentBase.h и др.). +- Основные файлы: `NativeApiProxy.cpp`, `NativeInterface.cpp`, `include/*` (`AddInDefBase.h`, `ComponentBase.h` и др.). - Задача: писать нативные аддины, видимые в BSL как объекты/контексты. -## 4 Как компоненты связаны между собой (словесная диаграмма) -- Language → даёт AST и ошибки компиляции. -- Core → базовые типы/контексты; используется Native, ScriptEngine, StandardLibrary. -- Native → компилирует и исполняет, опирается на Language/Core. -- ScriptEngine → организует выполнение (стек‑машина), использует Native и Core. -- HostedScript → высокий уровень хостинга поверх ScriptEngine. -- StandardLibrary → реализована на Core/ScriptEngine. -- DebugProtocol/DebugServices ↔ ScriptEngine — обмен данными отладки; VSCode.DebugAdapter ↔ DebugServices. -- Web.Server ↔ ASP.NET Core API — обёртки для работы из BSL. -- oscript/StandaloneRunner/Documenter/TestApp/Component — надстройки поверх ядра/рантайма. -- NativeApi ↔ ScriptEngine/Core — нативные расширения. - -## 5 Типичные сценарии доработок (куда лезть) -- Добавить объект/контекст с методами: OneScript.Core/Contexts/* (аннотации Context*Attribute). -- Добавить функцию в стандартную библиотеку: соответствующий раздел OneScript.StandardLibrary (например, Json/ или Collections/), плюс экспорт в общий контекст (StandardGlobalContext.cs или SymbolsContext.cs, если нужно). -- Встроенная функция языка/операция: OneScript.Native/Runtime/BuiltInFunctions.cs и/или Compiler/*, при необходимости — поддержка в ScriptEngine/Machine. -- Отладка: DebugServices/DebugProtocol — добавление/изменение событий или представления переменных; VSCode.DebugAdapter — проксирование. - -## 6 Навигация по тестам -- C#-тесты: src/Tests/*: - - Язык: src/Tests/OneScript.Language.Tests/* (лексер/парсер/препроцессор). - - Ядро/типы/контексты: src/Tests/OneScript.Core.Tests/*. - - Динамика/нативный рантайм: src/Tests/OneScript.Dynamic.Tests/*. - - Стандартная библиотека: src/Tests/OneScript.StandardLibrary.Tests/*. - - Отладчик: src/Tests/VSCode.DebugAdapter.Tests/, src/Tests/OneScript.DebugProtocol.Test/. -- Скриптовые тесты: tests/*.os (поведенческие сценарии языка/библиотек). \ No newline at end of file +## 4. Как компоненты связаны между собой (словесная диаграмма) + +- `OneScript.Language` → даёт AST и ошибки компиляции. +- `OneScript.Core` → базовые типы/контексты; используется в `OneScript.Native`, `ScriptEngine`, `OneScript.StandardLibrary`. +- `OneScript.Native` → компилирует и исполняет, опирается на `OneScript.Language`/`OneScript.Core`. +- `ScriptEngine` → организует выполнение (стековая ВМ), использует `OneScript.Native` и `OneScript.Core`. +- `ScriptEngine.HostedScript` → высокий уровень хостинга поверх `ScriptEngine`. +- `OneScript.StandardLibrary` → реализована на `OneScript.Core`/`ScriptEngine`. +- `OneScript.DebugProtocol`/`OneScript.DebugServices` ↔ `ScriptEngine` — обмен данными отладки; `VSCode.DebugAdapter` ↔ `OneScript.DebugServices`. +- `OneScript.Web.Server` ↔ ASP.NET Core API — обёртки для работы из BSL. +- `oscript`/`StandaloneRunner`/`OneScriptDocumenter`/`TestApp`/`Component` — надстройки поверх ядра/рантайма. +- `ScriptEngine.NativeApi` ↔ `ScriptEngine`/`OneScript.Core` — нативные расширения. + +## 5. Типичные сценарии доработок (куда лезть) + +- Добавить объект/контекст с методами: `OneScript.Core/Contexts/*` (атрибуты `Context*Attribute`); подробности и шаблоны — в [`docs/contexts.md`](contexts.md). +- Добавить функцию в стандартную библиотеку: соответствующий раздел `OneScript.StandardLibrary` (например, `Json/` или `Collections/`), плюс экспорт в общий контекст (`StandardGlobalContext.cs` или `SymbolsContext.cs`, если нужно). +- Встроенная функция языка/операция: `OneScript.Native/Runtime/BuiltInFunctions.cs` и/или `Compiler/*`, при необходимости — поддержка в `ScriptEngine/Machine`. +- Отладка: `OneScript.DebugServices`/`OneScript.DebugProtocol` — добавление/изменение событий или представления переменных; `VSCode.DebugAdapter` — проксирование. + +## 6. Навигация по тестам + +- C#-тесты: `src/Tests/*`: + - Язык: `src/Tests/OneScript.Language.Tests/*` (лексер/парсер/препроцессор). + - Ядро/типы/контексты: `src/Tests/OneScript.Core.Tests/*`. + - Динамика/нативный рантайм: `src/Tests/OneScript.Dynamic.Tests/*`. + - Стандартная библиотека: `src/Tests/OneScript.StandardLibrary.Tests/*`. + - Документатор: `src/Tests/DocumenterTests/*`. + - Отладчик: `src/Tests/VSCode.DebugAdapter.Tests/`, `src/Tests/OneScript.DebugProtocol.Test/`. +- Скриптовые тесты: `tests/*.os` — поведенческие сценарии языка и стандартной библиотеки. Запускаются скриптами `tests/run-bsl-tests.cmd`/`tests/run-bsl-tests.sh` через свежесобранный `oscript` (см. [`README.md`](../README.md), раздел «Тестирование»).