Merge pull request #817 from MihailRis/document-session-library

Document session library

doc/en/scripting.md

@@ -37,6 +37,7 @@ Subsections:
     - [quat](scripting/builtins/libquat.md)
     - [random](scripting/builtins/librandom.md)
     - [rules](scripting/builtins/librules.md)
+    - [session](scripting/builtins/libsession.md)
     - [time](scripting/builtins/libtime.md)
     - [utf8](scripting/builtins/libutf8.md)
     - [vec2, vec3, vec4](scripting/builtins/libvecn.md)

doc/en/scripting/builtins/libsession.md

@@ -0,0 +1,18 @@
+# *session* Library
+
+This library is used to store data that is not reset when loading/unloading content, and is a recommended alternative to using the `_G` table.
+
+The stored data is not saved when the engine terminates.
+
+To minimize the risk of name collisions, it is recommended to use pack prefixes (`pack_id:table_name`), or, if a pack stores a single table in *session*, use the pack name as the entry name.
+
+```lua
+-- Returns a table by name. Creates an empty table if it does not exist.
+session.get(name: str) -> table
+
+-- Deletes a table by name.
+session.reset(name: str)
+
+-- Returns true if the table has already been created by calling session.get
+session.has(name: str) -> boolean
+```

doc/ru/scripting.md

@@ -37,6 +37,7 @@
     - [quat](scripting/builtins/libquat.md)
     - [random](scripting/builtins/librandom.md)
     - [rules](scripting/builtins/librules.md)
+    - [session](scripting/builtins/libsession.md)
     - [time](scripting/builtins/libtime.md)
     - [utf8](scripting/builtins/libutf8.md)
     - [vec2, vec3, vec4](scripting/builtins/libvecn.md)

doc/ru/scripting/builtins/libsession.md

@@ -0,0 +1,18 @@
+# Библиотека *session*
+
+Библиотека используется для хранения данных, не сбрасывающихся при загрузке/выгрузке контента, являясь рекомендованной альтернативой использованию таблицы `_G`.
+
+Хранимые данные не сохраняются при завершении работы движка.
+
+Для минимизации риска коллизий имён рекомендуется использовать префиксы паков (`id_пака:имя_таблицы`), либо, если пак хранит одну таблицу в *session*, использовать имя пака как имя записи.
+
+```lua
+-- Возвращает таблицу по имени. Создаёт пустую таблицу при отсутствии.
+session.get(name: str) -> table
+
+-- Удаляет таблицу по имени.
+session.reset(name: str)
+
+-- Возвращает true если таблица уже была создана вызовом session.get
+session.has(name: str) -> boolean
+```

doc/ru/scripting/builtins/libtime.md

@@ -1,4 +1,4 @@
-# Библиотека time
+# Библиотека *time*
 
 ```lua
 -- Возвращает время с момента запуска движка в секундах и милисекундах.

res/layouts/console.xml.lua

@@ -1,6 +1,6 @@
 console_mode = "console"
 
-history = session.get_entry("commands_history")
+history = session.get("commands_history")
 history_pointer = #history
 
 events.on("core:open_traceback", function()

res/layouts/pages/generators.xml.lua

@@ -1,4 +1,4 @@
-settings = session.get_entry('new_world')
+settings = session.get('new_world')
 
 function on_open()
     local names = generation.get_generators()

res/layouts/pages/new_world.xml.lua

@@ -1,4 +1,4 @@
-settings = session.get_entry('new_world')
+settings = session.get('new_world')
 
 function world_name_validator(name)
     return name:match("^[%w-\\.\\ ]+$") ~= nil and not world.exists(name)
@@ -20,7 +20,7 @@ function create_world()
     local name = document.name_box.text
     local seed = document.seed_box.text
     local generator = settings.generator
-    session.reset_entry('new_world')
+    session.reset('new_world')
     app.new_world(name, seed, generator)
 end
 

res/modules/internal/session.lua

@@ -0,0 +1,21 @@
+local entries = {}
+local this = {}
+
+function this.get(name)
+    local entry = entries[name]
+    if entry == nil then
+        entry = {}
+        entries[name] = entry
+    end
+    return entry
+end
+
+function this.has(name)
+    return entries[name] ~= nil
+end
+
+function this.reset(name)
+    entries[name] = nil
+end
+
+return this

res/scripts/stdlib.lua

@@ -345,23 +345,7 @@ function gui.template(name, params)
     return text
 end
 
-session = {
+session = require "core:internal/session"
-    entries={}
-}
-
-function session.get_entry(name)
-    local entry = session.entries[name]
-    if entry == nil then
-        entry = {}
-        session.entries[name] = entry
-    end
-    return entry
-end
-
-function session.reset_entry(name)
-    session.entries[name] = nil
-end
-
 stdcomp = require "core:internal/stdcomp"
 entities.get = stdcomp.get_Entity
 entities.get_all = function(uids)