helper v1.0

local version = 1.0
--- Debugging Mode
-- <code>true</code> enabled, <code>false</code> disabled
-- @class table
-- @name debugging
-- @field debugging enables debugging by setting to <code>true</code>
local debugging = false

--- Table with positions<br>
-- <code>"top", "t", "center", "c", "bottom", "b", "left", "l", "right", "r"</code>
-- @class table
-- @name validPositions
-- @field validPositions Table with valid positions, needed for <code>isValidPosition()</code>
local validPositions = {"top", "t", "center", "c", "bottom", "b", "left", "l", "right", "r"}


--- Prints a debug message
-- Only print of @field debugging is true
-- @param source The source of the debug messsage
-- @param msg The actual message
function debug_print(source, msg)
    if debugging then
        print("DEBUG: '" .. source .."': " .. msg)
    end
end

--- Prints errors in red color and sets text color to white again
-- @param msg   The error message
function printError(msg)
    term.setTextColor(colors.red)
    print(msg)
    term.setTextColor(colors.white)
end

--[[ rPrint(struct, [limit], [indent]) Recursively print arbitrary data.
Set limit (default 100) to stanch infinite loops.
Indents tables as [KEY] VALUE, nested tables as [KEY] [KEY]...[KEY] VALUE
Set indent ("") to prefix each line: Mytable [KEY] [KEY]...[KEY] VALUE
--]]
function rPrint(s, l, i) -- recursive Print (structure, limit, indent)
    l = (l) or 100; i = i or "";    -- default item limit, indent string
    if (l<1) then print "ERROR: Item limit reached."; return l-1 end;
    local ts = type(s);
    if (ts ~= "table") then print (i,ts,s); return l-1 end
    print (i,ts); -- print "table"
    for k,v in pairs(s) do -- print "[KEY] VALUE"
        l = rPrint(v, l, i.."\t["..tostring(k).."]");
        if (l < 0) then break end
    end
    return l
end

--- Checks if an element is in a table.
-- (<a href=http://stackoverflow.com/questions/2282444/how-to-check-if-a-table-contains-an-element-in-lua>Source</a>)
-- @param table the table that should be searched in
-- @param element the element that should be tested
function table.contains(table, element)
  for _, value in pairs(table) do
    if value == element then
      return true
    end
  end
  return false
end

--- Formats <code>text</code> to fit into <code>width</code>, filling missing characters with
-- <code>fillchar</code> and also applies <code>orientation</code>
-- @param text  The text
-- @param width The length of the returned string
-- @param fillchar  Char to fill the "spaces"
-- @param orientation   Orientation of the text (<code>"center", "c", "left", "l", "right", "r"</code>)
function formatText(text, width, fillchar, orientation)
    local validOrientations = {"left", "l", "right", "r", "center", "c" }
    text = tostring(text)
    if #text >= width then
        return string.sub(text, 1, width), string.sub(text, width + 1)
    end

    if table.contains(validOrientations, orientation) then
        local value = ""
        local diff = width - #text
        if orientation == "left" or orientation == "l" then
            value = text .. string.rep(fillchar, diff)
            return value
        elseif orientation == "right" or orientation == "r" then
            value = string.rep(fillchar, diff) .. text
            return value
        elseif orientation == "center" or orientation == "c" then
            local leftside = math.floor(diff/2)
            local rightside = math.ceil(diff/2)
            value = string.rep(fillchar, leftside) .. text .. string.rep(fillchar, rightside)
            return value
        end
    end
    return text
end

--- Validaes the position
-- @param position  string: the position
-- @return true - valid, false - not valid
function isValidPosition(position)
    for _, value in pairs(validPositions) do
        if value == position then
            return true
        end
    end
    return false
end

--- Creates a table with a range numbers
-- @param startval  Star value
-- @param endval    End value
-- @param steps     Stepping
-- @return Table with range of number values
-- @usage createNumberList(0, 10, 2) -> {0,2,4,6,8,10}
function createNumberList(startval, endval, steps)
    local list = {}
    local index = 1
    for i = startval, endval, steps do
        list[index] = i
        index = index + 1
    end
    return list
end

--- Returns the length of the longest element in a table
-- Turn the elements to strings and compares the lengths
-- @param list  The list
-- @return Length of longest element
function longestElement(list)
    local length = 0
    for _, value in pairs(list) do
        if #tostring(value) > length then
            length = #tostring(value)
        end
    end
    return length
end