OpenComputers/Component API

Этот интерфейс используется для доступа и взаимодействия компьютера с компонентами.

## Интерфейс

`component.doc(address:string, method:string): string`


Возвращает строку документации по заданному методу заданного адресом компонента.
Обратите внимание, что вы также можете получить эту строку при помощи функции `tostring`

. Пример: `tostring(component.screen.isOn)`

.



`component.invoke(address:string, method:string[, ...]): ...`


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



`component.list([filter:string]):function`


Возвращает итерируемый список всех компонентов присоединенных к компьютеру (сети) в виде кортежей «адрес, тип компонента».

Пример использования: `for address, componentType in component.list() do ... end`

.

Если установлен параметр `filter`

, функция возвращает только те компоненты, которые содержат заданную строку (это *не* шаблон/регулярное выражение). Например, `component.list("red")`

вернет компоненты `redstone`

.



`component.proxy(address:string):table`


Возвращает «прокси» объект компонента. Прокси предоставляет все методы компонента в качестве своих полей, что позволяет обращаться к ним напрямую (без вызова `invoke`

).

Может использоваться для получения первого компонента некоторого типа:

`component.proxy(component.list("redstone")()).getInput(sides.north)`


Результат — прокси первого `redstone`

компонента возвращенного оператором `component.list`

вызывает метод `getInput`

.

*Примечание*: `component.list`

всегда содержит как минимум два поля: `type`

с названием типа компонента и `address`

с его адресом.



`component.type(address:string):string`


Возвращает тип компонента заданного адресом.



`component.get(address: string[, componentType: string]): string | (nil, string)`


Пытается найти полный адрес компонента по сокращенному. Возвращает адрес в случае успеха, или `nil`

и текст ошибки в противном случае. Необязательный параметр — фильтр по типу компонентов.



`component.isAvailable(componentType: string): boolean`


Проверяет доступен ли главный компонент с указанным типом.



`component.getPrimary(componentType: string): table`


Возвращает прокси главного компонента заданного типа. Вызывает ошибку, если такого не существует.



`component.setPrimary(componentType: string, address: string)`


Назначает новый главный компонент заданного типа. Адрес может быть сокращенным, но при этом должен быть правильным (если он не равен `nil`

). Переключает сигналы `component_unavailable`

или `component_available`

если адрес равен `nil`

или новому значению соответственно.



## Примеры

Программа пишет «redstone» для каждой красной платы в сети.

local component = require("component") -- prints `redstone` for each attached redstone card. for _, name in component.list("red") do print(name) end


Обратите внимание, что Component API позволяет также следующий синтаксис:

local component = require("component") local rs0 = component.getPrimary("redstone") local rs1 = component.redstone -- syntactic sugar print(rs0 == rs1) -- true



## Адреса компонентов

Каждый компонент имеет свой адрес. Этот адрес представляет собой UUID — уникальный идентификатор. В большинстве случаев адрес можно сократить до уникальной части. Чтобы получить полный адрес из сокращенного используйте `component.get`

. Чтобы узнать адрес конкретного устройства вы можете воспользоваться анализатором (зажмите `Ctrl` и щелкните правой кнопкой мыши).

Получение списка адресов всех компонентов в сети:

# lua Lua 5.2.3 Copyright (C) 1994-2013 Lua.org, PUC-Rio lua> local component = require("component") lua> for k,v in component.list() do print(k, v) end xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx keyboard xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx screen xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx gpu ...

Обратите внимание, что компоненты сохраняют свои адреса даже тогда, когда удалены из компьютера. Таким образом, дисковод, который вы вытащили и поставили обратно, сохраняет свой адрес. Это не касается механизмов-блоков. Блоки получают новый адрес каждый раз, когда их ставят.



## «Главный» компонент

Component API назначает один из компонентов каждого типа «главным». Если блоков одного типа несколько, «главный» выбирается случайно. Вы можете обращаться к главному компоненту оператором `component.xxx`

, где `xxx`

— это тип.

Например:

lua> component.gpu.address xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

В качестве альтернативы, вы можете воспользоваться оператором `component.getPrimary("xxx")`

. В этом случае можно получить ошибку если не существует главного компонента этого типа. Это можно предварительно проверить оператором `component.isAvailable("xxx")`

. Получить сообщение об ошибке может быть понятнее, чем `nil`

в первом варианте.


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



## Прокси

Есть два способа использования адресов компонентов. Первый — `component.invoke(address, method, ...)`

. Например:

local component = require("component") component.invoke(modemAddress, "broadcast", port, data)

Более удобный способ — прокси. Прокси — это таблица, которая предоставляет одноимённую функцию для каждого вызова метода через `invoke`

. Кроме того прокси имеет два поля: `address`

, которое определяет адрес компонента, и `type`

, которое содержит его тип. пример использования прокси:

local component = require("component") local proxy = component.proxy(address) -- The call above using the proxy: proxy.broadcast(port, data) -- The common proxy fields: print(proxy.address) -- address passed to component.proxy above print(proxy.type) -- "modem"

*Примечание*: когда вы обращаетесь к главному компоненту через `component.getPrimary`

или `component.xxx`

— вы используете его прокси.



## Прямые вызовы

Некоторые вызовы компонентов могут выполняться как «прямые вызовы». «Прямые вызовы» выполняются в рабочем потоке компьютера. Это означает, что результат будет получен немедленно. Обычные вызовы делегируются в главный поток сервера, чтобы избежать состояния гонки и других конфликтов потоков. Это означает, что обычные вызовы выполняются в течение одного «такта» (50 миллисекунд).

Этот случай относится только к Component API.



## Сигналы

Сигналы — важный элемент взаимодействия с компонентами. При помощи сигналов компоненты могут уведомлять компьютер о каких-либо событиях или изменениях вокруг. К примеру, пользовательский ввод обрабатывается компьютером при помощи сигналов. Компьютеры также могут создавать свои собственные сигналы. Это может быть удобно для повторного использования кода, или просто асинхронного доступа к другим частям кода.