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

現在判明している次バージョンCC1.6のperipheral.find()の仕様が不満なので作りました。

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

本APIの概要

(version 0.1についてはこちら)

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

getType(＜方向＞)
- 指定した方向にある周辺機器のタイプ名を返す。
- 第1返値は、CC標準の機器タイプ名（"monitor"など）。第2返値はより詳細な機器タイプ名（"advanced_monitor"など）
isAdvancedMonitor(＜方向＞)、isWirelessModem(＜方向＞)
- それぞれ、指定した方向にある周辺機器がAdvancedMonitorであるか、WirelessModemであるかをtrue/falseで返す。

wrapByName(＜機器種別＞)
- 隣接している周辺機器の中に＜機器種別＞に該当する機器を見つけたら、その機器の関数群をテーブルとして返す。
- 該当する機器が複数あるならば、それらを全て返す。
- peripheral.wrap()が方向を指示するのに対して、本関数は機器種別名で指示する。

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

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

本APIを使う利点

その１：＜方向＞あるいは＜機器種別＞でかしこく処理。

h2peripheral.find("left")、あるいは h2peripheral.find("advanced_monitor")。どちらでもかしこく処理してくれます。

その２：見つからなかったら、装着されるまで待ちます。

標準の「peripheral.wrap()」によって周辺機器を利用するプログラムの実行手順。
- コンピュータ設置 → 周辺機器装着 → 周辺機器を使うプログラムを手動で実行 → プログラム処理
「h2peripheral.waitForDetection()」関数を使うことで、startupプログラム中で周辺機器を使うことが可能。
- コンピュータ設置→（startupでプログラム自動実行＆一時停止）→周辺機器装着→（プログラムを継続実行） → プログラム処理

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

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

ソース

http://pastebin.com/ipuisaNU

利用方法

pastebinコマンドを使ってダウンロード

> pastebin get ipuisaNU h2peripheral

自分のプログラム中に以下のコードを埋め込む

os.loadAPI("h2peripheral")

ソース解説

h2peripheral version0.1については以下のとおり
- APIを作ろう（４）－h2peripheral API の実装を解説 - Minecraftとタートルと僕
version0.2についてはまだありません

更新履歴

0.2b :繰り返しこのAPIをloadAPIすると重くなる症状を修正。
0.2a :公開

本APIの詳細

関数

getType(＜方向＞)

標準のperipheral.getType()に対応する機能強化版の関数。機器のタイプ名を返す。
引数１：機器種別（文字列）。機器種別と実際の周辺機器の対応は本ページ末尾の表を参照のこと。
返値１：機器タイプ名（文字列）。CC標準のタイプ名（"monitor"など）を返す。
返値２：より詳細な機器タイプ名（文字列）。"advanced_monitor"、"wireless_modem"などを返す。普通のモニタならば"monitor"を返す。

isAdvancedMonitor(＜方向＞)、isWirelessModem(＜方向＞)

それぞれ、指定した方向にある周辺機器がAdvancedMonitorであるか、WirelessModemであるかをtrue/falseで返す。
引数１：方向（文字列）
返値１：true/false（boolean）

wrapByName(＜機器種別＞)

隣接している周辺機器の中に＜機器種別＞に該当する機器を見つけたら、その機器の関数群をテーブルとして返す。
引数１：機器種別（文字列）。機器種別と実際の周辺機器の対応は本ページ末尾の表を参照のこと。
返値（複数）：定数/関数群（テーブル）。最終的にperipheral.wrap()による返値を利用。指定した周辺機器が見つからない場合はnil。
- 同じ種別の周辺機器が複数あったらそれらを全て返す。
- 返値とする関数テーブルの中に以下の関数を追加する。*1。
  - getSide()、getType()

(サンプルコード)

mon1, mon2 = h2peripheral.wrapByName("advanced_monitor")
mon1.setBackgroundColor(colors.blue)
print(mon1.getSide()) -- => "top"
print(mon1.getType()) -- => "monitor", "advanced_monitor"

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

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

(サンプルコード)

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

mon3 = h2peripheral.wrap("bottom")
mon3.clear()
print(mon3.getSide()) -- => "bottom"

mon = { h2peripheral.find("advanced_monitor") } -- use table constructor
mon[1].setBackgroundColor(colors.blue)
mon[2].getSide()

mon = (h2peripheral.find("advanced_monitor")) -- get a function-table
mon.getSide()

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

wrap(＜機器種別あるいは方向＞)の別名関数。

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

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

(サンプルコード)

term.write("Now Detecting...")
mon = h2peripheral.waitForDetection("advanced_monitor")
print("OK.")
print(mon.getSide()) -- => "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