No replies to this topic

[Espen]

Description
It's a small utility API which extends the native turtle functions with events.

Whenever you execute one of these turtle functions, it creates an event along with some additional information.
I used this primarily for my own purposes, but thought someone might get a use out of it as well.
http://en.wikipedia.org/wiki/WTFPL

Exposed Functions
forward() (or any other movement function)

• Event-Values: "turtle", "forward", < true | false > (where "forward" changes depeding on the move function you used)
  
• Return-Values: < true | false > (like the native function)

select( slot )

• Event-Values: "turtle", "select", < true | false >, < slot >
  
• Return-Values: < true | false > (like the native function)

drop() or drop( quantity )

• Event-Values: "turtle", "drop", < true | false >, < slot >, < dropped amount >
  
• Return-Values: < true | false >, < slot >, < dropped amount >

Color Legend:
String
Boolean
Number

---

How to use?

• Save the API Code and make note of the filename, e.g. 'tev'
  
• Load the API within the program where you want to make use of it via os.loadAPI, e.g. os.loadAPI( "tev" )
  
• Then to call the API's functions just like the native turtle functions, but replace 'turtle' with 'tev', e.g.: tev.digDown()
  
• To listen to turtle events, create an event loop and pull four parameters from the event, e.g.:

  local event, operation, success, slot, amount = os.pullEvent()

  (See example program below for details)

---

API - Code
Pastebin: http://pastebin.com/tcNZNZyK
Direct-View:

Spoiler

-- Local aggregate-function for every turtle action except 'drop'.
local function executeOperation( sOperation, ... )
  local bSuccess = turtle[ sOperation ]( arg[1] )  -- As of CC 1.31, arg[1] is for 'slot' in turtle.select( slot )
  os.queueEvent( "turtle", sOperation, bSuccess, arg[1] )
  return bSuccess  -- Returning the success is sufficient for direct function calls.
end

-- Moving
function forward() return executeOperation( "forward" ) end
function back() return executeOperation( "back" ) end
function up() return executeOperation( "up" ) end
function down() return executeOperation( "down" ) end
function turnLeft() return executeOperation( "turnLeft" ) end
function turnRight() return executeOperation( "turnRight" ) end

-- Placing
function placeUp() return executeOperation( "placeUp" ) end
function place() return executeOperation( "place" ) end
function placeDown() return executeOperation( "placeDown" ) end

-- Detecting
function detectUp() return executeOperation( "detectUp" ) end
function detect() return executeOperation( "detect" ) end
function detectDown() return executeOperation( "detectDown" ) end

-- Digging
function digUp() return executeOperation( "digUp" ) end
function dig() return executeOperation( "dig" ) end
function digDown() return executeOperation( "digDown" ) end

-- Comparing
function compareUp() return executeOperation( "compareUp" ) end
function compare() return executeOperation( "compare" ) end
function compareDown() return executeOperation( "compareDown" ) end

-- Slot Selecting
function select( nSlot ) return executeOperation( "select", nSlot ) end

-- Dropping
function drop( quantity )
  local bSuccess
  local nSlot = 1  -- Init not necessary in this case, but just to be safe.
  local nAmountDropped = 0  -- Init not necessary in this case, but just to be safe.
  local tOldItemSpace = {}
  -- Get current slot-space amount for all slots.
  for i = 1, 9 do
	tOldItemSpace[i] = turtle.getItemSpace(i)
  end
  -- Execute drop.
  if quantity then
	bSuccess = turtle.drop( quantity )
  else
	bSuccess = turtle.drop()
  end
  -- Check which slot dropped the items and how many were dropped.
  for i = 1, 9 do
	nSlot = i
	nAmountDropped = turtle.getItemSpace(i) - tOldItemSpace[i]
	if nAmountDropped > 0 then break end
  end
  -- Don't queue these parameters if the drop was unsuccessful.
  if not bSuccess then
	nSlot = nil
	nAmountDropped = nil
  end
  -- Queue event with the previously assembled information.
  os.queueEvent( "turtle", "drop", bSuccess, nSlot, nAmountDropped )
  return bSuccess, nSlot, nAmountDropped
end

---

Example Program to try out the API
Save the API from above as "tev".
Then run the program below. Pressing "e" will exit the program.
For all other keys see the code, there are quite a few. I mapped every turtle function to a key.
Pastebin: http://pastebin.com/mKsVVPFL
Direct-View:

Spoiler

-- Load API
os.loadAPI("tev")
if not tev then
  error( "Turtle Event API not loaded!" )
end

--[[ === MAIN LOOP === ]]
while true do
  local event, p1, p2, p3, p4 = re.pullEvent()

  if event == "turtle" then
	print( event..", "..tostring( p1 )..", "..tostring( p2 )..", "..tostring( p3 )..", "..tostring( p4 ) )
  end

  -- Moving
  if event == "key" and p1 == 200 then tev.forward() end  -- UP
  if event == "key" and p1 == 208 then tev.back() end  -- DOWN
  if event == "key" and p1 == 57 then tev.up() end  -- SPACE
  if event == "key" and p1 == 42 then tev.down() end  -- LSHIFT
  if event == "key" and p1 == 203 then tev.turnLeft() end  -- LEFT
  if event == "key" and p1 == 205 then tev.turnRight() end  -- RIGHT
  -- Placing
  if event == "key" and p1 == 71 then tev.placeUp() end  -- NUMPAD 7
  if event == "key" and p1 == 75 then tev.place() end  -- NUMPAD 4
  if event == "key" and p1 == 79 then tev.placeDown() end  -- NUMPAD 1
  -- Detecting
  if event == "key" and p1 == 72 then tev.detectUp() end  -- NUMPAD 8
  if event == "key" and p1 == 76 then tev.detect() end  -- NUMPAD 5
  if event == "key" and p1 == 80 then tev.detectDown() end  -- NUMPAD 2
  -- Digging
  if event == "key" and p1 == 73 then tev.digUp() end  -- NUMPAD 9
  if event == "key" and p1 == 77 then tev.dig() end  -- NUMPAD 6
  if event == "key" and p1 == 81 then tev.digDown() end  -- NUMPAD 3
  -- Comparing
  if event == "char" and string.lower( p1 ) == "q" then tev.compareUp() end
  if event == "char" and string.lower( p1 ) == "a" then tev.compare() end
  if event == "char" and string.lower( p1 ) == "y" then tev.compareDown() end
  -- Dropping
  if event == "char" and string.lower( p1 ) == "g" then tev.drop() end
  if event == "char" and string.lower( p1 ) == "b" then tev.drop(5) end
  -- Selecting
  if event == "char" and string.lower( p1 ) == "x" then tev.select(1) end
  if event == "char" and string.lower( p1 ) == "c" then tev.select(2) end
  -- Stopping program
  if event == "char" and string.lower( p1 ) == "e" then break end
end

-- Cleanup
os.unloadAPI( tev )