ComputerCraft Tutorial: h2turtle_API_0_1

local H2Turtle = {}
setmetatable(H2Turtle,{__index = turtle})

--[[
turtle.select( slotNum )
turtle.getSelectedSlot()
turtle.getItemCount( [slotNum] )
turtle.getItemSpace( [slotNum] )
turtle.equipLeft()
turtle.equipRight()
turtle.dig( [toolSide] )
turtle.digUp( [toolSide] )
turtle.digDown( [toolSide] )
turtle.place()
turtle.placeUp()
turtle.placeDown()
turtle.attack( [toolSide] )
turtle.attackUp( [toolSide] )
turtle.attackDown( [toolSide] )
turtle.detect()
turtle.detectUp()
turtle.detectDown()
turtle.compare()
turtle.compareUp()
turtle.compareDown()
turtle.compareTo( slotNum )
turtle.transferTo( slotNum, [quantity] )
turtle.drop( [quantity] )
turtle.dropUp( [quantity] )
turtle.dropDown( [quantity] )
turtle.suck( [quantity] )
turtle.suckUp( [quantity] )
turtle.suckDown( [quantity] )
turtle.getFuelLevel()
turtle.getFuelLimit()
turtle.refuel( [quantity] )
turtle.craft( [quantity] ) (requires Crafty Turtle)
--]]

H2Turtle.new = function()
  local obj = {}
  obj.direction = 0 -- 0-3, 0: start dir., 1: turn right, 2: two times, 3: three times
  obj.x = 0 -- side pos.
  obj.y = 0 -- height
  obj.z = 0 -- depth
  if turtle.select(1) then obj.slot = 1 end
  return setmetatable(obj,{__index = H2Turtle})
end

H2Turtle.turnRight = function(self, _n)
  _n = _n or 1
  if type(_n)=="number" and _n > 0 then
    for i=1,_n do
      turtle.turnRight()
    end
    self.direction = (self.direction + _n)%4
  elseif type(_n)=="number" and _n == 0 then
    -- do nothing.
  else
    assert(false, "Illegal argument: turnRight(n)")
  end
  return self.direction
end

H2Turtle.turnLeft = function(self, _n)
  _n = _n or 1
  if type(_n)=="number" and _n > 0 then
    for i=1,_n do
      turtle.turnLeft()
    end
    self.direction = (self.direction + (4-_n))%4
  elseif type(_n)=="number" and _n == 0 then
    -- do nothing.
  else
    assert(false, "Illegal argument: turnLeft(n)")
  end
  return self.direction
end

H2Turtle.select = function(self, _n)
  _n = _n or 0
  if type(_n)=="number" then
    if _n >= 1 and _n <= 16 then
      self.slot = _n
      turtle.select(self.slot)
    elseif _n == 0 then
      -- do nothing
    else
      assert(false, "select(n): n is 1..16")
    end
    return self.slot
  else
    assert(false, "select(n): n is integer")
  end
end

H2Turtle.selectRelative = function(self, _delta)
  _delta = _delta or 0
  if type(_delta)=="number" then
    local n = self.slot + _delta
    n = ((n-1) % 16) + 1 -- 1 < n < 16
    return self:select(n)
  end
end

H2Turtle.forward = function(self, n)
  local _forward = function(self)
    local _status, _err_msg
    for i=1,3 do
      _status, _err_msg = turtle.forward()
      if _status or (_err_msg ~= "Movement obstructed") then break end
      os.sleep(0.1)
    end
    if _status then
      if self.direction == 0 then
        self.z = self.z+1
      elseif self.direction == 1 then
        self.x = self.x+1
      elseif self.direction == 2 then
        self.z = self.z-1
      elseif self.direction == 3 then
        self.x = self.x-1
      end
    end
    return _status, _err_msg
  end

  -- main loop
  n = tonumber(n) or 1
  local status, err_msg
  for i=1, n do
    status, err_msg = _forward(self)
    if not status then break end
  end
  return status, err_msg
end

H2Turtle.back = function(self, n)
  local _back = function(self)
    local _status, _err_msg
    for i=1,3 do
      _status, _err_msg = turtle.back()
      if _status or (_err_msg ~= "Movement obstructed") then break end
      os.sleep(0.1)
    end
    if _status then
      if self.direction == 0 then
        self.z = self.z-1
      elseif self.direction == 1 then
        self.x = self.x-1
      elseif self.direction == 2 then
        self.z = self.z+1
      elseif self.direction == 3 then
        self.x = self.x+1
      end
    end
    return _status, _err_msg
  end

  -- main loop
  n = tonumber(n) or 1
  local status, err_msg
  for i=1, n do
    status, err_msg = _back(self)
    if not status then break end
  end
  return status, err_msg
end
H2Turtle.up = function(self, n)
  local _up = function(self)
    local _status, _err_msg
    for i=1,3 do
      _status, _err_msg = turtle.up()
      if _status or (_err_msg ~= "Movement obstructed") then break end
      os.sleep(0.1)
    end
    if _status then
        self.y = self.y+1
    end
    return _status, _err_msg
  end

  -- main loop
  n = tonumber(n) or 1
  local status, err_msg
  for i=1, n do
    status, err_msg = _up(self)
    if not status then break end
  end
  return status, err_msg
end
H2Turtle.down = function(self, n)
  local _down = function(self)
    local _status, _err_msg
    for i=1,3 do
      _status, _err_msg = turtle.down()
      if _status or (_err_msg ~= "Movement obstructed") then break end
      os.sleep(0.1)
    end
    if _status then
        self.y = self.y-1
    end
    return _status, _err_msg
  end

  -- main loop
  n = tonumber(n) or 1
  local status, err_msg
  for i=1, n do
    status, err_msg = _down(self)
    if not status then break end
  end
  return status, err_msg
end


H2Turtle.place = function(self, slot)
  H2Turtle.select(slot)
  return turtle.place()
end



-- shortened name
--[[
H2Turtle.fwd = H2Turle.forward
H2Turtle.tL = H2Turtle.turnLeft
H2Turtle.tR = H2Turtle.turnRight
H2Turtle.sel = H2Turtle.select
H2Turtle.selRel = H2Turtle.selectRelative
--]]

-- ##################################
-- API Functions
function new()
  return H2Turtle.new()
end