Skip to content

Commit

Permalink
Документация
Browse files Browse the repository at this point in the history
  • Loading branch information
@nixel2007
nixel2007 committed Dec 4, 2023
1 parent 12fa323 commit 0773795
Showing 1 changed file with 31 additions and 72 deletions.
103 changes: 31 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,13 +35,13 @@
- [Уникальность экземпляров компонентов](#уникальность-экземпляров-компонентов)
- [Дополнительная обработка компонента](#дополнительная-обработка-компонента)
- [Использование контекста приложения](#использование-контекста-приложения)
- [Вынос логики регистрации желудей из точки запуска приложения](#вынос-логики-регистрации-желудей-из-точки-запуска-приложения)
- [Условная регистрация компонентов в контексте приложения](#условная-регистрация-компонентов-в-контексте-приложения)
- [Инверсия управления запуском приложения](#инверсия-управления-запуском-приложения)
- [Собственные аннотации](#собственные-аннотации)
- [Наследование аннотаций](#наследование-аннотаций)
- [Обработка аннотаций](#обработка-аннотаций)
- [Статический инициализатор контекста](#статический-инициализатор-контекста)
- [Заключение](#заключение)
- [В предыдущих сериях](#в-предыдущих-сериях)
- [Заключение](#заключение)

## Зачем мне это?

Expand All @@ -66,41 +66,31 @@

Для инициализации контекста "ОСени" служит класс `Поделка`, который необходимо создать через `Новый` (один разочек можно и написать это вредное слово), а затем наполнить Желудями, Дубами и Напильниками. Нет, мы не упоролись, скоро расскажем, что тут к чему.

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

1. Через сканирование каталога:
Инициализировать контекст можно так:

```bsl
// file: main.os
#Использовать autumn
Поделка = Новый Поделка();
Поделка.ПросканироватьКаталог(ТекущийКаталог());
```

Сей нехитрый код заставит ОСень просканировать все `*.os` файлы в текущем каталоге (включая подкаталоги), понять, кто из них желудь, а кто дуб, и последовательно их добавить в контекст.
И... всё.

<!-- markdownlint-disable MD029 -->
2. Через непосредственную регистрацию:
<!-- markdownlint-enable MD029 -->
При создании Поделки ОСень автоматически просканирует все доступные в системе типов классы, определит, кто их них желудь, а то дуб, и последовательно добавит их в контекст.

Вероятно, помимо загрузки собственно ОСени, вы захотите так же зарегистрировать и собственные классы. Единственное, что для этого нужно, это выполнить обычное для OneScript подключение библиотек по имени или пути:

```bsl
// file: main.os
#Использовать autumn
#Использовать "."
Поделка = Новый Поделка();
Поделка
.ДобавитьЖелудь(Тип("ВерхнеуровневыйЖелудь"))
.ДобавитьЖелудь(Тип("ЖелудьНижнегоУровня"))
.ДобавитьДуб(Тип("ГлавныйДуб"));
```

Не так красиво, как первый вариант, зато гибкости побольше, если вдруг она необходима.

### Запуск приложения

После добавления всех желудей, дубов и прочих частей в нашу поделку мы готовы к запуску приложения.
Expand Down Expand Up @@ -237,7 +227,7 @@

В листинге выше объявляются две функции-конструктора, возвращающие желуди. Как вы видите, желудь может быть чем угодно, а что угодно (в данном случае - строка) может быть желудем.

Т. к. `Дуб` - это тоже желудь, а методы "Завязью" - это псевдо-конструкторы, то такой метод может быть скреплен пластилином с другими желудями. Плохие желуди могут даже хардкодить значения паролей, но мы закроем на это глаза.
Т. к. `Дуб` - это тоже желудь, а методы с "Завязью" - это псевдо-конструкторы, то такой метод может быть скреплен пластилином с другими желудями. Плохие желуди могут даже хардкодить значения паролей, но мы закроем на это глаза.

В листинге выше `&Завязь` содержит параметр `Тип`. Он требуется, если из имени функции непонятно, что за тип она вернет. Ну, нам-то с вами понятно, что `Пароль` - это строка, но вот глупой железке надо немного помочь.

Expand Down Expand Up @@ -286,7 +276,7 @@

> Поддержка загрузки настроек из переменных окружения и аргументов командной строки в ближайших планах разработки. Еще год-два и точно запилим, честно-честно!
Конфигурационный файл может быть в виде `json` или `yaml` файла, называется `autumn-properties.json`/`autumn-properties.yml` соответственно и ищется ОСенью в каталоге запуска приложения или в подкаталоге `src`.
Конфигурационный файл может быть в виде `json`, `yaml` или `ini` файла, называется `autumn-properties.json`/`autumn-properties.yml`/`autumn-properties.ini` соответственно и ищется ОСенью в каталоге запуска приложения или в подкаталоге `src`.

```json
{
Expand All @@ -300,7 +290,7 @@

А вот так их можно использовать в жёлуде:

```bsl
```bsl
// file: Классы/Обновлятор1С.os
&Деталька
Expand All @@ -318,7 +308,7 @@
&Желудь
Процедура ПриСозданииОбъекта()
КонецПроцедуры
```
```

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

Expand Down Expand Up @@ -728,11 +718,11 @@ JSON обычно содержит вложенные объекты и масс

Поэтому вам никто не запретит с помощью `Пластилина` прилепить `Поделка` в ваш `Желудь`, `Дуб` или даже `Напильник`. Главное - берегите свое ментальное здоровье.

### Вынос логики регистрации желудей из точки запуска приложения
### Условная регистрация компонентов в контексте приложения

Иногда вам может потребоваться выбирать, какие именно желуди вы хотите добавлять в свою поделку. Или их просто много, и не хочется захламлять точку запуска приложения вызовами `Поделка.ДобавитьЖелудь()`. Или по какой-то причине вам не подходит `Поделка.ПросканироватьКаталог()`. На помощь придёт объект `&Заготовка`, который можно расценивать как готовый набор желудей, добавляемый в поделку.
Иногда вам может потребоваться выбирать, какие именно классы вы хотите добавлять в свою поделку. Например, вы хотите загружать определенный класс только при выполнении какого-нибудь условия (из-за конфликта имен, к примеру). На помощь придёт объект `&Заготовка`, который можно расценивать как готовый набор желудей, добавляемый в поделку.

`&Заготовка` - это очень хитрый `&Желудь`! В отличие от обычных желудей он автоматически создается на фазе инициализации приложения, а затем у него вызывается метод `ПриИнициализацииПоделки(Поделка)`. Желудёвость заготовки позволяет пользоваться частью возможностей обычных желудей - на нем будут срабатывать `&Напильники`, добавленные в `Поделку` до `&Заготовки`, однако из всего многообразия ~~веществ~~ зависимостей ему доступны только `&Детальки` с настройками приложения. Ни тебе `&Пластилина`, ни `&Блестяшек` навесить на `&Заготовку` нельзя.
`&Заготовка` - это очень хитрый `&Желудь`! В отличие от обычных желудей он автоматически создается на фазе инициализации приложения, а затем у него вызывается метод `ПриИнициализацииПоделки(Поделка)`. Желудёвость заготовки позволяет пользоваться частью возможностей обычных желудей - на нем могут срабатывать `&Напильники`, добавленные в `Поделку` до `&Заготовки`, однако из всего многообразия ~~веществ~~ зависимостей ему доступны только `&Детальки` с настройками приложения. Ни тебе `&Пластилина`, ни `&Блестяшек` навесить на `&Заготовку` нельзя.

```bsl
// file: Классы/НаборЖелудей.os
Expand All @@ -745,44 +735,25 @@ JSON обычно содержит вложенные объекты и масс
КонецПроцедуры
Процедура ПриИнициализацииПоделки(Поделка) Экспорт
Поделка.ДобавитьЖелудь(Тип("Обновлятор1С"));
Поделка.ДобавитьЖелудь(Тип("ПроверяторВерсий");
ПутьКСценарию = "./ОбычныйПроверятор.os";
Если _ПереопределитьПроверятор Тогда
Поделка.ДобавитьЖелудь("ВерховныйПроверяторВерсий");
ПутьКСценарию = "./НеобычныйПроверятор.os";
КонецЕсли;
КонецПроцедуры
```

Использовать заготовку можно так:
```bsl
// file: main.os
Поделка = Новый Поделка();
Поделка
.ДобавитьЗаготовку(Тип("НаборЖелудей"))
.ЗапуститьПриложение();
```
ПодключитьСценарий(ПутьКСценарию, "Проверятор");
Лучше, чем дублировать ту же логику в `main.os`, не правда ли?
КонецПроцедуры
```

### Инверсия управления запуском приложения

Одной из конечных точкой использования фреймворка для внедрения зависимостей является отказ от какой-либо логики при запуске приложения. В конце концов мы же жёлуди в поделку добавляем не просто так, а чтобы они могли `Сообщить("Привет, мир!")`.

Вместо императивного стиля в виде поиска желудя и вызова у него нужного метода, мы можем добавить в `Поделку`... ещё один жёлудь с аннотацией `&Рогатка`.

`&Рогатка` - это специальный желудь, содержащий метод `ПриЗапускеПриложения()`, который вызовется при, кхм, запуске приложения. Если быть точным, при вызове `Поделка.ЗапуститьПриложение()`.

```bsl
// file: main.os
Поделка = Новый Поделка();
Поделка
.ДобавитьРогатку(Тип("ПришедшийСМиром"))
.ЗапуститьПриложение();
```
`&Рогатка` - это специальный желудь, содержащий метод `ПриЗапускеПриложения()`, который вызовется при, кхм, запуске приложения. Если еще точнее, при вызове `Поделка.ЗапуститьПриложение()`.

```bsl
// file: Классы/ПришедшийСМиром.os
Expand Down Expand Up @@ -934,29 +905,17 @@ OneScript могуч. В отличие от материнской платфо

Для всего остального есть модуль `РаботаСАннотациями`.

### Статический инициализатор контекста

В некоторых случаях может понадобиться указать "ОСени" набор заготовок до/без собственно создания новой `Поделки`. Сейчас будет серьезный пример, т.к. на упоротых аналогиях объяснить такое не получается. И вообще, я птичка, мне такое сложно.
## В предыдущих сериях

В составе "ОСени" есть метод `Осень.ДобавитьЗаготовкуДляАвтоИнициализации(ИмяТипаЗаготовки)`, в который в качестве `ИмяТипаЗаготовки` можно передать *строку* с именем типа. Добавленные таким образом `&Заготовки` будут созданы и вызваны сразу же при создании `Поделки`. Особенность этого метода в том, что его можно вызывать еще до полной прогрузки классов и модулей вашего приложения или импортируемой сторонней библиотеки.

Например, библиотека [winow](https://github.com/Nivanchenko/winow) содержит [модифицированный загрузчик библиотек](https://github.com/Nivanchenko/winow/blob/master/package-loader.os#L14), который прямо в момент `#Использовать winow` добавит в контекст `Поделки` информацию обо всех желудях, имеющихся в библиотеке, включая `&Рогатку`, которая и запустит веб-сервер, реализованный в `winow`.

Таким образом, точка входа в приложение может быть минималистичной настолько, насколько возможно. Например, полный текст модуля запуска приложения на `winow` выглядит вот так:

```bsl
#Использовать autumn
#Использовать winow
Поделка = Новый Поделка;
Поделка.ЗапуститьПриложение();
```
В прошлых версиях библиотеки и/или документации вы могли встречать описание таких вещи как:

В коде выше сначала импортируется сама "ОСень", которая и предоставит модуль `Осень` с методом добавления заготовок, а затем загрузится `winow`, которая своим загрузчиком библиотеки наполнит "ОСень" заготовками. А уже при создании приложения и его запуске и произойдет вся магия регистрации и запуска желудей.
* методы `Поделка.ДобавитьЖелудь()`/`Поделка.ДобавитьДуб()` и другие методы добавления желудей в поделку;
* метод `Поделка.ПросканироватьКаталог()`
* модуль `Осень` и автоматическую регистрацию заготовок для запуска при создании поделки;

Такие дела.
Все это устарело и теперь либо не используется, либо просто не нужно. Да, следить за чейнджлогами полезно!

### Заключение
## Заключение

Если вы думаете, что мы упоролись, то вы в чем-то даже правы. Напоследок отмечу, что среди вариантов именования аннотаций "ОСени" еще была связка Гриб/Грибница/Спора/Рецепт для Желудь/Дуб/Завязь/Напильник соответственно. Так что еще не все потеряно. Надеюсь.

Expand Down

0 comments on commit 0773795

Please sign in to comment.