Vous avez re莽u un message "Your GitLab account has been locked ..." ? Pas d'inqui茅tude : lisez cet article https://docs.gricad-pages.univ-grenoble-alpes.fr/help/unlock/

Commit e18f05f4 authored by Alexis Brenon's avatar Alexis Brenon
Browse files

馃毀馃摑 Complete documentation

parent d285cf21
--- Add some useful functions to lualogging module.
-- @module utils.logging
--- A logger class.
--
-- A class that can be used by any object to instanciate dedicated logger.
-- See documentation of Python logging facility to see what I tried to
-- achieve.
--
-- This class also contains a @{main_logger|default/main logger} as a
-- static field for quick and dirty logging.
-- @classmod utils.Logger
-- @alias class
-- @author Alexis BRENON <alexis.brenon@imag.fr>
local torch = require('torch')
......@@ -7,6 +15,28 @@ local torch = require('torch')
local module = {}
local class = torch.class('Logger', module)
--- Fields
-- @section field
--- Name of the logger to identify it.
-- @tfield string name
--- Function used to format log message.
-- @tfield function formatter
--- Output stream used by the logger.
-- @tfield io.file_descripton output
--- Current logging level.
-- @tfield integer level_value
--- @section end
--- Class constructor.
-- @tparam string name @{name|Name} of the logger
-- @param[opt=default_level_value] level Logging level (string or integer) to use
-- @tparam[opt=timestamp_output] function formatter Function used to format log message
-- @tparam[opt=default_output] io.file_descriptor output Stream to use as logger output
function class:__init(name, level, formatter, output)
self.name = name
self.formatter = formatter or self.timestamp_output
......@@ -14,6 +44,15 @@ function class:__init(name, level, formatter, output)
self:set_level(level or class.default_level_value)
end
--- Public Methods
-- @section public-methods
--- Change logging level.
--
-- Change the current logging level to the given `level` witch can be passed as
-- @{level_values|integer} or @{level_strings|string} values.
-- @param level Logging level to use
-- @return `self`
function class:set_level(level)
local int_level, str_level = self.get_levels(level)
self.level_value = int_level
......@@ -21,10 +60,38 @@ function class:set_level(level)
return self
end
--- Get logging level.
--
-- Return current logging level as
-- @{level_values|integer} and @{level_strings|string} values.
-- @treturn integer Current logging integer value
-- @treturn string Current logging string value
function class:get_level()
return self.get_levels(self.level_value)
end
--- Change the output.
-- @tparam[opt=nil] string filename Log to the given file or `io.stdout` if `nil`
function class:set_output(filename)
self:info("Updating log output: " .. filename or "stdout")
if filename then
self.output = io.open(filename, "a")
else
self.output = io.output
end
end
--- Log a message.
--
-- Generate a log message with the given `level`, and print it if current logging level allows it.
--
-- A function is also defined for each log level, using a lower cased version of @{level_strings} values.
-- @usage logger:log("DEBUG", ...)
-- -- equivalent to
-- logger:debug(...)
-- @param level Message level as @{level_values|integer} or @{level_strings|string} value.
-- @param ... Data to format and log. See @_get_log_message.
-- @return self
function class:log(level, ...)
local int_level, _ = self.get_levels(level)
if int_level >= self.level_value then
......@@ -35,6 +102,19 @@ function class:log(level, ...)
return self
end
--- Print a progressing wheel.
-- @warn This function is only available for the @{main_logger}.
-- @tparam[opt] integer step Step number to display
-- @function progress
--- Private Methods
-- @section private-methods
--- Build and format a log message.
-- @tparam integer int_level Integer value of the level of the message
-- @tparam string str_format Base string to format
-- @param ... Values used for formatting
-- @treturn string Formatted log message
function class:_get_log_message(int_level, str_format, ...)
local msg = str_format
local str_level = self._get_level_string(int_level)
......@@ -48,20 +128,36 @@ function class:_get_log_message(int_level, str_format, ...)
return self:_format(str_level, msg)
end
--- Add logger informations to log message.
-- @tparam string str_level String value of the message level
-- @tparam string msg User log message
-- @treturn string Logger formatted message
function class:_format(str_level, msg)
return self:formatter(str_level, msg)
end
--- Change the output of the logging facilities.
-- @tparam[opt=nil] string filename Log to the given file or stdout if <code>nil</code>
function class:set_output(filename)
self:info("Updating log output: " .. filename or "stdout")
if filename then
self.output = io.open(filename, "a")
else
self.output = io.output
end
end
--- Static Fields
-- @section static-fields
--- Available log levels.
--
-- String representations of the log levels.
-- @table level_strings
-- @tfield string DEBUG
-- @tfield string INFO
-- @tfield string WARN
-- @tfield string ERROR
-- @tfield string FATAL
--- Available log levels.
--
-- Integer representations of the log levels.
-- @table level_values
-- @tfield integer 10
-- @tfield integer 20
-- @tfield integer 30
-- @tfield integer 40
-- @tfield integer 50
class.level_strings = {"DEBUG", "INFO", "WARN", "ERROR", "FATAL"}
class.level_values = { 10, 20, 30, 40, 50 }
......@@ -72,10 +168,32 @@ for i, _ in ipairs(class.level_strings) do
end
end
--- Default output.
--
-- Output used by default by new logger instances.
-- @tfield io.file_descriptor default_output `io.stdout`
class.default_output = io.stdout
--- Default log level.
--
-- Log level used by default by new logger instances.
-- @tfield integer default_level_value 20
class.default_level_value = 20
-- Static functions
--- Default logger.
--
-- A pre-instanciated logger for quick and dirty logging.
-- @tfield Logger main_logger
--- Static Functions
-- @section static-functions
--- Standard log formatter function.
--
-- The default standard log formatter function, adding timestamp, message level, file and line of issuing code.
-- @tparam Logger self The logger object
-- @tparam string level @{level_strings|String} representation of message level
-- @tparam string msg User log message
-- @treturn string Logger formatted message
function class.timestamp_output(self, level, msg)
local result = ""
if class.need_lf then result = result .. "\n" end
......@@ -91,6 +209,9 @@ function class.timestamp_output(self, level, msg)
return result
end
--- Set default log level.
-- @param level Level value as @{level_values|integer} or @{level_strings|string} value.
-- @see default_level_value
function class.set_default_level(level)
local int_level, str_level = class.get_levels(level)
class.main_logger:debug("Updating default level to: " .. str_level)
......@@ -98,6 +219,8 @@ function class.set_default_level(level)
class.main_logger:set_level(int_level)
end
--- Set default output.
-- @tparam[opt=nil] string f Name of the file to use as output or `nil` to set `io.stdout`
function class.set_default_output(f)
class.main_logger:info("Updating log output: " .. f or "stdout")
if f then
......@@ -108,9 +231,9 @@ function class.set_default_output(f)
end
--- Return a string representation of a integer debug level (similar to Python ones).
-- @tparam int int_level Debug level as an integer between 0 an 50
-- @treturn string The name of the debug level suitable for lualogging
--- Get string representation of an integer log level.
-- @tparam integer int_level Log level as an @{level_values|integer}
-- @treturn string The @{level_strings|string} representation of the log level
function class._get_level_string(int_level)
for i, v in ipairs(class.level_values) do
if int_level <= v then
......@@ -120,6 +243,9 @@ function class._get_level_string(int_level)
return class.level_strings[1] -- Emergency case
end
--- Get integer representation of a string log level.
-- @tparam string str_level The @{level_strings|string} representation of the log level
-- @treturn integer Log level as an @{level_values|integer}
function class._get_level_value(str_level)
for i, v in ipairs(class.level_strings) do
if str_level == v then
......@@ -129,6 +255,10 @@ function class._get_level_value(str_level)
return class.level_values[1] -- Emergency case
end
--- Get representations of the given level.
-- @param level Log level as @{level_values|integer} or @{level_strings|string} value.
-- @treturn integer Log level as @{level_values|integer}
-- @treturn string Log level as @{level_strings|string}
function class.get_levels(level)
if type(level) == "number" then
return level, class._get_level_string(level)
......@@ -143,8 +273,6 @@ main_logger.wheel = {"|", "/", "-", "\\"}
main_logger.wheel_step = 0
main_logger.last_step = 0
--- Function to print a progressing wheel.
-- @tparam[opt] int step Step number to display
function main_logger:progress(step)
if class.need_lf then self.output:write("\b\b\b\b\b\b\b\b\b\b\b") end
self.last_step = step or self.last_step
......@@ -158,7 +286,6 @@ function main_logger:progress(step)
class.need_lf = true
end
--- Default logger that can be used by any module.
class.main_logger = main_logger
return module.Logger
--- Argument parser class
--- Argument parser class.
-- Declare arguments used by ARCADES.
-- @todo Don't rely on a class declaration (just a module instead).
-- @todo Use config file instad of complicated command line arguments.
-- @author Alexis BRENON <alexis.brenon@imag.fr>
-- @classmod utils.argparse.Parser
-- @alias class
......@@ -96,21 +99,22 @@ end
local indent = ""
--- Private methods
--- Private Methods
-- @section private-methods
--- Add elements from a table to the parser.
--
-- There are 3 different element type, <code>text</code> which is just displayed
-- in the usage description, <code>option</code> that is the top level option
-- (it must be preceded by a hash) and <code>field</code> if it is a suboption
-- that is contained in a table.
-- There are 3 different element type:
--
-- * `text` which is just displayed in the usage description;
-- * `option` that is the top level option (it must be preceded by a dash);
-- * `field` if it is a suboption that is contained in a table.
--
-- Text elements are of the form:<br/>
-- <code>{"text", "my very useful piece of text"}</code>
-- `{"text", "my very useful piece of text"}`
--
-- Option and field elements are of the form:<br/>
-- <code>{"option"|"field", "option_name", default value, "Description", "type"}</code>
-- `{"option"|"field", "option_name", default value, "Description", "type"}`
--
-- @tparam table elements A table representing the element.
function class:_add_elements(elements)
......@@ -141,13 +145,13 @@ function class:_add_elements(elements)
indent = old_indent
end
--- This function will parse a string in depth.
--- Parse a string in depth.
--
-- Given the description of the arguments and the actual parsing result, it will
-- go deeper, casting string to the right type. This function works recurcivelly.
-- go deeper, casting string to the right type. This function works recursivelly.
-- @tparam table description The description of the arguments
-- @tparam table input Result of the previous parsing
-- @treturn table <code>input</code> parsed according to the <code>description</code>
-- @treturn table `input` parsed according to the `description`
function class:_format(description, input)
local output = {}
for _, e in ipairs(description) do
......@@ -195,10 +199,10 @@ function class:_format(description, input)
return output
end
--- Public methods
--- Public Methods
-- @section public-methods
--- Actually parse arg
--- Actually parse `arg`
-- @tparam string arg Arguments string to parse
-- @treturn table Parsed arguments
function class:parse(arg)
......
--- Foreign function interface management.
--
-- Handle unique declaration of C functions
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local ffi = require('ffi') -- Lua <-> C bindings
-- Do the FFI definition once
......@@ -33,6 +38,16 @@ local function load_lib(alt_names)
end
end
---Table of the `gobject` library's function
-- @table gobject
---Table of the `cairo` library's function
-- @table cairo
---Table of the `rsvg` library's function
-- @table rsvg
--- @export
return {
gobject = load_lib({
'gobject',
......
--- A set of utilities functions and classes.
--- A set of utilities modules and classes.
-- @package utils
-- @author Alexis BRENON <alexis.brenon@imag.fr>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment