Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
Alexis Brenon
arcades
Commits
e18f05f4
Commit
e18f05f4
authored
Jan 31, 2018
by
Alexis Brenon
Browse files
🚧
📝
Complete documentation
parent
d285cf21
Changes
4
Hide whitespace changes
Inline
Side-by-side
arcades/utils/Logger.lua
View file @
e18f05f4
--- 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
---
R
et
urn a
string representation of a integer
debu
g level
(similar to Python ones)
.
-- @tparam int int_level
Debu
g level as an
integer between 0 an 50
-- @treturn string The
name
of the
debu
g level
suitable for lualogging
---
G
et string representation of a
n
integer
lo
g level.
-- @tparam int
eger
int_level
Lo
g level as an
@{level_values|integer}
-- @treturn string The
@{level_strings|string} representation
of the
lo
g 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
arcades/utils/argparse.lua
View file @
e18f05f4
--- 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
m
ethods
--- Private
M
ethods
-- @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 p
arse a string in depth.
---
P
arse 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 recur
c
ivelly.
-- go deeper, casting string to the right type. This function works recur
s
ivelly.
-- @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
m
ethods
--- Public
M
ethods
-- @section public-methods
--- Actually parse arg
--- Actually parse
`
arg
`
-- @tparam string arg Arguments string to parse
-- @treturn table Parsed arguments
function
class
:
parse
(
arg
)
...
...
arcades/utils/ffi_cdef.lua
View file @
e18f05f4
--- 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'
,
...
...
arcades/utils/init.lua
View file @
e18f05f4
--- A set of utilities
function
s and classes.
--- A set of utilities
module
s and classes.
-- @package utils
-- @author Alexis BRENON <alexis.brenon@imag.fr>
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment