Redstone helper API - rshelp

Have you ever tried to get a redstone event, and found it lacking the side the redstone event occured on, and whether it was true or false?

I have, which is why I decided to create this API. The usage is very simple for what is provided.

rshelp.pullEvent([noTerminate, exclusive, side, wire, val])

In its simplest form, you can use this EXACTLY like os.pullEvent. The main difference is that if the event is a redstone event, further params are returned. The params returned are the side, the type of redpower coloured cable, or if it is plain redstone, and whether the cable is on or off (true or false). Rather then explaining it, I'll provide examples:

Documentation:

Spoiler

Basic usage

Spoiler

Example 1: You have a redstone wire right side of a computer/turtle, but not currently activated, while using this code:

local event, side, type, value = rshelp.pullEvent()
print("Event: ", event)
print("Side: ", side)
print("Type: ", type)
print("Value: ", tostring(value))

You then activate the wire by placing a redstone torch next to it. The output would be:

Event: redstone
Side: right
Type: rs
Value: true

If the code is ran again, then the redstone input is turned off, the output would be:

Event: redstone
Side: right
Type: rs
Value: false

Example 2: You have a bundled cable on the front of the computer, with a blue wire attached, but not currently activated. If you then activate the wire, the code will return the below

Event: redstone
Side: front
Type: blue
Value: true

Advanced usage

Spoiler

Example 1: You have a redstone wire right side of a computer/turtle, but not currently activated. But imagine you only want to do something when the redstone wire is activated. That would require an if statement, right? Wrong! See below example code:

while true do
	rshelp.pullEvent(false, true, "right", "rs", true)
	print("Redstone on the right side activated!")
end

First, let me explain the arguments that I passed to the function.
false - this is an optional argument which specifies if the pullEvent can be terminated. Because I've specified false (the default) then it CAN be terminated.
true - this is an optional argument which specifies if it will exclusively return redstone events. As I've specified true, it will only wait for redstone events.
"right" - the side to listen on.
"rs" - the type of signal to listen to. Can be "rs" or any colour.
true - the type of value to listen to. Can be true or false. It is possible to only do something when a signal is turned OFF by specifying false.

The above code loops, and prints "Redstone on the right side activated!" whenever the redstone on the right side is, well, activated.
Example 2: You have a bundled cable, and wish to listen only for a yellow signal on the front side. However, you also want to listen for "q" being pressed, but do not wish to allow termination using Ctrl+T. The use of this API simplifies the code needed. See below example code:

local event, param1
while true do
	event, param1 = rshelp.pullEvent(true, false, "front", "yellow", true)
	if event == "char" and param1 == "q" then
		break
	elseif event == "redstone" then
		print("Yellow wire activated!")
	end
end

Bonus feature:

Spoiler

Because I happened to be messing around with metatables at the time I was writing this API, I implemented a metatable to get the current redstone state. Please see below examples if you want to find whether the yellow cable on the front is currently active, you can simply type this:

if rshelp.state.front.yellow == true then print("Yellow on!") else print("Yellow off!") end

This works with all the colours and "rs" as plain redstone.

Get the API!

Spoiler

The API can be found here:

http://pastebin.com/6iSKf9uu

Simply save it to a file named "rshelp" in the API's directory in rom, and you are free to use it in your code!

Changelog

Spoiler

V1.1

• Fixed fail in termination prevention

V1.0

• Initial release

I hope you enjoy this and that it is useful. Please feel free to provide me with feedback or requests :)/>/> I am thinking of expanding it to provide more information on the peripheral event too, and expanding the metatable functionality, so watch this space!

Nice! Used this, help very much.
Do you mind if I reuse some of the code in the API?

Not at all, provided you state you use some of my code, or at least mention me somewhere!

Am I a idiot or is there no API to download :

Well you are an not idiot.Yes the download is mising..

D'oh! I have no idea what happened there people. Please feel free to download the API now :)/>/>

Nice work, very useful.

Thanks :P/>/> I plan to expand it when I get time and ideas! If you have any, please feel free to share.

It was pretty discouraging to be getting into writing a more involved program and then find that the rs API didn't already have this functionality.

Then I searched for this and it'll save me a bunch of annoying code I wasn't looking forward to writing.

It's easier to use than the kludge I was starting to plan, too. Thanks for sharing this!