Skip to content

Commit 2b2a3e2

Browse files
Lazerbeak12345Lazerbeak12345
committed
fix: Add typechecking and various bugfixes
1 parent dc7ba30 commit 2b2a3e2

10 files changed

+461
-112
lines changed

‎.luacheckrc

+7-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1+
--luacheck: std luacheckrc
2+
---@package
3+
---@class globals:any
14
globals = {
25
'formspec_ast',
3-
'minetest',
46
'flow',
5-
'dump',
67
'flow_extras'
78
}
89

@@ -14,3 +15,7 @@ globals = {
1415
-- This error is thrown for methods that don't use the implicit "self"
1516
-- parameter.
1617
--ignore = {"212/self", "432/player", "43/ctx", "212/player", "212/ctx", "212/value"}
18+
19+
---@package
20+
---@class std:any
21+
std = 'lua52+minetest'

‎README.md

+9-55
Original file line numberDiff line numberDiff line change
@@ -16,61 +16,15 @@ An experimental collection of extra widgets for [flow].
1616

1717
## Docs
1818

19-
### Widgets
20-
21-
#### Grid
22-
23-
> TODO:
24-
25-
#### List
26-
27-
```lua
28-
flow_extras.List{
29-
inventory_location = inventory_location,
30-
list_name = list_name,
31-
w = w,
32-
h = h,
33-
starting_item_index = starting_item_index,
34-
remainder = remainder ,
35-
remainder_v = remainder_v ,
36-
remainder_align = remainder_align,
37-
listring = listring,
38-
bgimg = bgimg,
39-
align_h = align_h,
40-
align_v = align_v,
41-
spacing = spacing
42-
}
43-
```
44-
45-
> TODO: link these
46-
47-
| Parameter | Type | Description |
48-
| :-------- | :--- | :---------- |
49-
| `inventory_location` | `string` | **Required**. [See minetest's documentation for `list[]`][list] for more information. |
50-
| `list_name` | `string` | **Required**. [See minetest's documentation for `list[]`][list] for more information. |
51-
| `w` | `number` | **Required**. Width of list in tiles. [See minetest's documentation for `list[]`][list] for more information. |
52-
| `h` | `number` | **Required**. Height of list in tiles. [See minetest's documentation for `list[]`][list] for more information. |
53-
| `starting_item_index` | `number` | **Optional**. (Default `0`) Zero-based offset index for this list. [See minetest's documentation for `list[]`][list] for more information. |
54-
| `remainder` | `number` | **Optional**. (Default `0`) If you'd like a row of list tiles that is less than one demention of the rest of the list, set this to a number > 0. |
55-
| `remainder_v` | `boolean` | **Optional**. (Default `false`) If `true`, the remainder will be below the rest of the [`list[]`][list]. Otherwise, it is to the right. |
56-
| `remainder_align` | `string` | **Optional**. Passed into `align_v` on a [`flow.widgets.VBox`][gui.VBox] if `remainder_v` or `align_h` on a [`flow.widgets.HBox`][gui.HBox] to align the remainder list. |
57-
| `listring` | `table` | **Optional**. A list of tables each passed to `flow.widgets.Listring`. Prepended with this `list[]`'s location and name, if provided. If not provided, [`listring[]`][listring]s are not generated. |
58-
| `bgimg` | `boolean` or `string` or `table` of `string`s | **Optional**. If present, applies each image in order, looping from left to right, top to bottom, on each list tile in the main list, followed by the remainder list, in the same pattern. By default, since `list[]` elements are opaque, you will not be able to see these images. Make use of [`flow.widgets.Listcolors`][listcolors] to adjust this as needed. If `bgimg` is `false`, then no `bgimg`s are rendered. If it is `nil`, it defaults to `{ "flow_extras_list_bg.png" }`. If it is a string, it is wrapped in a table. |
59-
| `align_h` | `string` | **Optional**. If there is a remainder or a listring, this is passed to the the [`flow.widgets.VBox`][gui.VBox] if `remainder_v` or [`flow.widgets.Hbox`][gui.HBox] that wraps the entire element. Otherwise, this element does not exist, and either a [`flow.widgets.Stack`][gui.Stack] or a [`flow.widgets.List`][List] is the root. |
60-
| `align_v` | `string` | **Optional**. If there is a remainder or a listring, this is passed to the the [`flow.widgets.VBox`][gui.VBox] if `remainder_v` or [`flow.widgets.Hbox`][gui.HBox] that wraps the entire element. Otherwise, this element does not exist, and either a [`flow.widgets.Stack`][gui.Stack] or a [`flow.widgets.List`][List] is the root. |
61-
| `spacing` | `number` | **Optional**. The amount of space between the list tiles. Defaults to `0.25` - the same amount as minetest out of the box. |
62-
63-
[list]: https://github.com/minetest/minetest/blob/master/doc/lua_api.md#listinventory-locationlist-namexywhstarting-item-index
64-
[listring]: https://github.com/minetest/minetest/blob/master/doc/lua_api.md#listringinventory-locationlist-name
65-
[gui.List]: https://gitlab.com/luk3yx/minetest-flow/-/blob/main/elements.md?ref_type=heads#guilist
66-
[gui.HBox]: https://gitlab.com/luk3yx/minetest-flow#guihbox
67-
[gui.VBox]: https://gitlab.com/luk3yx/minetest-flow#guivbox
68-
[gui.Stack]: https://gitlab.com/luk3yx/minetest-flow#guistack
69-
[listcolors]: https://github.com/minetest/minetest/blob/master/doc/lua_api.md#listcolorsslot_bg_normalslot_bg_hover
70-
71-
### Tools
72-
73-
> TODO:
19+
<span id="widgets"></span>
20+
<span id="grid"></span>
21+
<span id="list"></span>
22+
<span id="tools"></span>
23+
### Widgets & tools
24+
25+
See the LuaCATS documentation in the code, with the busted unit tests for examples.
26+
27+
If your IDE supports LuaCATS (such as if it uses the `lua_ls` language server), then the documentation should show up in your IDE.
7428

7529
### Textures
7630

‎demo/init.lua

+10-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
1-
local flow, minetest, flow_extras = flow, minetest, flow_extras
1+
---@module '../../flow/init.lua'
2+
local flow = _G.flow --[[@as flow]]
3+
24
local gui = flow.widgets
5+
6+
---@class minetest
7+
local minetest = minetest
8+
9+
---@class flow_extras
10+
local flow_extras = flow_extras
11+
312
local example_form = flow.make_gui(function ()
413
return gui.HBox{
514
gui.VBox{

‎init.lua

+182-1
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,190 @@
1-
local modpath = minetest.get_modpath"flow_extras"
1+
2+
3+
4+
-- What's all this stuff behind the ---? That's LuaCATS documentation.
5+
-- It does typechecking as well, so I've documented types for 3rd party untyped utilities - to make sure I'm (at least)
6+
-- documenting what I thinkking the APIs do (and how I'm using them) - that and some apis are building upon things from
7+
-- others.
8+
9+
---@package
10+
---@class minetest.register_chatcommand_params
11+
---@field privs TruthTable
12+
---@field help string
13+
---@field func fun(player:string)
14+
15+
---@package
16+
---@class minetest.Player
17+
18+
---@package
19+
---@class minetest
20+
---@field log fun(type:"warning", message:string)
21+
---@field is_singleplayer fun():boolean
22+
---@field register_chatcommand fun(cmd:string, params:minetest.register_chatcommand_params)
23+
---@field get_player_by_name fun(player:string):minetest.Player
24+
---@module 'minetest' -- ???
25+
local minetest = _G.minetest --[[@as minetest]]
26+
27+
---@package
28+
---@alias FormspecAstTree { type:string, [number]:FormspecAstTree, [string]:any }
29+
30+
---@package
31+
---@class formspec_ast
32+
---@field walk fun(flow_tree:FormspecAstTree, truth_table:TruthTable): Iterator<FormspecAstTree>
33+
---@module '../../formspec_ast/init.lua'
34+
--luacheck: push ignore formspec_ast
35+
--local formspec_ast = _G.formspec_ast --[[@as formspec_ast]]
36+
--luacheck: pop
37+
38+
---@package
39+
---@alias FlowTree FormspecAstTree
40+
41+
---@package
42+
---@alias FlowAlign "auto"|"start"|"end"|"centre"|"fill"|"center"
43+
44+
---@package
45+
---@class flow.widget_fields
46+
---@field expand? boolean
47+
---@field [number] FlowTree
48+
49+
---@package
50+
---@class flow.widgets.Listring_fields:flow.widget_fields
51+
---@field inventory_location string See minetest's `list[]` documentation for more information.
52+
---@field list_name string See minetest's documentation for `list[]` for more information.
53+
54+
---@package
55+
---@alias flow.widgets.Listring fun(fields: flow.widgets.Listring_fields): FlowTree
56+
57+
---@package
58+
---@class flow.widgets.List_fields:flow.widgets.Listring_fields
59+
---@field w number Width of list in tiles. See minetest's documentation for `list[]` for more information.
60+
---@field h number Height of list in tiles. See minetest's documentation for `list[]` for more information.
61+
--luacheck: push no max comment line length
62+
---@field starting_item_index? number (Default `0`) Zero-based offset index for this list. [See minetest's documentation for `list[]`][list] for more information.
63+
--luacheck: pop
64+
65+
---@package
66+
---@alias flow.widgets.List fun(fields: flow.widgets.List_fields): FlowTree
67+
68+
---@package
69+
---@class flow.widgets.VBox_fields:flow.widget_fields
70+
---@field spacing? number
71+
---@field align_v? string
72+
73+
---@package
74+
---@alias flow.widgets.VBox fun(fields: flow.widgets.VBox_fields): FlowTree
75+
76+
---@package
77+
---@class flow.widgets.HBox_fields:flow.widget_fields
78+
---@field spacing? number
79+
---@field align_h? string
80+
81+
---@package
82+
---@alias flow.widgets.HBox fun(fields: flow.widgets.HBox_fields): FlowTree
83+
84+
---@package
85+
---@class flow.widgets.Stack_fields:flow.widget_fields
86+
87+
---@package
88+
---@alias flow.widgets.Stack fun(fields: flow.widgets.Stack_fields): FlowTree
89+
90+
---@package
91+
---@class flow.widgets.Spacer_fields:flow.widget_fields
92+
---@field w number
93+
---@field h number
94+
---@field expand boolean
95+
96+
---@package
97+
---@alias flow.widgets.Spacer fun(fields: flow.widgets.Spacer_fields): FlowTree
98+
99+
---@package
100+
---@class flow.widgets.Image_fields:flow.widget_fields
101+
---@field w number
102+
---@field h number
103+
---@field texture_name string
104+
105+
---@package
106+
---@alias flow.widgets.Image fun(fields: flow.widgets.Image_fields): FlowTree
107+
108+
---@package
109+
---@class flow.widgets.Label_fields:flow.widget_fields
110+
---@field label string
111+
112+
---@package
113+
---@alias flow.widgets.Label fun(fields: flow.widgets.Label_fields): FlowTree
114+
115+
---@package
116+
---@class flow.widgets.Button_fields:flow.widgets.Label_fields
117+
118+
---@package
119+
---@alias flow.widgets.Button fun(fields: flow.widgets.Button_fields): FlowTree
120+
121+
---@package
122+
---@alias flow.widgets.Nil fun(fields: flow.widget_fields): FlowTree
123+
124+
---@package
125+
---@alias flow.widgets.Box flow.widgets.Nil
126+
127+
---@package
128+
---@class flow.widgets
129+
---@field flow.widget_fields flow.widget_fields
130+
---@field List_fields flow.widgets.List_fields
131+
---@field List flow.widgets.List
132+
---@field Listring_fields flow.widgets.Listring_fields
133+
---@field Listring flow.widgets.Listring
134+
---@field VBox_fields flow.widgets.VBox_fields
135+
---@field VBox flow.widgets.VBox
136+
---@field HBox_fields flow.widgets.HBox_fields
137+
---@field HBox flow.widgets.HBox
138+
---@field Stack_fields flow.widgets.Stack_fields
139+
---@field Stack flow.widgets.Stack
140+
---@field Spacer_fields flow.widgets.Spacer_fields
141+
---@field Spacer flow.widgets.Spacer
142+
---@field Image_fields flow.widgets.Image_fields
143+
---@field Image flow.widgets.Image
144+
---@field Label_fields flow.widgets.Label_fields
145+
---@field Label flow.widgets.Label
146+
---@field Button_fields flow.widgets.Button_fields
147+
---@field Button flow.widgets.Button
148+
---@field Nil flow.widgets.Nil
149+
---@field Box flow.widgets.Box
150+
151+
---@package
152+
---@class flow.Flow
153+
---@field show fun(self: flow.Flow, p:minetest.Player)
154+
155+
---@package
156+
---@generic X:table
157+
---@class flow
158+
---@field get_context nil|fun(): `X`
159+
---@field widgets flow.widgets
160+
---@field make_gui fun():flow.Flow
161+
---@module '../../flow/init.lua'
162+
--luacheck: push ignore flow
163+
--local flow = _G.flow --[[@as flow]]
164+
--luacheck: pop
165+
166+
---A collection of unofficial widgets for flow
167+
---@see flow
168+
---@class flow_extras
2169
local flow_extras = {}
3170
_G.flow_extras = flow_extras
171+
172+
local modpath = minetest.get_modpath"flow_extras"
173+
174+
---@module "./tools/search.lua"
4175
dofile(modpath .. "/tools/search.lua")
176+
177+
---@module "./tools/context.lua"
5178
dofile(modpath .. "/tools/context.lua")
179+
180+
---@module "./tools/tables.lua"
6181
dofile(modpath .. "/tools/tables.lua")
182+
183+
---@module "./widgets/grid.lua"
7184
dofile(modpath .. "/widgets/grid.lua")
185+
186+
---@module "./widgets/list.lua"
8187
dofile(modpath .. "/widgets/list.lua")
188+
189+
---@module "./demo/init.lua"
9190
--dofile(modpath .. "/demo/init.lua")

0 commit comments

Comments
 (0)