-
Notifications
You must be signed in to change notification settings - Fork 1
/
other.template
642 lines (597 loc) · 24.7 KB
/
other.template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
-- Hand written Discordia types for things which are also hand written in the documentation
-- Add in auto complete for events
---@alias clientEvents string
---| "'ready'" # Emitted after all shards and guilds are fully loaded.
---| "'shardReady'" # Emitted after a shard successfully connects to a Discord gateway and loads all corresponding guilds.
---| "'shardResume'" # Emitted after the client successfully resumes a severed gateway connection.
---| "'channelCreate'" # Emitted when a guild channel is created, when a private channel is opened, or when a group channel is joined.
---| "'channelUpdate'" # Emitted when a channel property is updated, such as its name, topic, bitrate, etc.
---| "'channelDelete'" # Emitted when a guild channel is deleted, when a private channel is closed, or when a group channel is left.
---| "'recipientAdd'" # Emitted when a new recipient is added to a group channel. User-accounts only.
---| "'recipientRemove'" # Emitted when a new recipient is removed from a group channel. User-accounts only.
---| "'guildAvailable'" # Emitted when a guild becomes available. This can occur after a server outage or as guild data is streamed in after login.
---| "'guildCreate'" # Emitted when a guild is created from the perspective of the current user, usually after the client user joins a new one.
---| "'guildUpdate'" # Emitted when a guild property is updated such as its name, region, icon, etc.
---| "'guildUnavailable'" # Emitted when a guild becomes unavailable, potentially due to a server outage. Unavailable guilds may lack significant data.
---| "'guildDelete'" # Emitted when a guild is deleted from the perspective of the current user, usually after the client leaves one.
---| "'userBan'" # Emitted when a user is banned from a guild.
---| "'userUnban'" # Emitted when a user is unbanned from a guild.
---| "'emojisUpdate'" # Emitted when a guild's custom emoji is updated.
---| "'memberJoin'" # Emitted when a new user joins a guild.
---| "'memberLeave'" # Emitted when a user leaves a guild.
---| "'memberUpdate'" # Emitted when a guild member property is updated, such as its roles or nickname. See presenceUpdate for status changes.
---| "'roleCreate'" # Emitted when a guild role is created.
---| "'roleUpdate'" # Emitted when a guild role property is updated, such as its name, color, permissions, etc.
---| "'roleDelete'" # Emitted when a guild role is deleted.
---| "'messageCreate'" # Emitted when a text channel message is created.
---| "'messageUpdate'" # Emitted when the content of a text channel message is edited.
---| "'messageUpdateUncached'" # Emitted when the content of a text channel message is edited, but the message is not cached by the client.
---| "'messageDelete'" # Emitted when a text channel message is deleted. Bulk deletions will fire this for every message that is deleted.
---| "'messageDeleteUncached'" # Emitted when a text channel message is deleted, but the message is not cached by the client. Bulk deletions will fire this for every message that is deleted, but not cached.
---| "'reactionAdd'" # Emitted when an emoji reaction is added to message.
---| "'reactionAddUncached'" # Emitted when an emoji reaction is added to message, but the message is not cached by the client.
---| "'reactionRemove'" # Emitted when an emoji reaction is removed from a message.
---| "'reactionRemoveUncached'" # Emitted when an emoji reaction is removed from a message, but the message is not cached by the client.
---| "'pinsUpdate'" # Emitted when a message is pinned or unpinned in a channel.
---| "'presenceUpdate'" # Emitted when a guild member's status or user properties change. See memberUpdate for role and nickname changes.
---| "'relationshipUpdate'" # Emitted when a relationship's (friend, blocked user) status or user properties change. User-accounts only.
---| "'relationshipAdd'" # Emitted when a relationship (friend, blocked user) is added. User-accounts only.
---| "'relationshipRemove'" # Emitted when a relationship (friend, blocked user) is removed. User-accounts only.
---| "'typingStart'" # Emitted when a user starts typing in a text channel.
---| "'userUpdate'" # Emitted when the client user updates itself.
---| "'voiceConnect'" # Emitted when a guild member connects to voice chat.
---| "'voiceDisconnect'" # Emitted when a guild member disconnects from voice chat.
---| "'voiceUpdate'" # Emitted when a guild member's mute/deaf status changes.
---| "'voiceChannelJoin'" # Emitted when a guild member joins a voice channel.
---| "'voiceChannelLeave'" # Emitted when a guild member leaves a voice channel.
---| "'webhooksUpdate'" # Emitted when a guild's text channel's webhooks have updated.
---| "'heartbeat'" # Emitted when Discord responds with a heartbeat acknowledgement.
---| "'raw'" # Emitted for every Discord gateway event.
---| "'debug'" # Emitted to provide detailed information regarding specific library behavior.
---| "'info'" # Emitted to provide helpful information regarding general library behavior.
---| "'warning'" # Emitted when something went wrong, but your code will probably continue operating normally.
---| "'error'" # Emitted when something went wrong and your code may not continue operating normally.
---Subscribes a callback to be called every time the named event is emitted. Callbacks registered with this method will automatically be wrapped as a new coroutine when they are called. Returns the original callback for convenience.
---@param name clientEvents
---@param fn function
---@return function
--@clientEmitters
function Client:on(name, fn) end
---Subscribes a callback to be called only the first time this event is emitted. Callbacks registered with this method will automatically be wrapped as a new coroutine when they are called. Returns the original callback for convenience.
---@param name clientEvents
---@param fn function
---@return function
--@clientEmitters
function Client:once(name, fn) end
---Subscribes a callback to be called every time the named event is emitted. Callbacks registered with this method are not automatically wrapped as a coroutine. Returns the original callback for convenience.
---@param name clientEvents
---@param fn function
---@return function
--@clientEmitters
function Client:onSync(name, fn) end
---Subscribes a callback to be called only the first time this event is emitted. Callbacks registered with this method are not automatically wrapped as a coroutine. Returns the original callback for convenience.
---@param name clientEvents
---@param fn function
---@return function
--@clientEmitters
function Client:onceSync(name, fn) end
--- Send a debug level(4) message
---
--- Used for all HTTP requests, all gateway events, gateway debugging information
---@param msg string
---@vararg any
function Client:debug(msg, ...) end
--- Send an info level(3) message
---
--- Used for messages about connecting to the gateway, launching shards, receiving select gateway events
---@param msg string
---@vararg any
function Client:info(msg, ...) end
--- Send a warning level(2) message
---
--- Used for uncached objects and unhandled gateway events, unacknowledged heartbeats, gateway reconnections
---@param msg string
---@vararg any
function Client:warning(msg, ...) end
--- Send an error level(1) message
---
--- Used for API request failures (HTTP 4xx/5xx), sharding issues, authentication issues
---@param msg string
---@vararg any
function Client:error(msg, ...) end
--- The Lua language does not have classes, but it does have all of the tools needed to write them.
--- Discordia uses a custom class system that was written explicitly to encapsulate data provided by Discord in intuitive, efficient structures.
---
--- The `class` module used by Discordia is available to users in the main Discordia module.
--- The class module is both the module table and a callable class constructor.
---
--- ```lua
--- local discordia = require('discordia')
--- local class = discordia.class
--- ```
---
--- ## Constructing Classes and Objects
---
--- All Discordia classes must be uniquely named and must have an `__init` method.
--- `UpperCamelCase` is used for class names while `lowerCamelCase` is used for public instances, properties, and methods.
---
--- ```lua
--- local Apple = class('Apple') -- construct a new class
---
--- function Apple:__init(color) -- define the initializer
--- ...
--- end
---
--- local apple = Apple('red') -- call the class table to instantiate a new object
--- ```
---
--- ## Properties
---
--- Discordia enforces a "protected" property policy.
--- All new properties written directly to class objects must be prefixed with an underscore.
--- Directly accessing underscored properties outside of the class definitions is not recommended.
--- Additionally, to avoid potential compatibility issues, **writing custom properties to pre-defined Discordia classes is not recommended**.
---
--- ```lua
--- local Apple = class('Apple')
---
--- function Apple:__init(color)
--- self._color = color -- define a "protected" property
--- end
--- ```
---
--- Because of this underscore policy, Discordia classes also have **getters** and **setters** that can be used to define public properties.
--- These are empty tables and should be populated by functions where getters return a value and setters modify a property.
--- Note that an explicit `self` must be passed for these functions.
---
--- ```lua
--- local Apple, get, set = class('Apple') -- multiple return values
---
--- function Apple:__init(color)
--- self._color = color
--- end
---
--- function get.color(self) -- define a getter
--- return self._color
--- end
---
--- function set.color(self, color) -- define a setter
--- self._color = color
--- end
--- ```
---
--- With getters and setters, you can indirectly get/access and set/mutate protected (underscored) properties without having to use a method.
--- More importantly, if a setter is not defined for a specific property, Discordia will prevent users from overwriting that property.
--- Note Discordia itself never uses setters, but the option is available for people who want to make their own classes.
---
--- ```lua
--- local apple = Apple('red')
--- print(apple.color) -- 'red'
---
--- apple.color = 'green'
--- print(apple.color) -- 'green'
--- ```
---
--- ### Member Methods
---
--- Member methods are defined and called using Lua's colon notation so that an implicit `self` is passed to the function.
---
--- ```lua
--- local Apple = class('Apple')
---
--- function Apple:__init(color)
--- self._color = color
--- end
---
--- function Apple:getColor() -- define a member method
--- return self._color
--- end
---
--- local user = Apple('red')
--- print(user:getColor()) -- 'red'
--- ```
---
--- ### Static Methods
---
--- Static methods are defined and called using Lua's dot notation.
--- No implicit (or explicit) self is required for static methods.
---
--- ```lua
--- local colors = {'red', 'yellow', 'green'}
---
--- function Apple.random() -- returns a random apple object
--- return Apple(colors[math.random(#colors)])
--- end
--- ```
---
--- ## Inheritance
---
--- Discordia classes support single and multiple inheritance.
--- Base or super classes are passed to the class constructor.
---
--- ```lua
--- local Fruit = class('Fruit') -- Fruit is a base class
---
--- function Fruit:__init(color)
--- self._color = color
--- end
---
--- function Fruit:getColor()
--- return self._color
--- end
---
--- local Apple = class('Apple', Fruit) -- Apple inherits from Fruit
---
--- function Apple:__init(color)
--- Fruit.__init(self, color) -- base constructor must be explicitly called
--- end
---
--- local apple = Apple('red')
---
--- print(apple:getColor()) -- 'red'; method inherited from Fruit
--- ```
---
--- ## Utilities
---
--- The class module contains a variety of tables and functions that may be useful to regular users.
---
--- #### classes
---
--- Table of all defined classes, indexed by name.
---
---@class class
---@field public classes table<string, any>
local class = {}
---@type class | fun(name: string, ...): any, table, table
class = class
--- Function that returns true only if the provided argument is a Discordia class module.
---
--- ```lua
--- print(class.isClass(Color)) -- true
--- print(class.isClass(1337)) -- false
--- ```
---@param obj any
---@return boolean
function class.isClass(obj) end
--- Function that returns true only if the provided argument is an instance of a Discordia class.
---
--- ```lua
--- local color = Color(...)
--- print(class.isObject(color)) -- true
--- print(class.isObject(1337)) -- false
--- ```
---@param obj any
---@return boolean
function class.isObject(obj) end
--- Function that returns true if the first argument is a subclass of the second argument.
--- Note that classes are considered to be subclasses of themselves.
---
--- ```lua
--- print(class.isSubclass(TextChannel, Channel)) -- true
--- print(class.isSubclass(Color, Channel)) -- false
--- print(class.isSubclass(Channel, Channel)) -- true
--- ```
---@param obj any
---@param obj2 any
---@return boolean
function class.isSubclass(obj, obj2) end
--- Function that returns the type of the provided argument.
--- If the argument is a Discordia object, then this will return the name of its class; otherwise, it will return the result of calling Lua's global `type` function.
---
--- ```lua
--- print(class.type(color)) -- 'Color'
--- print(class.type(1337)) -- 'number'
--- ```
--- @param obj any
--- @return string
function class.type(obj) end
--- Function that returns the number of each class instance currently alive (ie, not garbage collected) in table form.
---
--- ```lua
--- local data = class.profile()
--- for name, count in pairs(data) do
--- print(name, count)
--- end
--- ```
---@return table<string, number>
function class.profile() end
-- @enums
---@class enums
--- The Discord API uses numbers to represent certain data types.
--- For convenience, these are enumerated in Discord as special read-only tables, found in the main Discordia module.
--- All available enumerations are listed at the end of this page.
---
--- ```lua
--- local discordia = require('discordia')
--- local enums = discordia.enums
--- ```
---
--- Enumerations (enums) can be accessed like a regular Lua table, but they cannot be modified.
--- This is completely optional, but it is generally easier to use and read enumerations than it is to use and read plain numbers.
--- For example, given a text channel object, the following are logically equivalent:
---
--- ```lua
--- if channel.type == 0 then
--- print('This is a text channel!')
--- end
---
--- if channel.type == enums.channelType.text then
--- print('This is a text channel!')
--- end
---
--- print(enums.verificationLevel.low) -- 1
--- ```
---
--- Additionally, enumerations work in reverse.
--- If you have the number, but you want to recall the human-readable version, simply call the enum;
--- it will return a string if the enumeration is valid.
---
--- ```lua
--- print(enums.channelType(channel.type)) -- 'text'
--- print(enums.verificationLevel(1)) -- 'low'
--- ```
---
--- If necessary, custom enumerations can be written using the enum constructor:
---
--- ```lua
--- local fruit = enums.enum {
--- apple = 0,
--- orange = 1,
--- banana = 2,
--- cherry = 3,
--- }
--- ```
---
--- ## Discord Enumerations
---
--- The enumerations are designed to be compatible with the Discord API. They are not necessarily unique to Discordia.
local enums = {}
--- Create a new enum
---@generic T
---@param data T
---@return T enum The newly constructed enum
function enums.enum(data) end
--- Extensions related to tables
---@class ext_table
---@overload fun()
local tableExt = {}
--- Returns the total number of elements in a table. This uses the global `pairs` function and respects any `__pairs` metamethods.
---@param tbl table
---@return number
function tableExt.count(tbl) end
--- Returns the total number of elements in a table, recursively.
--- If a table is encountered, it is recursively counted instead of being directly added to the total count.
--- This uses the global `pairs` function and respects any `__pairs` metamethods.
---@param tbl table
---@return number
function tableExt.deepcount(tbl) end
--- Returns a copy of the original table, recursively.
--- If a table is encountered, it is recursively deep-copied. Metatables are not copied.
---@param tbl table
---@return table
function tableExt.copy(tbl) end
--- Returns a copy of the original table, recursively.
--- If a table is encountered, it is recursively deep-copied. Metatables are not copied.
---@param tbl table
---@return table
function tableExt.deepcopy(tbl) end
--- Reverses the elements of an array-like table in place.
---@param tbl any[]
function tableExt.reverse(tbl) end
--- Returns a copy of an array-like table with its elements in reverse order.
--- The original table remains unchanged.
---@param tbl any[]
---@return any[]
function tableExt.reversed(tbl) end
--- Returns a new array-like table where all of its values are the keys of the original table.
---@param tbl table
---@return any[]
function tableExt.keys(tbl) end
--- Returns a new array-like table where all of its values are the values of the original table.
---@param tbl table
---@return any[]
function tableExt.values(tbl) end
--- Returns a random (index, value) pair from an array-like table.
---@param tbl any[]
---@return number, any
function tableExt.randomipair(tbl) end
--- Returns a random (key, value) pair from a dictionary-like table.
---@param tbl table
---@return any, any
function tableExt.randompair(tbl) end
--- Returns a copy of an array-like table sorted using Lua's `table.sort`.
---@param tbl any[]
---@param fn function
---@return any[]
function tableExt.sorted(tbl, fn) end
--- Iterates through a table until it finds a value that is equal to `value` according to the `==` operator.
--- The key is returned if a match is found.
---@param tbl table
---@param value any
---@return any
function tableExt.search(tbl, value) end
--- Returns a new table that is a slice of the original, defined by the start and stop bounds and the step size.
--- Default start, stop, and step values are 1, #tbl, and 1, respectively.
---@param tbl table
---@param start number
---@param stop number
---@param step number
---@return table
---@overload fun(tbl: table):table
---@overload fun(tbl: table, start: number):table
---@overload fun(tbl: table, start: number, stop: number):table
---@overload fun(tbl: table, start: number, stop: number, step: number):table
function tableExt.slice(tbl, start, stop, step) end
--- Utilities related to strings
---@class ext_string
---@overload fun()
local stringExt = {}
--- Splits a string into a table of specifically delimited sub-strings.
--- If the delimiter is omitted or empty, the string is split into a table of characters.
---@param str string
---@param delim string
---@return table
---@overload fun(str: string):table
function stringExt.split(str, delim) end
--- Returns a new string with all whitespace removed from the left and right sides of the original string.
---@param str string
---@return string
function stringExt.trim(str) end
---@alias alignment string | "'left'" | "'right'" | "'center'"
--- Returns a new string that is padded up to the desired length.
--- The alignment, either `left`, `right`, or `center` with left being the default, defines the placement of the original string.
--- The default pattern is a single space.
---@param str string
---@param len number
---@param align alignment
---@param pattern string
---@return string
---@overload fun(str: string, len: number):string
---@overload fun(str: string, len: number, align: alignment):string
function stringExt.pad(str, len, align, pattern) end
--- Returns whether a string starts with a specified sub-string or pattern.
--- The plain parameter is the same as that used in Lua's `string.find`.
---@param str string
---@param pattern string
---@param plain boolean
---@return boolean
---@overload fun(str: string, pattern: string):boolean
function stringExt.startswith(str, pattern, plain) end
--- Returns whether a string ends with a specified sub-string or pattern.
--- The plain parameter is the same as that used in Lua's `string.find`.
---@param str string
---@param pattern string
---@param plain boolean
---@return boolean
---@overload fun(str: string, pattern: string):boolean
function stringExt.endswith(str, pattern, plain) end
--- Returns the Levenshtein distance between two strings.
--- A higher number indicates a greater distance.
---@param str1 string
---@param str2 string
---@return number
function stringExt.levenshtein(str1, str2) end
--- Returns a string of random characters with the specified length.
--- If provided, the min and max bounds cannot be outside 0 to 255.
--- Use 32 to 126 for printable ASCII characters.
---@param len number
---@param min number
---@param max number
---@return string
---@overload fun(len: number):string
---@overload fun(len: number, min: number):string
function stringExt.random(len, min, max) end
--- Utilities related to math
---@class ext_math
---@overload fun()
local mathExt = {}
--- Returns a number that is at least as small as the minimum value and at most as large as the maximum value, inclusively.
--- If the original number is already with the bounds, the same number is returned.
---@param n number
---@param min number
---@param max number
---@return number
function mathExt.min(n, min, max) end
--- Returns a number that is rounded to the nearest defined digit.
--- The nearest integer is returned if the digit is omitted.
--- Negative values can be used for higher order places.
---@param n number
---@param digits number
---@return number
---@overload fun(n: number):number
function mathExt.round(n, digits) end
--- **Discordia** has some built-in Lua standard library extensions.
--- These provide complementary or supplementary, commonly used functions that the Lua standard library does not provide.
---
--- Extensions can be used directly...
---
--- ```lua
--- local str = " abc "
--- print(discordia.extensions.string.trim(str)) -- "abc"
--- ```
---
--- ... or they can be loaded into the global tables:
---
--- ```lua
--- local str = " abc "
--- discordia.extensions.string()
--- print(string.trim(str)) -- "abc"
--- ```
---
--- Note that calling the whole extensions module will load all sub-modules:
---
--- ```lua
--- discordia.extensions()
--- ```
---@class extensions
---@field public string ext_string
---@field public table ext_table
---@field public math ext_math
--@package
--- To write a Discordia application, the library's main module must be required. If it's in a deps or libs folder, simply require it by name.
--- If you've manually installed the library elsewhere, then you will need to provide a relative or full path to the Discordia directory.
---
--- ```lua
--- local discordia = require('discordia')
--- ```
---
--- ## Classes
---
--- Discordia has many custom classes. Some of them are instantiated only by the library and not by users.
--- The classes that may be safely instantiated by users are included in the Discordia module:
---
--- * Client
--- * Clock
--- * Color
--- * Date
--- * Deque
--- * Emitter
--- * Logger
--- * Mutex
--- * Permissions
--- * Stopwatch
--- * Time
---
--- ## Sub-Modules
---
--- In addition to classes, the Discordia module has some generic modules that may be helpful in writing your applications.
---
--- ### class
---
--- Used to create custom classes and provides tools for inspecting classes and class instances.
---
--- ### enums
---
--- Used to create custom enumerations or access a variety of pre-defined enumerations.
---
--- ### extensions
---
--- Extensions to the Lua standard library. Functions can be used directly or can be loaded into the Lua global tables.
---
--- ### package
---
--- Not to be confused with the global Lua module, this Discordia's literal package metadata, used to define the module when it is uploaded to lit, the Luvit Invention Toolkit.
---
--- ### storage
---
--- An empty table that can be used to store user data.
--- This may be used an alternative to storing values on class instances or in global variables, both of which are not recommended.
---
---@class discordia
---@field public Client Client
---@field public Clock Clock
---@field public Color Color
---@field public Date Date
---@field public Deque Deque
---@field public Emitter Emitter
---@field public Logger Logger
---@field public Mutex Mutex
---@field public Permissions Permissions
---@field public Stopwatch Stopwatch
---@field public Time Time
---@field public class class
---@field public enums enums
---@field public extensions extensions | function
---@field public package package
---@field public storage table<any, any>
local discordia = {}