finish documentation for STD containers and fix and break emmylua

docs/generate.py

@@ -9,8 +9,9 @@
 if not os.path.exists("src/includes"):
     os.makedirs("src/includes")
 
-
+# if you change anything in here, please update it in validator.py as well
 replace_table = {
+    # standard basic types
     "uint8_t": "int",
     "uint16_t": "int",
     "uint32_t": "int",
@@ -22,25 +23,35 @@
     "ImU32": "int",
     "in_port_t": "int",
     "size_t": "int",
-    "custom_vector<": "vector<",
-    "span<": "array<",
-    "unordered_map<": "map<",
-    "game_map<": "map<",
-    "custom_map<": "map<",
-    ", identity_hasher<>": "",
     "char*": "string",
     "wstring": "string",
     "u16string": "string",
     "string_view": "string",
     "char16_t*": "string",
     "char16_t": "char",
     "pair<": "tuple<",
+    # std containers
+    "custom_vector<": "vector<",
+    "custom_map<": "map<",
+    "custom_unordered_map<": "map<",
+    "custom_set<": "set<",
+    "custom_unordered_set<": "set<",
+    "game_vector<": "vector<",
+    "game_map<": "map<",
+    "game_unordered_map<": "map<",
+    "game_set<": "set<",
+    "game_unordered_set<": "set<",
+    "unordered_map<": "map<", # doesn't seam to matter for lua if it's ordered or not
+    "unordered_set<": "set<", # doesn't seam to matter for lua if it's ordered or not
+    # removers
+    ", identity_hasher<>": "",
     "std::": "",
     "sol::": "",
     "void": "",
     "constexpr": "",
     "const": "",
     "static": "",
+    # special
     "variadic_args va": "ENT_TYPE, ENT_TYPE...",
     "EmittedParticlesInfo": "array<Particle>",
     "ImVec2": "Vec2",
@@ -69,6 +80,13 @@ def is_custom_type(name):
     return False
 
 
+extra_link = {
+    "vector":"STD-Library-Containers",
+    "map":"STD-Library-Containers",
+    "span":"STD-Library-Containers",
+    "set":"STD-Library-Containers",
+}
+
 def link_custom_type(ret):
     parts = re.findall(r"[\w_]+|[^\w_]+", ret)
     ret = ""
@@ -95,6 +113,7 @@ def link_custom_type(ret):
             ):
                 part = f"[{part}](#Aliases)"
         ret += part
+# TODO link extra types (map, set, vector)
     return ret
 
 
@@ -374,7 +393,7 @@ def print_lf(lf):
             com = link_custom_type(com)
             print(com)
 
-print("# STD Library")
+print("# STD Library Containers")
 print(
     """Sometimes game variables and return of some functions will be of type `map`, `set`, `vector` etc. from the C++ Standard Library.
 
@@ -388,20 +407,30 @@ def print_lf(lf):
 Type | Name | Description
 ---- | ---- | -----------"""
 )
+print("bool | all:empty() | Returns true if container is empty, false otherwise")
+print("int | aLL:size() | Same as `#container`")
+
 print("any | vector:at(int index) | Same as `vector[index]`")
+print("any | span:at(int index) | Same as `span[index]`")
 print("any | set:at(int order) | Returns elements in order, it's not an index as sets don't have one")
+print("any | map:at(int order) | Returns elements in order, it's not an index as maps don't have one")
+
 print("int | vector:find(any value) | Searches for the value in vector, returns index of the item in vector or nil if not found, only available for simple values that are comparable")
+print("int | span:find(any value) | Searches for the value in span, returns index of the item in span or nil if not found, only available for simple values that are comparable")
 print("any | set:find(any value) | Searches for the value in set, returns the value itself or nil if not found, only available for simple values that are comparable")
-print("nil | vector:erase(int index) | Removes element at given index, the rest of elements swift down so that the vector stays contiguous")
-print("nil | set:erase(any value) | Removes element from set")
-print("nil | vector:clear() | Removes all elements from vector")
-print("nil | vector:insert(int index, any element) | Inserts element at given index, the rest of elements shift up")
-print("nil | set:insert(int order, any element) | If the set is ordered, the order param doesn't matter and can be set to nil")
+print("any | map:find(any key) | Searches for the key in map, returns the value itself or nil if not found, only available for simple keys that are comparable")
 
-print("bool | all:empty() | Returns true if container is empty, false otherwise")
-print("int | aLL:size() | Same as `#container`")
+print("nil | vector:erase(int index) | Removes element at given index, the rest of elements shift down so that the vector stays contiguous")
+print("nil | set:erase(any value) | Removes element from set")
+print("nil | map:erase(any key) | Removes element from map by key")
 
+print("nil | vector:clear() | Removes all elements from vector")
+print("nil | set:clear() | Removes all elements from set")
+print("nil | map:clear() | Removes all elements from map")
 
+print("nil | vector:insert(int index, any element) | Inserts element at given index, the rest of elements shift up in index")
+print("nil | set:insert(int order, any element) | The order param doesn't acutally matter and can be set to nil")
+print("nil | map:insert(any key, any value) | unsure, probably easier to just use `map[key] = value`")
 
 
 print("# Functions")

docs/generate_emmylua.py

@@ -19,12 +19,11 @@
     "vector": "Array",
     "array": "Array",
     "unordered_map": "table",
-    "game_table": "table",
     ", identity_hasher<>": "",
-    "const char*": "string",
+    "char*": "string",
     "wstring": "string",
     "u16string": "string",
-    "char16_t": "string",
+    "char16_t*": "string",
     "string_view": "string",
     "pair": "tuple",
     "std::": "",
@@ -33,12 +32,15 @@
     "void": "",
     "constexpr": "",
     "...va:": "...ent_type:",
-    "// Access via": "ImGuiIO",
     "set<": "Array<",
     "span<": "Array<",
-    "&": "",
+
+    "game_table": "table",
+    "custom_table": "table",
+    "game_array": "Array",
+    "custom_array": "Array",
+
     "const ": "",
-    "ShopType": "SHOP_TYPE",
     "EmittedParticlesInfo": "Array<Particle>",
     "object": "any",
     "ImVec2": "Vec2",

docs/src/includes/_globals.md

@@ -147,6 +147,35 @@ end, ON.LEVEL)
 > Search script examples for [prng](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=prng)
 
 The global prng state, calling any function on it will advance the prng state, thus desynchronizing clients if it does not happen on both clients.
+# STD Library Containers
+Sometimes game variables and return of some functions will be of type `map`, `set`, `vector` etc. from the C++ Standard Library.
+
+You don't really need to know much of this as they will behave similar to a lua table, even accept some table functions from the `table` library and support looping thru using `pair` function. You can also use them as parameter for functions that take `array`, Sol will happily convert them for you.
+
+They come with some extra functionality:
+
+
+Type | Name | Description
+---- | ---- | -----------
+bool | all:empty() | Returns true if container is empty, false otherwise
+int | aLL:size() | Same as `#container`
+any | vector:at(int index) | Same as `vector[index]`
+any | span:at(int index) | Same as `span[index]`
+any | set:at(int order) | Returns elements in order, it's not an index as sets don't have one
+any | map:at(int order) | Returns elements in order, it's not an index as maps don't have one
+int | vector:find(any value) | Searches for the value in vector, returns index of the item in vector or nil if not found, only available for simple values that are comparable
+int | span:find(any value) | Searches for the value in span, returns index of the item in span or nil if not found, only available for simple values that are comparable
+any | set:find(any value) | Searches for the value in set, returns the value itself or nil if not found, only available for simple values that are comparable
+any | map:find(any key) | Searches for the key in map, returns the value itself or nil if not found, only available for simple keys that are comparable
+nil | vector:erase(int index) | Removes element at given index, the rest of elements shift down so that the vector stays contiguous
+nil | set:erase(any value) | Removes element from set
+nil | map:erase(any key) | Removes element from map by key
+nil | vector:clear() | Removes all elements from vector
+nil | set:clear() | Removes all elements from set
+nil | map:clear() | Removes all elements from map
+nil | vector:insert(int index, any element) | Inserts element at given index, the rest of elements shift up in index
+nil | set:insert(int order, any element) | The order param doesn't acutally matter and can be set to nil
+nil | map:insert(any key, any value) | unsure, probably easier to just use `map[key] = value`
 # Functions
 The game functions like `spawn` use [level coordinates](#get_position). Draw functions use normalized [screen coordinates](#screen_position) from `-1.0 .. 1.0` where `0.0, 0.0` is the center of the screen.
 

docs/src/includes/_types.md

@@ -2931,8 +2931,8 @@ int | [text_length](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=tex
 float | [width](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=width) | 
 float | [height](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=height) | 
 int | [special_texture_id](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=special_texture_id) | Used to draw buttons and stuff, default is -1 wich uses the buttons texture
-array<[Letter](#Letter)> | [get_dest()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=get_dest) | Returns refrence to the letter coordinates relative to the x,y position
-array<[Letter](#Letter)> | [get_source()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=get_source) | Returns refrence to the letter coordinates in the texture
+span<[Letter](#Letter)> | [get_dest()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=get_dest) | Returns refrence to the letter coordinates relative to the x,y position
+span<[Letter](#Letter)> | [get_source()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=get_source) | Returns refrence to the letter coordinates in the texture
 tuple<float, float> | [text_size()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=text_size) | {width, height}, is only updated when you set/change the text. This is equivalent to draw_text_size
 nil | [rotate(float angle, optional<float> px, optional<float> py)](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=rotate) | Rotates the text around the pivot point (default 0), pivot is relative to the text position (x, y), use px and py to offset it
 nil | [set_text(string text, float scale_x, float scale_y, VANILLA_TEXT_ALIGNMENT alignment, VANILLA_FONT_STYLE fontstyle)](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=set_text) | Changes the text, only position stays the same, everything else (like rotation) is reset or set according to the parameters
@@ -4026,7 +4026,7 @@ bool | [trigger_action(Entity user)](https://github.com/spelunky-fyi/overlunky/s
 int | [get_metadata()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=get_metadata) | e.g. for turkey: stores health, poison/curse state, for mattock: remaining swings (returned value is transferred)
 nil | [apply_metadata(int metadata)](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=apply_metadata) | 
 nil | [set_invisible(bool value)](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=set_invisible) | 
-array&lt;int&gt; | [get_items()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=get_items) | 
+span&lt;int&gt; | [get_items()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=get_items) | 
 bool | [is_in_liquid()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=is_in_liquid) | Returns true if entity is in water/lava
 bool | [is_cursed()](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=is_cursed) | 
 [CallbackId](#Aliases) | [set_pre_virtual(ENTITY_OVERRIDE entry, function fun)](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=set_pre_virtual) | Hooks before the virtual function at index `entry`.

docs/validator.py

@@ -4,6 +4,7 @@
 
 #should be the same as in generate.py
 replace_table = {
+    # standard basic types
     "uint8_t": "int",
     "uint16_t": "int",
     "uint32_t": "int",
@@ -15,25 +16,35 @@
     "ImU32": "int",
     "in_port_t": "int",
     "size_t": "int",
-    "custom_vector<": "vector<",
-    "span<": "array<",
-    "unordered_map<": "map<",
-    "game_map<": "map<",
-    "custom_map<": "map<",
-    ", identity_hasher<>": "",
     "char*": "string",
     "wstring": "string",
     "u16string": "string",
     "string_view": "string",
     "char16_t*": "string",
     "char16_t": "char",
     "pair<": "tuple<",
+    # std containers
+    "custom_vector<": "vector<",
+    "custom_map<": "map<",
+    "custom_unordered_map<": "map<",
+    "custom_set<": "set<",
+    "custom_unordered_set<": "set<",
+    "game_vector<": "vector<",
+    "game_map<": "map<",
+    "game_unordered_map<": "map<",
+    "game_set<": "set<",
+    "game_unordered_set<": "set<",
+    "unordered_map<": "map<", # doesn't seam to matter for lua if it's ordered or not
+    "unordered_set<": "set<", # doesn't seam to matter for lua if it's ordered or not
+    # removers
+    ", identity_hasher<>": "",
     "std::": "",
     "sol::": "",
     "void": "",
     "constexpr": "",
     "const": "",
     "static": "",
+    # special
     "variadic_args va": "ENT_TYPE, ENT_TYPE...",
     "EmittedParticlesInfo": "array<Particle>",
     "ImVec2": "Vec2",
@@ -71,6 +82,11 @@ def replace_all(text):
     "any",
     "IMAGE",
     "VTABLE_OFFSET",
+    # std library
+    "map",
+    "set",
+    "vector",
+    "span",
 ]
 
 unknown_types = []