Simple Log File API

--[[
    Log API. This API allows calls to write errors, warnings, and information to a log file for later review

    @version 1.0, 24 September 2013, BIT
    @author  TheOriginalBIT, BIT

    License:

      COPYRIGHT NOTICE
      Copyright © 2013 Joshua Asbury a.k.a TheOriginalBIT [theoriginalbit@me.com]

      Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
      associated documentation files (the "Software"), to deal in the Software without restriction,
      including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
      copies of the Software, and to permit persons to whom the Software is furnished to do so,
      subject to the following conditions:

      - The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
      - Visible credit is given to the original author.
      - The software is distributed in a non-profit way.

      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
      WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
      COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
      ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--]]

local file
local nativeError = _G.error

--# internal function that writes to the log file
local function logWrite(output)
  if not file then
    nativeError("Log API not initialised!", 3)
  end
  file.writeLine(output)
  file.flush()
end

local callerThrowback = 5

--# gets the name of the calling file without the extension if present
local function getCaller()
  local ok, err = pcall(nativeError, "", callerThrowback)
  return err:match("(%a+)%.?.-:.-") or "unknown" --# extract file name, remove extension
end

--# get the line number the function in the API was called from in the calling file (used in error)
local function getCallerLineNumber()
  local ok, err = pcall(nativeError, "", callerThrowback)
  return err:match("%a+:(%d+).-") or 0
end

local function formatMessage(_type, needsLine, ...)
  if needsLine then
    return string.format("[%s] [%s:%d] [%s] %s", _type, getCaller(), getCallerLineNumber(), os.clock(), table.concat({...}, ' '))
  end
  return string.format("[%s] [%s] [%s] %s", _type, getCaller(), os.clock(), table.concat({...}, ' '))
end

--[[
    Opens the log file handle so that the API can function

    @param  filename  string  [optional] the name of the log file, if not supplied it takes on the name of the calling file and appends '.log'
--]]
function init(filename)
  file = fs.open(filename or getCaller()..".log", 'w')
  logWrite("============= LOG START =============")
end

--[[
    Logs an error string to the log file with the prefix of [ERROR] and the clock time

    @param  ...  any number of strings (or numbers) to output to the log file
--]]
function e(...)
  local msg = formatMessage("ERROR", true, ...)
  logWrite(msg)
end

--[[
    Logs a warning string to the log file with the prefix of [WARNING] and the clock time

    @param  ...  any number of strings (or numbers) to output to the log file
--]]
function w(...)
  local msg = formatMessage("WARNING", false, ...)
  logWrite(msg)
end

--[[
    Logs an information string to the log file with the prefix of [INFORMATION] and the clock time

    @param  ...  any number of strings (or numbers) to output to the log file
--]]
function i(...)
  local msg = formatMessage("INFO", false, ...)
  logWrite(msg)
end

--[[
    Writes the log end and closes the log file handle, should only be used when the program is about to end

    @param  ...  any number of strings (or numbers) to output to the log file
--]]
function close()
  logWrite("============== LOG END ==============")
  file.close()
  _G.error = nativeError
end

--[[
  An override to error that will make use of the Log API

  @param  (same as default error function)
--]]
function _G.error(msg, lvl)
  callerThrowback = 6 -- trick the caller system into not pointing here
  e(msg)
  callerThrowback = 5
  nativeError(msg, (lvl == 0 and 0 or lvl and (lvl + 1) or 2))
end