RobustTurtleAPI

----------------------------------------------
--------------Robust Turtle API---------------
----------------------------------------------

--[[Same as turtle.dig() but guarantees
    that there will be no Block in front
    of the turtle afterwards.
]]--
function dig()
  success = false
  while turtle.dig() do
    success = true
    os.sleep(0.05)
  end
  return success
end

--[[Same as turtle.digUp() but guarantees
    that there will be no Block above the
    turtle afterwards.
]]--
function digUp()
  success = false
  while turtle.digUp() do
    success = true
    os.sleep(0.05)
  end
  return success
end

--[[Same as turtle.digDown().
    Included for user-friendliness
]]--
function digDown()
  return turtle.digDown()
end

--[[Robust version of turtle.forward().
    Refuels if it needs to, removes the
    obstructing block if there is one
    and kills mobs or players that prevent
    it from moving.
]]--
function _forward()
  while not turtle.forward() do
    if turtle.getFuelLevel() == 0 then
      if not refuel() then
        term.write("Please insert fuel into my inventory.\n Sleeping...")
        os.pullEvent()
      end
    elseif not dig() then
      turtle.attack()
    end
  end
end

--[[See _forward().
    @param distance
      Number of Blocks to move.
]]--
function forward(distance)
  distance = distance or 1
  for i = 1, distance do
    _forward()
  end
end

--[[Robust version of turtle.up().
    Refuels if it needs to, removes the
    obstructing block if there is one
    and kills mobs or players that prevent
    it from moving.
]]--
function _up()
  while not turtle.up() do
    if turtle.getFuelLevel() == 0 then
      refuel()
    elseif not digUp() then
      turtle.attackUp()
    end
  end
end

--[[See _up().
    @param distance
      Number of Blocks to move.
]]--
function up(distance)
  distance = distance or 1
  for i = 1, distance do
    _up()
  end
end

--[[Robust version of turtle.down().
    Refuels if it needs to, removes the
    obstructing block if there is one
    and kills mobs or players that prevent
    it from moving.
]]--
function _down()
  while not turtle.down() do
    if turtle.getFuelLevel() == 0 then
      refuel()
    elseif not digDown() then
      turtle.attackDown()
    end
  end
end

--[[See _down().
    @param distance
      Number of Blocks to move.
]]--
function down(distance)
  distance = distance or 1
  for i = 1, distance do
    _down()
  end
end

--[[Robust version of turtle.back().
    Refuels if it needs to, removes the
    obstructing block if there is one
    and kills mobs or players that prevent
    it from moving.
]]--
function _back()
  if not turtle.back() then
    turnAround()
    forward()
    turnAround()
  end
end

--[[See _back().
    @param distance
      Number of Blocks to move.
]]--
function back(distance)
  distance = distance or 1
  for i = 1, distance do
    _back()
  end
end

--[[Type safe version of turtle.getFuelLevel().
    Always returns a number.
    Returns 1,000,000,000 if 'turtlesNeedFuel'
    is set to false in the config.
]]--
function getFuelLevel()
  local fuelLevel = turtle.getFuelLevel()
  if fuelLevel == "unlimited" then
    return 1000000000
  else
    return fuelLevel
  end
end

----------------------------------------------
-----------Direction track-keeping------------
----------------------------------------------
local DIRECTIONS = {"north", "east", "south", "west", ["north"] = 1, ["east"] = 2, ["south"] = 3, ["west"] = 4}
local _direction = DIRECTIONS["north"]

local function remainder(dividend, divisor)
  return dividend - floor(dividend/divisor+0.5)*divisor
end

--[[Equivalent to turtle.turnRight() but
    updates the _direction variable and
    doesn't return success as it would
    always be true anyways.
]]
function right()
  turtle.turnRight()
  _direction = _direction % 4 + 1
end

--[[Analog to right()
]]
function left()
  turtle.turnLeft()
  _direction = (_direction - 2) % 4 + 1
end

--[[Turns the turtle in order to face
    a given direction.
]]
function face(direction)
  assert(type(direction) == string, "Expected string got "..type(direction))
  direction = DIRECTIONS[direction]
  local action = remainder(direction - _direction, 4)
  if action == 0 then
    return
  elseif action == 1 then
    return right()
  elseif action == -1 then
    return left()
  else
    return turn()
  end
end

--[[Sets the direction the turtle is
    currently facing.
]]
function setDirection(direction)
  assert(type(direction) == string, "Expected string got "..type(direction))
  _direction = DIRECTIONS[direction]
end

--[[Gets the direction the turtle is
    currently facing.
]]
function getDirection()
  return DIRECTIONS[_direction]
end

----------------------------------------------
---------------QoL Improvements---------------
----------------------------------------------

--[[The turtle turns by 180°.
]]--
function turnAround()
  left()
  left()
end

--[[QoL improvement for turtle.place().
    Tries placing a block from the given slot.
]]--
function place(slot)
  slot = slot or 1
  turtle.select(slot)
  return turtle.place()
end

--[[Analog to place().
]]--
function placeUp(slot)
  slot = slot or 1
  turtle.select(slot)
  return turtle.placeUp()
end

--[[Analog to place().
]]--
function placeDown(slot)
  slot = slot or 1
  turtle.select(slot)
  return turtle.placeDown()
end

--[[Helper function for the drop functions
    to reduce redundancy.]]
local function _drop(slot, dropFunc)
  local selectedSlot = turtle.getSelectedSlot()
  slot = slot or selectedSlot
  turtle.select(slot)
  local success = dropFunc() or turtle.getItemCount() == 0
  turtle.select(selectedSlot)
  return success
end

--[[Alternative to turtle.drop().
    Takes a slot to drop items from as
    argument instead of a quantity.
    Will always try to drop the entire stack.
    Only returns false when it can't drop items
    not when there are no items to drop to begin
    with.
]]--
function drop(slot)
  return _drop(slot, turtle.drop)
end

--[[Analog to drop().
]]--
function dropUp(slot)
  return _drop(slot, turtle.dropUp)
end

--[[Analog to drop().
]]--
function dropDown(slot)
  return _drop(slot, turtle.dropDown)
end


--[[Automatically chooses a slot to refuel from.
]]--
function refuel(toFuel)
  for slot = 1, 16 do
    turtle.select(slot)
    if turtle.refuel(toFuel or turtle.getItemCount()) then
      return true
    end
  end
  return false
end