--- Main logging module for setting up logging, retrieve module loggers,
-- etc. Please consult the main example, @{config.lua}. You can run the example
-- with lua -l lloader ./examples/config.lua and any other examples with also
-- similar command.
--
-- A short description on each example follows:
--
-- @{config.lua}  - Initialising logua with a log4cpp properties config file, with basic logging
--
-- @{modules.lua} - Initialising different modules with different log levels
--
-- @{tables.lua}  - Logging tables
--
-- @{cyclic_tables.lua} - Logging tables that were made by strange people
--
-- @{log_priorities.lua} - Logging by specifying the log priority yourself
--
-- @module logua

local logua = {}

local logua_internal = require("logua_internal")

for k, v in pairs(logua_internal.get_priority_map()) do logua[k] = v end

--- configure logua with a config file
--
-- The config file should be a normal log4j style properties file.
-- See the example, @{config.lua}.
--
-- An example log4j properties file is also in the source tree,
-- see examples/test.conf.
--
-- @param config_file The path to the config file.
-- @return A string error on why the config failed or nil
function logua.init(config_file)
  local success, err = pcall(logua_internal.configure, config_file)
  if not success then
    return err
  else
    return nil
  end
end

--- Retrieve a logger for your module
--
-- The retrieved logger will behave in the way described by the 
-- config file you used when calling logua.init(). Consult 
-- @{modules.lua} and the associated config file to see how this happens.
--
-- @param module_name The name of your module. If you pass nil you
--   will retrieve the root logger.
-- @return A LoguaLogger for your module.
function logua.get_log(module_name)
  return logua_internal.get_log(module_name)
end

--- Get a string to int table map of log priorities for log4cpp
--
-- This is not very useful unless you need to dynamically set the log
-- priority of a log call.
--
-- @return A table of associated log4cpp priority names with log4cpp priority numbers.
function logua.get_priority_map()
  return logua_internal.get_priority_map()
end

return logua
