my version of computercraft's Excavate program

-- this does not belong to me.
-- most of it came from the ComputerCraft wiki and is presumably under the same license as ComputerCraft itself
-- I just added some comments and a condition to stop at a certain depth
local tArgs = { ... }
local targetDepth
if #tArgs < 1 then
    print( "Usage: excavate <diameter> [targetDepth]" )
    return
elseif #tArgs == 2 then
    targetDepth = tonumber ( tArgs[2] )
end

-- Mine in a quarry pattern until we hit something we can't dig
local size = tonumber( tArgs[1] )
if size < 1 then
    print( "Excavate diameter must be positive" )
    return
end

local depth = 0       --this keeps track of how far we had descended from our starting position
local unloaded = 0    --this keeps track of how much we have unloaded, and is updated by unload()
local collected = 0   --this keeps track of how many items we have on board, and is updated by collect()

local xPos,zPos = 0,0 --these store the turtle's location within its own relativistic world grid
local xDir,zDir = 0,1 --these are a direction vector that assumes we face positive Z initially
                      --(but whether this is true is irrelevant since the API calls for checking the "real"
                      --location are never utilized. We just track our location and direction internally)

local goTo -- Filled in further down
local refuel -- Filled in further down

local function unload( _bKeepOneFuelStack )
    print( "Unloading items..." )
    for n=1,16 do
        local nCount = turtle.getItemCount(n)
        if nCount > 0 then
            turtle.select(n)
            local bDrop = true
            if _bKeepOneFuelStack and turtle.refuel(0) then
                bDrop = false
                _bKeepOneFuelStack = false
            end
            if bDrop then
                turtle.drop()
                unloaded = unloaded + nCount
            end
        end
    end
    collected = 0
    turtle.select(1)
end

local function returnSupplies()
    local x,y,z,xd,zd = xPos,depth,zPos,xDir,zDir
    print( "Returning to surface..." )
    goTo( 0,0,0,0,-1 )

    local fuelNeeded = 2*(x+y+z) + 1
    if not refuel( fuelNeeded ) then
        unload( true )
        print( "Waiting for fuel" )
        while not refuel( fuelNeeded ) do
            os.pullEvent( "turtle_inventory" )
        end
    else
        unload( true )
    end

    print( "Resuming mining..." )
    goTo( x,y,z,xd,zd )
end

local function collect()    --checks if inventory has an open slot
    local bFull = true --assume backpack is full until disproven
    local nTotalItems = 0 --start a count of items
    for n=1,16 do
        local nCount = turtle.getItemCount(n)
        if nCount == 0 then
            bFull = false
        end
        nTotalItems = nTotalItems + nCount --to count how much we have on hand
    end

    if nTotalItems > collected then
        collected = nTotalItems
        if math.fmod(collected + unloaded, 50) == 0 then
            print( "Mined "..(collected + unloaded).." items." )
        end
    end

    if bFull then
        print( "No empty slots left." )
        return false
    end
    return true
end

function refuel( amount ) -- checks if we have enough fuel, and if not, search the inventory for valid fuels
    local fuelLevel = turtle.getFuelLevel()
    if fuelLevel == "unlimited" then
        return true -- if fuel requirements are disabled for any reason, this function always returns true
    end

    local needed = amount or (xPos + zPos + depth + 2) -- if amount isn't specified, estimate how much we need to get "home"
    if turtle.getFuelLevel() < needed then
        local fueled = false
        for n=1,16 do
            if turtle.getItemCount(n) > 0 then
                turtle.select(n)
                if turtle.refuel(1) then
                    while turtle.getItemCount(n) > 0 and turtle.getFuelLevel() < needed do
                        turtle.refuel(1)
                    end
                    if turtle.getFuelLevel() >= needed then
                        turtle.select(1) -- reset the inventory cursor
                        return true
                    end
                end
            end
        end
        turtle.select(1)
        return false -- if the fuel requirements could not be met, refuel failed
    end

    return true
end

local function tryForwards()
    if not refuel() then -- only move forward if we can get back from this location
        print( "Not enough Fuel" )
        returnSupplies()
    end

    while not turtle.forward() do -- keep trying to move forward (digging or attacking if necessary) until successful
        if turtle.detect() then --is there a block in front of us?
            if turtle.dig() then
                if not collect() then
                    returnSupplies()
                end
            else
                return false -- The block in front of us couldn't be broken
            end
        elseif turtle.attack() then --By the way, even with just a pickaxe, this thing hits decently hard
            if not collect() then
                returnSupplies()
            end
        else
            sleep( 0.5 )
        end
    end

    xPos = xPos + xDir -- adjust the turtle's memory of its location by the direction vector
    zPos = zPos + zDir -- see above
    return true
end

local function tryDown()
    if not refuel() then
        print( "Not enough Fuel" )
        returnSupplies()
    end

    while not turtle.down() do
        if turtle.detectDown() then
            if turtle.digDown() then
                if not collect() then
                    returnSupplies()
                end
            else
                return false
            end
        elseif turtle.attackDown() then
            if not collect() then
                returnSupplies()
            end
        else
            sleep( 0.5 )
        end
    end

    depth = depth + 1
    if math.fmod( depth, 10 ) == 0 then
        print( "Descended "..depth.." metres." )
    end

    return true
end

local function turnLeft() --this just updates the direction vector
    turtle.turnLeft()
    xDir, zDir = -zDir, xDir --this is pretty smart vector handling, TBH. I might have to remember this...
end

local function turnRight() --this just updates the direction vector
    turtle.turnRight()
    xDir, zDir = zDir, -xDir
end

function goTo( x, y, z, xd, zd ) --given a location and a current direction vector, go to location
    while depth > y do --first go up...
        if turtle.up() then
            depth = depth - 1
        elseif turtle.digUp() or turtle.attackUp() then --if something was in the way[...]
            collect()                                   --update the inventory manager. Isn't functional programming fun?
        else
            sleep( 0.5 )
        end
    end --note that this function does not give up if digging and/or attacking fail

    if xPos > x then --if we need to go toward negative X
        while xDir ~= -1 do --... but we aren't facing negative X
            turnLeft() --turn and update the vector
        end
        while xPos > x do --start moving left just like we did with up
            if turtle.forward() then
                xPos = xPos - 1
            elseif turtle.dig() or turtle.attack() then
                collect()
            else
                sleep( 0.5 )
            end
        end
    elseif xPos < x then --same as above, but we need to be facing positive X
        while xDir ~= 1 do
            turnLeft()
        end
        while xPos < x do
            if turtle.forward() then
                xPos = xPos + 1
            elseif turtle.dig() or turtle.attack() then
                collect()
            else
                sleep( 0.5 )
            end
        end
    end

    if zPos > z then
        while zDir ~= -1 do
            turnLeft()
        end
        while zPos > z do
            if turtle.forward() then
                zPos = zPos - 1
            elseif turtle.dig() or turtle.attack() then
                collect()
            else
                sleep( 0.5 )
            end
        end
    elseif zPos < z then
        while zDir ~= 1 do
            turnLeft()
        end
        while zPos < z do
            if turtle.forward() then
                zPos = zPos + 1
            elseif turtle.dig() or turtle.attack() then
                collect()
            else
                sleep( 0.5 )
            end
        end
    end

    while depth < y do
        if turtle.down() then
            depth = depth + 1
        elseif turtle.digDown() or turtle.attackDown() then
            collect()
        else
            sleep( 0.5 )
        end
    end

    while zDir ~= zd or xDir ~= xd do
        turnLeft()
    end
end

if not refuel() then
    print( "Out of Fuel" )
    return
end
-- end of function definitions.

-- program entry point
print( "Excavating..." )

local reseal = false
turtle.select(1)
if turtle.digDown() then
    reseal = true
end

local alternate = 0
local done = false
while not done do
    for n=1,size do
        for m=1,size-1 do --clear a row
            if not tryForwards() then -- if it ran into something unbreakable
                done = true
                break
            end
        end
        if done then
            break
        end
        if n<size then --if we have more rows to clear
            if math.fmod(n + alternate,2) == 0 then --depending on the modulus of this row..
                turnLeft()
                if not tryForwards() then
                    done = true
                    break
                end
                turnLeft()
            else
                turnRight()
                if not tryForwards() then
                    done = true
                    break
                end
                turnRight()
            end
        end
    end
    if done then
        break
    end

    if size > 1 then
        if math.fmod(size,2) == 0 then
            turnRight()
        else
            if alternate == 0 then
                turnLeft()
            else
                turnRight()
            end
            alternate = 1 - alternate
        end
    end

    --this check is added temporarily because I want a version of this that only goes down to Y = 60
    local realX, realY, realZ = gps.locate()
    --if not realY then --If gps.locate didn't work, it won't return anything. So check to see if it did.
    --  print("Failed to get my location!")
    --end
    --if realY <= 60 then
    --  done = true
    --  break
    --end
    if (targetDepth ~= nil) and (depth >= targetDepth) then
        done = true
        break
    elseif not tryDown() then
        done = true
        break
    end
end

print( "Returning to surface..." )

-- Return to where we started
goTo( 0,0,0,0,-1 )
unload( false )
goTo( 0,0,0,0,1 )

-- Seal the hole
if reseal then
    turtle.placeDown()
end

print( "Mined "..(collected + unloaded).." items total." )