h2peripheral　API　version0.1 詳細 - Minecraftとタートルと僕

（このページは、h2peripheral APIについて情報をまとめるページです。このページは随時更新します）

本APIの概要

このAPIは、周辺機器を取り扱う標準のPeripheral APIを拡張するものです。
以下の関数があります。

wrapByName(＜機器種別＞)
- 隣接している全ての方向を調べ、指定した機器種別に該当する機器を見つけたら、その機器の関数群をテーブルとして返す。
- つまり、peripheral.wrap()が方向を指示するのに対して、機器種別名で指示するようにしようという発想。
- プログラムをインストールたびに周辺機器を装着している方向を書き換えるの面倒ですし！

wrap(＜機器種別あるいは方向＞)
- 上記のwrapByName()とperipheral.wrap()のセレクタ関数。引数が「機器種別」なら前者に、「方向」なら後者に処理を引き渡す。
- あいまいな入力でかしこく処理してくれるのって便利やん？

waitForDetect(＜機器種別あるいは方向＞)
- 指定した＜機器種別あるいは方向＞に該当する機器を見つけたら、その機器の関数群をテーブルとして返す。
- もし見つからなかったら、該当する機器が装着されるまで待つ。
- 内部で、wrapByName()とos.pullEvent("peripheral")を利用。

本APIを使う利点

「peripheral.wrap()」によって周辺機器を利用するプログラムの実行手順。

コンピュータ設置 → 周辺機器装着 → 周辺機器を使うプログラムを手動で実行 → プログラム処理

「h2peripheral.waitForDetect()」関数を使うことで、startupプログラム中で周辺機器を使うことが可能。

コンピュータ設置→（startupでプログラム自動実行＆一時停止）→周辺機器装着→（プログラムを継続実行） → プログラム処理

つまりコンピュータやタートルを設置したら、必要な周辺機器をつけるだけでいきなりプログラムが動き出すように見えます。しかも、機器種別名だけで機器を自動認識するため機器をつける方向を問いません。

ソースコード配布・インストール方法・ソースの解説

ソース

http://pastebin.com/ck6QZ2CS

インストール方法

> pastebin get ck6QZ2CS h2peripheral

ソース解説

APIを作ろう（４）－h2peripheral API の実装を解説 - Minecraftとタートルと僕

本APIの詳細

関数

wrapByName(＜機器種別＞)

隣接している全ての方向を調べ、指定した機器種別に該当する機器を見つけたら、その機器の関数群をテーブルとして返す。
引数１：機器種別（文字列）。機器種別と実際の周辺機器の対応は本ページ末尾の表を参照のこと。
返値１：定数/関数群（テーブル）。最終的にperipheral.wrap()による返値を利用。指定した周辺機器が見つからない場合はnil。
- 返値テーブルの中に、どの方向にあったのかを追加情報として含める*1。
その他備考
- 内部でperipheral.wrap()を利用。
- 同じ種別の周辺機器が複数あったら最初に見つかったものを返す。
- 検索順番はrs.getSides()を利用する（top, bottom, left, right, front, back　の順番）。

(サンプルコード)

mon = h2peripheral.wrapByName("advanced_monitor")
mon.setBackgroundColor(colors.blue)
print(mon.side) -- => "top"

wrap(＜機器種別あるいは方向＞)

上記のwrapByName()とperipheral.wrap()のセレクタ関数。引数が「機器種別」なら前者に、「方向」なら後者に処理を引き渡す。
引数１：機器種別（文字列）、あるいは方向（文字列）
返値１：定数/関数群（テーブル）。最終的にperipheral.wrap()による返値を利用。
- 返値テーブルの中にどの方向にあったのかを追加情報として含める。
- 指定した周辺機器が見つからない場合はnil。

(サンプルコード)

mon1 = h2peripheral.wrap("advanced_monitor")
mon1.setBackgroundColor(colors.blue)

mon2 = h2peripheral.wrap("bottom")
mon2.clear()
print(mon2.side) -- => "bottom"

waitForDetect(＜機器種別あるいは方向＞)

指定した＜機器種別あるいは方向＞に該当する機器を見つけたらその機器の関数群をテーブルとして返す。もし見つからなかったら、該当する機器が装着されるまで待つ。
引数１：機器種別（文字列）、あるいは方向（文字列）
返値１：定数/関数群（テーブル）。最終的にperipheral.wrap()による返値を利用。
- 返値テーブルの中にどの方向にあったのかを追加情報として含める。

(サンプルコード)

term.write("Now Detecting...")
mon = h2peripheral.waitForDetect("advanced_monitor")
print("OK.")
print(mon.side) -- => "top"

本APIで扱う「機器種別」（文字列）

機器種別（文字列）と、それに該当する周辺機器*2

機器種別	周辺機器
"monitor"	Monitor, Advanced Monitor
"advanced_monitor"	Advanced Monitor
"modem"	Wired Modem, Wireless Modem
"wireless_modem"	Wireless Modem
"drive"	Disk Drive
"workbench"	Crafty Turtle の作業台
"printer"	Printer
"command"	Command Block