Turtle Events API

-- 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