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 3b2a5567 authored by Alexis Brenon's avatar Alexis Brenon
Browse files

馃摑 Write Arcades_Components documentation

parent 0f2afbd3
--- Base package of the ARCADES project.
-- This is the base package of the ARCADES project.
-- As an exception to confirm the rule, this package not only discover
-- sub-packages, modules and class, but also define its own class.
-- This behavior should be fixed.
-- The class defined by this package (`ArcadesComponent`)
-- is a base class for any
--- Base of any ARCADES related object.
-- ArcadesComponent is a base class for any
-- ARCADES class, providing default behavior for logging,
-- string representation, dumping and loading.
-- @classmod Arcades_Components
-- @alias class
-- @author Alexis BRENON <alexis.brenon@imag.fr>
local torch = require('torch')
......@@ -19,6 +15,30 @@ local Logger = require('arcades.utils.Logger')
local arcades = require('arcades.utils.package_loader')(...)
local class = torch.class('ArcadesComponent', arcades)
--- Fields
-- @section fields
--- Table (shallow copy) of arguments used for instanciation
-- @tfield table self._args
--- Identifier name of the object
-- @tfield string self._name
--- List of attributes that does not need to be dumped
-- @tfield table self._no_dump_list
--- Object's logger
-- @see utils.Logger
-- @tfield utils.Logger self._logger
---
-- @section end
--- Object constructor.
--
-- Instanciate a new ARCADES object.
-- @tparam[opt={}] table args Table of attributes/arguments to pass to the object
-- @tparam[opt={}] table dump Dump of an object to re-instanciate
function class:__init(args, dump)
args = args or {}; dump = dump or {}
self._args = tablex.copy(args)
......@@ -32,17 +52,8 @@ function class:__init(args, dump)
self._logger:debug("Instanciating a new object")
end
function class:dump(cycles)
cycles = cycles or {}
if self._logger then self._logger:debug("Dumping...") end
cycles[torch.pointer(self)] = true
local args_dump = class._dump(self._args, cycles)
local dump = class._dump(self, cycles)
dump.classname = torch.typename(self)
dump._args = args_dump
return dump
end
--- Get a string representation of the object.
-- @treturn string A string representing the object
function class:__tostring__()
local dump = self:dump()
result = string.format(
......@@ -53,50 +64,49 @@ function class:__tostring__()
return result
end
function class._dump(o, cycles)
if not o then return nil end
--- Public Methods
-- @section public-methods
--- Dump an object.
--
-- Build a serializable table containing enough information to instanciate
-- and initialize a new object at the same state than `self`.
-- @tparam[opt={}] table cycles Already dumped fields to avoid loops
-- @treturn table A serializable table
function class:dump(cycles)
cycles = cycles or {}
local dump = {}
for k, v in pairs(o) do
if (
type(v) ~= "function" and -- You cannot safely save a function
string.sub(k, 1, 1) ~= "_" and -- Don't dump private fields
(not (o._no_dump_list and o._no_dump_list[k])) -- Do not dump attributes listed as undumpable
) then
if (
(torch.typename(v) or torch.type(v) == "table") and
cycles[torch.pointer(v)]
) then
dump[k] = string.format(
"cycle<%s>",
v._name or "table("..torch.pointer(v)..")"
)
elseif ( -- Call dump function on Torch object if available
torch.typename(v) and
v.dump
) then
dump[k] = v:dump(cycles)
elseif (torch.type(v) == "table") then -- Recurcively dump tables
cycles[v] = true
dump[k] = class._dump(v, cycles)
else
dump[k] = v
end
end
end
if self._logger then self._logger:debug("Dumping...") end
cycles[torch.pointer(self)] = true
local args_dump = class._dump(self._args, cycles) -- First dump the instanciation arguments
local dump = class._dump(self, cycles) -- Then dump local attributes
dump.classname = torch.typename(self) -- Used to identify the class from the dump
dump._args = args_dump
return dump
end
--- Load an object from a dump.
--
-- Given a @{dump}, find the associated class, instanciate an object and initialize it.
-- @tparam table dump Dump to restore
-- @return A newly instanciated object
function class.load(dump)
--- Find a class path given a class name.
--
-- Recurcively look for a class named `classname` in loaded packages/modules.
-- @tparam string classname Name of the class to find
-- @tparam[opt=_G] package Base environment/package to search
-- @treturn function Class constructor
-- @error nil
-- @todo Dump classpath to avoid this expensive search
local function find_class_by_name(classname, package)
package = package or _G
for k, v in pairs(package) do
for k, v in pairs(package) do -- look for each exported name
if k == classname then
return v
elseif (
string.lower(string.sub(k, 1, 1)) == string.sub(k, 1, 1) and -- packages are lower cased (while classes are upper cased)
type(v) == "table"
) then
) then -- search sub packages
local constructor = find_class_by_name(classname, v)
if constructor then return constructor end
end
......@@ -104,6 +114,11 @@ function class.load(dump)
return nil
end
--- Recurcively load a dump.
--
-- Instanciate any object referenced in `dump` before actually loading it.
-- @tparam table dump Dump to load
-- @return Newly instantiated object
local function recursive_load(dump)
local class = find_class_by_name(dump.classname, arcades)
if not class then
......@@ -125,8 +140,58 @@ function class.load(dump)
return class(dump._args, dump)
end
arcades.load_all()
arcades.load_all() -- Import all packages of the arcades library
return recursive_load(dump)
end
--- Static Methods
-- @section static-methods
--- Dump an object.
--
-- Dump any object, avoiding cycles.
-- The dump will contain any attribute excepted:
--
-- * functions
-- * attributes with name starting with `_` (underscore)
-- * attributes with name present in @{_no_dump_list}
--
-- If possible, tables and objects will be recurcively dumped.
-- @param[opt] o Object to dump
-- @tparam[opt={}] table cycles Already dumped tables/objects
-- @treturn table A serializable table or `nil`
function class._dump(o, cycles)
if not o then return nil end
cycles = cycles or {}
local dump = {}
for k, v in pairs(o) do
if (
type(v) ~= "function" and -- You cannot safely save a function
string.sub(k, 1, 1) ~= "_" and -- Don't dump private fields
(not (o._no_dump_list and o._no_dump_list[k])) -- Do not dump attributes listed as undumpable
) then
if (
(torch.typename(v) or torch.type(v) == "table") and
cycles[torch.pointer(v)]
) then
dump[k] = string.format(
"cycle<%s>",
v._name or "table("..torch.pointer(v)..")"
)
elseif ( -- Call dump function on Torch object if available
torch.typename(v) and
v.dump
) then
dump[k] = v:dump(cycles)
elseif (torch.type(v) == "table") then -- Recurcively dump tables
cycles[v] = true
dump[k] = class._dump(v, cycles)
else
dump[k] = v
end
end
end
return dump
end
return arcades
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