Remove autotools build system.
[metze/wireshark/wip.git] / doc / README.wslua
1 README.wslua
2
3 This is a HOWTO for adding support for new Lua hooks/functions/abilities in
4 Wireshark.   If you see any errors or have any improvements, submit patches -
5 free software is a community effort....
6
7 This is NOT a guide for how to write Lua plugins - that's documented already
8 on the Wireshark webpages.
9
10 Contributors to this README:
11 Hadriel Kaplan <hadrielk[AT]yahoo.com>
12
13 ==============================================================================
14
15 Overview:
16
17 The way Wireshark exposes functions for Lua is generally based on a
18 callback/event model, letting Lua plugins register their custom Lua functions
19 into event callbacks.  C-based "objects" are exposed as Lua tables with
20 typical Lua USERDATA pointer dispatching, plain C-functions are registered as
21 such in Lua, and C-based enums/variables are registered into Lua as table
22 key=value (usually... though rarely they're registered as array indexed
23 values).  All of that is very typical for applications that expose things
24 into a Lua scripting environment.
25
26 The details that make it a little different are (1) the process by which the
27 code is bound/registered into Lua, and (2) the API documentation generator.
28 Wireshark uses C-macros liberally, both for the usual reasons as well as for
29 the binding generator and documentation generator scripts.  The macros are
30 described within this document.
31
32 The API documentation is auto-generated from a Perl script called 'make-
33 wsluarm.pl', which searches C-files for the known macros and generates
34 appropriate HTML documentation from them.  This includes using the C-comments
35 after the macros for the API document info.
36
37 Likewise, another Perl script called 'make-reg.pl' generates the C-files
38 'register_wslua.c' and 'declare_wslua.h', based on the C-macros it searches
39 for in existing source files.  The code this Perl script auto-generates is
40 what actually registers some classes/functions into Lua - you don't have to
41 write your own registration functions to get your new functions/classes into
42 Lua tables. (you can do so, but it's not advisable)
43
44 Both of the perl scripts above are given the C-source files to search through
45 by the make process, generated from the lists in epan/wslua/CMakeLists.txt.
46 Naturally if you add new source files, you need to add them to the list in
47 epan/wslua/CMakeLists.txt. You also have to add the module name into
48 docbook/user-guide.xml and docbook/wsluarm.xml, and the source files into
49 docbook/CMakeLists.txt, to get it to be generated in the user guide.
50
51 Another Perl script is used as well, called 'make-init-lua.pl', which
52 generates the init.lua script.  A large part of it deals with exposing #define
53 values into the Lua global table, or sub-tables.  Unfortunately not all of
54 them are put in sub-tables, which means the global Lua table is quite polluted
55 now.  If you add new ones in here, please think of putting them in a subtable,
56 as they are for wtap, ftypes, and base.  For example, there are several put in
57 as 'PI_' prefixed names, such as 'PI_SEVERITY_MASK = 15728640'.  The fact they
58 all have a common 'PI_' prefix should be an indicator they can be put in a
59 table named PI, or PacketInfo.  Just because C-code doesn't have namespaces,
60 doesn't mean Lua can't. This has now been fixed, and the PI_* names are now in
61 two separate subtables of a table named 'expert', as 'expert.group' and
62 'expert.severity' subtables. Follow that model in 'make-init-lua.pl'.
63
64
65 Due to those documentation and registration scripts, you MUST follow some very
66 specific conventions in the functions you write to expose C-side code to Lua,
67 as described in this document.
68
69 Naming conventions/rules:
70
71 Class/object names must be UpperCamelCase, no numbers/underscores.
72 Function and method names must be lower_underscore_case, no numbers.
73 Constants/enums must be ALLCAPS, and can have numbers.
74
75 The above rules are more than merely conventions - the Perl scripts which
76 auto-generate stuff use regex patterns that require the naming syntax to be
77 followed.
78
79 ==============================================================================
80
81 Documenting things for the API docs:
82
83 As explained previously, the API documentation is auto-generated from a
84 Perl script called 'make-wsluarm.pl', which searches C-files for the known
85 macros and generates appropriate HTML documentation from them. This includes
86 using the C-comments after the macros for the API document info. The comments
87 are extremely important, because the API documentation is what most Lua script
88 authors will see - do *not* expect them to go looking through the C-source code
89 to figure things out.
90
91 Please make sure to at least use the '@since' version notification markup
92 in your comments, to let users know when the new class/function/etc. you
93 created became available.
94
95 Because documentation is so important, the make-wsluarm.pl script supports
96 specific markup syntax in comments, and converts them to XML and ultimately
97 into the various documentation formats. The markup syntax is documented in
98 the top comments in make-wsluarm.pl, but are repeated here as well:
99   - two (or more) line breaks in comments result in separate paragraphs
100   - all '&' are converted into their entity names, except inside urls
101   - all '<', and '>' are converted into their entity names everywhere
102   - any word(s) wrapped in one star, e.g., *foo bar*, become italics
103   - any word(s) wrapped in two stars, e.g., **foo bar**, become bold
104   - any word(s) wrapped in backticks, e.g., `foo bar`, become bold (for now)
105   - any word(s) wrapped in two backticks, e.g., ``foo bar``, become one backtick
106   - any "[[url]]" becomes an XML ulink with the url as both the url and text
107   - any "[[url|text]]" becomes an XML ulink with the url as the url and text as text
108   - any indent with a single leading star '*' followed by space is a bulleted list item
109     reducing indent or having an extra linebreak stops the list
110   - any indent with a leading digits-dot followed by space, i.e. "1. ", is a numbered list item
111     reducing indent or having an extra linebreak stops the list
112   - supports meta-tagged info inside comment descriptions as follows:
113     * a line starting with "@note" or "Note:" becomes an XML note line
114     * a line starting with "@warning" or "Warning:" becomes an XML warning line
115     * a line starting with "@version" or "@since" becomes a "Since:" line
116     * a line starting with "@code" and ending with "@endcode" becomes an
117       XML programlisting block, with no indenting/parsing within the block
118     The above '@' commands are based on Doxygen commands
119
120
121 ==============================================================================
122
123 Some implementation details:
124
125 Creating new C-classes for Lua:
126
127 Explaining the Lua class/object model and how it's bound to C-code functions
128 and data types is beyond the scope of this document; if you don't already know
129 how that works, I suggest you start reading lua-users.org's wiki, and
130 lua.org's free reference manual.
131
132 Wireshark generally uses a model close to the typical binding
133 model: 'registering' class methods and metamethods, pushing objects into Lua
134 by applying the class' metatable to the USERDATA, etc.  This latter part is
135 mostly handled for you by the C-macro's created by WSLUA_CLASS_DEFINE, such as
136 push/check, described later in this document.
137
138 The actual way methods are dispatched is a little different from normal Lua
139 bindings, because attributes are supported as well (see next section). The
140 details won't be covered in this document - they're documented in the code
141 itself in: wslua_internals.c above the wslua_reg_attributes function.
142
143 Registering a class requires you to write some code: a WSLUA_METHODS table,
144 a WSLUA_META table, and a registration function.  The WSLUA_METHODS table is an
145 array of luaL_Reg structs, which map a string name that will be the function's
146 name in Lua, to a C-function pointer which is the C-function to be invoked by
147 Lua when the user calls the name.  Instead of defining this array of structs
148 explicitly using strings and function names, you should use the WSLUA_METHODS
149 macro name for the array, and use WSLUA_CLASS_FNREG macro for each entry.
150 The WSLUA_META table follows the same behavior, with the WSLUA_CLASS_MTREG
151 macro for each entry. Make sure your C-function names use two underscores
152 instead of one (for instance, ClassName__tostring).
153
154 Once you've created the appropriate array tables, define a registration
155 function named 'ClassName_register', where 'ClassName'is your class name, the
156 same one used in WSLUA_CLASS_DEFINE.  The make-reg.pl Perl script will search
157 your file for WSLUA_CLASS_DEFINE, and it generates a register_wslua.c which
158 will call your ClassName_register function during Wireshark initialization.
159 Define a wslua_class structure which describes the class and register this in
160 your ClassName_register function using one of:
161  - wslua_register_classinstance_meta to create a metatable which allows
162    instances of a class to have methods and attributes. C code can create such
163    instances by setting the metatable on userdata, the class itself is not
164    directly visible in the Lua scope.
165  - wslua_register_class to additionally expose a class with static functions
166    that is also directly visible in the Lua global scope.
167 Also, you should read the 'Memory management model' section later in this
168 document.
169
170 Class member variable attributes (getters/setters):
171
172 The current implementation does not follow a single/common class-variable
173 attribute accessor model for the Lua API: some class member values are
174 populated/retrieved when a table field attribute is used that triggers the
175 __index or __newindex metamethods, and others are accessed through explicit
176 getter/setter method functions.  In other words from a Lua code perspective
177 some class object variables are retrieves as 'foo = myObj.var', while others
178 are done as 'foo = myObj.getVar()'.
179
180 From the C-side code perspective, some classes register no real method
181 functions but just have attributes (and use the WSLUA_ATTRIBUTE documentation
182 model for them). For example the FieldInfo class in wslua_field.c does this.
183 Other classes provide access to member variable through getter/setter method
184 functions (and thus use the WSLUA_METHOD documentation model). For example
185 the TvbRange class in wslua_tvb.c does this. Using the latter model of having
186 a getter/setter method function allows one to pass multiple arguments, whereas
187 the former __index/__newindex metamethod model does not. Both models are
188 fairly common in Lua APIs, although having a mixture of both in the same API
189 probably isn't.  There is even a third model in use: pre-loading the member
190 fields of the class table with the values, instead of waiting for the Lua
191 script to access a particular one to retrieve it; for example the Listener tap
192 extractors table is pre-populated (see files 'wslua_listener.c' and 'taps'
193 which through the make-taps.pl perl script creates 'taps_wslua.c'). The
194 downside of that approach is the performance impact, filling fields the Lua
195 script may never access.  Lastly, the Field, FieldInfo, and Tvb's ByteArray
196 type each provide a __call metamethod as an accessor - I strongly suggest you
197 do NOT do that, as it's not a common model and will confuse people since it
198 doesn't follow the model of the other classes in Wireshark.
199
200 Attributes are handled internally like this:
201
202     -- invoked on myObj.myAttribute
203     function myObj.__metatable:__index(key)
204         if "getter for key exists" then
205             return getter(self)
206         elseif "method for key exists" then
207             -- ensures that myObj.myMethod() works
208             return method
209         else
210             error("no such property error message")
211         end
212     end
213     -- invoked on myObj.myAttribute = 1
214     function myObj.__metatable:__newindex(key, value)
215         if "setter for key exists" then
216             return setter(self, value)
217         else
218             error("no such property error message")
219         end
220     end
221
222 To add getters/setters in C, initialize the "attrs" member of the wslua_class
223 structure. This should contain an array table similar to the WSLUA_METHODS and
224 WSLUA_META tables, except using the macro name WSLUA_ATTRIBUTES. Inside this
225 array, each entry should use one of the following macros: WSLUA_ATTRIBUTE_ROREG,
226 WSLUA_ATTRIBUTE_WOREG, or WSLUA_ATTRIBUTE_RWREG. Those provide the hooks for
227 a getter-only, setter-only, or both getter and setter function. The functions
228 themselves need to follow a naming scheme of ClassName_get_attributename(),
229 or ClassName_set_attributename(), for the respective getter vs. setter function.
230 Trivial getters/setters have macros provided to make this automatic, for things
231 such as getting numbers, strings, etc. The macros are in wslua.h. For example,
232 the WSLUA_ATTRIBUTE_NAMED_BOOLEAN_GETTER(Foo,bar,choo) macro creates a getter
233 function to get the boolean value of the Class Foo's choo member variable, as
234 the Lua attribute named 'bar'.
235
236 Callback function registration:
237
238 For some callbacks, there are register_* Lua global functions, which take a
239 user-defined Lua function name as the argument - the one to be hooked into
240 that event.  Unlike in most Lua APIs, there's a unique register_foo() function
241 for each event type, instead of a single register() with the event as an
242 argument.  For example there's a register_postdissector() function.  In some
243 cases the Lua functions are invoked based on a pre-defined function-name model
244 instead of explicit register_foo(), whereby a C-object looks for a defined
245 member variable in the Registry that represents a Lua function created by the
246 plugin.  This would be the case if the Lua plugin had defined a pre-defined
247 member key of its object's table in Lua, for that purpose.  For example if the
248 Lua plugin sets the 'reset' member of the Listener object table to a function,
249 then Wireshark creates a Registry entry for that Lua function, and executes
250 that Lua function when the Listener resets. (see the example Listener Lua
251 script in the online docs) That model is only useful if the object can only be
252 owned by one plugin so only one function is ever hooked, obviously, and thus
253 only if it's created by the Lua plugin (e.g., Listener.new()).
254
255 Creating new Listener tap types:
256
257 The Listener object is one of the more complicated ones.  When the Lua script
258 creates a Listener (using Listener.new()), the code creates and returns a tap
259 object.  The type of tap is based on the passed-in argument to Listener.new(),
260 and it creates a Lua table of the tap member variables.  That happens in
261 taps_wslua.c, which is an auto-generated file from make-taps.pl.  That Perl
262 script reads from a file called 'taps', which identifies every struct name
263 (and associated enum name) that should be exposed as a tap type.  The Perl
264 script then generates the taps_wslua.c to push those whenever the Listener
265 calls for a tap; and it also generates a taps.tx file documenting them all.
266 So to add a new type, add the info to the taps file (or uncomment an existing
267 one), and make sure every member of the tap struct you're exposing is of a
268 type that make-taps.pl has in its Perl %types and %comments associative
269 arrays.
270
271 Note on Lua versions:
272
273 Wireshark supports both Lua 5.1 and 5.2, which are defined as LUA_VERSION_NUM
274 values 501 and 502 respectively.  When exposing things into Lua, make sure to
275 use ifdef wrappers for things which changed between the versions of Lua.  See
276 this for details: http://www.lua.org/manual/5.2/manual.html#8.3
277
278 ==============================================================================
279
280 Defined Macros for Lua-API C-files:
281
282 WSLUA_MODULE - this isn't actually used in real C-code, but rather only
283 appears in C-comments at the top of .c files.  That's because it's purely used
284 for documentation, and it makes a new section in the API documentation.
285
286 For example, this appears near the top of the wslua_gui.c file:
287
288     /* WSLUA_MODULE Gui GUI support */
289
290 That makes the API documentation have a section titled 'GUI support' (it's
291 currently section 11.7 in the API docs).  It does NOT mean there's any Lua
292 table named 'Gui' (in fact there isn't).  It's just for documentation.
293 If you look at the documentation, you'll see there is 'ProgDlg', 'TextWindow',
294 etc. in that 'GUI support' section.  That's because both ProgDlg and
295 TextWindow are defined in that same wslua_gui.c file using the
296 'WSLUA_CLASS_DEFINE' macro. (see description of that later)  make-wsluarm.pl
297 created those in the same documentation section because they're in the same c
298 file as that WSLUA_MODULE comment.  You'll also note the documentation
299 includes a sub-section for 'Non Method Functions', which it auto-generated
300 from anything with a 'WSLUA_FUNCTION' macro (as opposed to class member
301 functions, which use the 'WSLUA_METHOD' and 'WSLUA_CONSTRUCTOR' macros). Also,
302 to make new wslua files generate documentation, it is not sufficient to just
303 add this macro to a new file and add the file to the CMakeLists.txt; you also
304 have to add the module name into docbook/user-guide.xml, and docbook/wsluarm.xml.
305
306
307 WSLUA_CONTINUE_MODULE - like WSLUA_MODULE, except used at the top of a .c file
308 to continue defining classes/functions/etc. within a previously declared module
309 in a previous file (i.e., one that used WSLUA_MODULE). The module name must match
310 the original one, and the .c file must be listed after the original one in the
311 CMakeLists.txt lists in the docbook directory.
312
313
314 WSLUA_ATTRIBUTE - this is another documentation-only "macro", only used within
315 comments.  It makes the API docs generate documentation for a member variable
316 of a class, i.e. a key of a Lua table that is not called as a function in Lua,
317 but rather just retrieved or set.  The 'WSLUA_ATTRIBUTE' token is followed by
318 a 'RO', 'WO', or 'RW' token, for Read-Only, Write-Only, or Read-Write. (ie,
319 whether the variable can be retrieved, written to, or both)  This read/write
320 mode indication gets put into the API documentation. After that comes the name
321 of the attribute, which must be the class name followed by the specific
322 attribute name.
323
324 Example:
325
326     /* WSLUA_ATTRIBUTE Pinfo_rel_ts RO Number of seconds passed since beginning of capture */
327
328
329
330 WSLUA_FUNCTION - this is used for any global Lua function (functions put into
331 the global table) you want to expose, but not for object-style methods (that's
332 the 'WSLUA_METHOD' macro), nor static functions within an object (that's
333 WSLUA_CONSTRUCTOR).  Unlike many of the macros here, the function name must
334 begin with 'wslua_'.  Everything after that prefix will be the name of the
335 function in Lua.  You can ONLY use lower-case letters and the underscore
336 character in this function name.  For example 'WSLUA_FUNCTION
337 wslua_get_foo(lua_State* L)' will become a Lua function named 'get_foo'.
338 Documentation for it will also be automatically generated, as it is for the
339 other macros.  Although from a Lua perspective it is a global function (not in
340 any class' table), the documentation will append it to the documentation page
341 of the module/file its source code is in, in a "Non Method Functions" section.
342 Descriptive text about the function must be located after the '{' and optional
343 whitespace, within a '\*' '*\' comment block on one line.
344
345 Example:
346
347     WSLUA_FUNCTION wslua_gui_enabled(lua_State* L) { /* Checks whether the GUI facility is enabled. */
348         lua_pushboolean(L,GPOINTER_TO_INT(ops && ops->add_button));
349         WSLUA_RETURN(1); /* A boolean: true if it is enabled, false if it isn't. */
350     }
351
352
353 WSLUA_CLASS_DEFINE - this is used to define/create a new Lua class type (i.e.,
354 table with methods).  A Class name must begin with an uppercase letter,
355 followed by any upper or lower case letters but not underscores; in other
356 words, UpperCamelCase without numbers.  The macro is expanded to create a
357 bunch of helper functions - see wslua.h.  Documentation for it will also be
358 automatically generated, as it is for the other macros.
359
360 Example:
361
362     WSLUA_CLASS_DEFINE(ProgDlg,NOP,NOP); /* Manages a progress bar dialog. */
363
364
365 WSLUA_CONSTRUCTOR - this is used to define a function of a class that is a
366 static function rather than a per-object method; i.e., from a Lua perspective
367 the function is called as 'myObj.func()' instead of 'myObj:func()'.  From a
368 C-code perspective the code generated by make-reg.pl does not treat this
369 differently than a WSLUA_METHOD, the only real difference being that the code
370 you write within the function won't be checking the object instance as the
371 first passed-in argument on the Lua-API stack.  But from a documentation
372 perspective this macro correctly documents the usage using a '.' period rather
373 than ':' colon.  This can also be used within comments, but then it's
374 '_WSLUA_CONSTRUCTOR_'.  The name of the function must use the Class name
375 first, followed by underscore, and then the specific lower_underscore name
376 that will end up being the name of the function in Lua.
377
378 Example:
379
380     WSLUA_CONSTRUCTOR Dissector_get (lua_State *L) {
381         /* Obtains a dissector reference by name */
382     #define WSLUA_ARG_Dissector_get_NAME 1 /* The name of the dissector */
383         const gchar* name = luaL_checkstring(L,WSLUA_ARG_Dissector_get_NAME);
384         Dissector d;
385
386         if (!name)
387             WSLUA_ARG_ERROR(Dissector_get,NAME,"must be a string");
388
389         if ((d = find_dissector(name))) {
390             pushDissector(L, d);
391             WSLUA_RETURN(1); /* The Dissector reference */
392         } else
393             WSLUA_ARG_ERROR(Dissector_get,NAME,"No such dissector");
394     }
395
396
397 WSLUA_METHOD - this is used for object-style class method definitions.  The
398 documentation will use the colon syntax, and it will be called as
399 'myObj:func()' in Lua, so your function needs to check the first argument of
400 the stack for the object pointer.  Two helper functions are automatically made
401 for this purpose, from the macro expansion of WSLUA_CLASS_DEFINE, of the
402 signatures 'MyObj toMyObj(lua_State* L, int idx)' and 'MyObj
403 checkMyObj(lua_State* L, int idx)'.  They do the same thing, but the former
404 generates a Lua Error on failure, while the latter does not.
405
406 Example:
407
408     WSLUA_METHOD Listener_remove(lua_State* L) {
409         /* Removes a tap listener */
410         Listener tap = checkListener(L,1);
411         if (!tap) return 0;
412         remove_tap_listener(tap);
413         return 0;
414     }
415
416
417 WSLUA_METAMETHOD - this is used for defining object metamethods (ie, Lua
418 metatable functions).  The documentation will describe these as well, although
419 currently it doesn't specify they're metamethods but rather makes them appear
420 as regular object methods.  The name of it must be the class name followed by
421 *two* underscores, or else it will not appear in the documentation.
422
423 Example:
424
425     WSLUA_METAMETHOD NSTime__eq(lua_State* L) { /* Compares two NSTimes */
426         NSTime time1 = checkNSTime(L,1);
427         NSTime time2 = checkNSTime(L,2);
428         gboolean result = FALSE;
429
430         if (!time1 || !time2)
431           WSLUA_ERROR(FieldInfo__eq,"Data source must be the same for both fields");
432
433         if (nstime_cmp(time1, time2) == 0)
434             result = TRUE;
435
436         lua_pushboolean(L,result);
437
438         return 1;
439     }
440
441
442 WSLUA_ARG_ - the prefix used in a #define statement, for a required
443 function/method argument (ie, one without a default value).  It is defined to
444 an integer representing the index slot number of the Lua stack it will be at,
445 when calling the appropriate lua_check/lua_opt routine to get it from the
446 stack.  The make_wsluarm.pl Perl script will generate API documentation with
447 this argument name for the function/method, removing the 'WSLUA_ARG_' prefix.
448 The name following the 'WSLUA_ARG_' prefix must be the same name as the
449 function it's an argument for, followed by an underscore and then an ALLCAPS
450 argument name (including numbers is ok).  Although this last part is in
451 ALLCAPS, it is documented in lowercase.  The argument name itself is
452 meaningless since it does not exist in Lua or C code.
453
454 Example: see the example in WSLUA_CONSTRUCTOR above, where
455 WSLUA_ARG_Dissector_get_NAME is used.
456
457
458 WSLUA_OPTARG_ - the prefix used in a #define statement, for an optional
459 function/method argument (ie, one with a default value).  It is defined to an
460 integer representing the index slot number of the Lua stack it will be at,
461 when calling the appropriate lua_check/lua_opt routine to get it from the
462 stack.  The make_wsluarm.pl Perl script will generate API documentation with
463 this argument name for the function/method, removing the 'WSLUA_OPTARG_'
464 prefix.  The rules for the name of the argument after the prefix are the same
465 as for 'WSLUA_ARG_' above.
466
467 Example:
468
469     #define WSLUA_OPTARG_Dumper_new_FILETYPE 2 /* The type of the file to be created */
470
471
472 WSLUA_MOREARGS - a documentation-only macro used to document that more
473 arguments are expected/supported.  This is useful when the number of
474 arguments is not fixed, i.e., a vararg model.  The macro is followed by the
475 name of the function it's an argument for (without the 'wslua_' prefix if the
476 function is a WSLUA_FUNCTION type), and then followed by descriptive text.
477
478 Example:
479
480     WSLUA_FUNCTION wslua_critical( lua_State* L ) { /* Will add a log entry with critical severity*/
481     /* WSLUA_MOREARGS critical objects to be printed    */
482         wslua_log(L,G_LOG_LEVEL_CRITICAL);
483         return 0;
484     }
485
486
487 WSLUA_RETURN - a macro with parentheses containing the number of return
488 values, meaning the number of items pushed back to Lua.  Lua supports multiple
489 return values, although Wireshark usually just returns 0 or 1 value.  The
490 argument can be an integer or a variable of the integer, and is not actually
491 documented.  The API documentation will use the comments after this macro for
492 the return description.  This macro can also be within comments, but is then
493 '_WSLUA_RETURNS_'.
494
495 Example:
496
497     WSLUA_RETURN(1); /* The ethernet pseudoheader */
498
499
500 WSLUA_ERROR - this C macro takes arguments, and expands to call luaL_error()
501 using them, and returns 0.  The arguments it takes is the full function name
502 and a string describing the error.  For documentation, it uses the string
503 argument and displays it with the function it's associated to.
504
505 Example:
506     if (!wtap_dump_can_write_encap(filetype, encap))
507         WSLUA_ERROR(Dumper_new,"Not every filetype handles every encap");
508
509
510 WSLUA_ARG_ERROR - this is a pure C macro and does not generate any
511 documentation.  It is used for errors in type/value of function/method
512 arguments.
513
514 Example: see the example in thr WSLUA_CONSTRUCTOR above.
515
516
517 ==============================================================================
518
519 Memory management model:
520
521 Lua uses a garbage collection model, which for all intents and purposes can
522 collect garbage at any time once an item is no longer referenced by something
523 in Lua.  When C-malloc'ed values are pushed into Lua, the Lua library has to
524 let you decide whether to try to free them or not.  This is done through the
525 '__gc' metamethod, so every Wireshark class created by WSLUA_CLASS_DEFINE must
526 implement a metamethod function to handle this.  The name of the function must
527 be 'ClassName__gc', where 'ClassName' is the same name as the class.  Even if
528 you decide to do nothing, you still have to define the function or it will
529 fail to compile - as of this writing, which changed it to do so, in order to
530 make the programmer think about it and not forget.
531
532 The thing to think about is the lifetime of the object/value.  If C-code
533 controls/manages the object after pushing it into Lua, then C-code MUST NOT
534 free it until it knows Lua has garbage collected it, which is only known by
535 the __gc metamethod being invoked.  Otherwise you run the risk of the Lua
536 script trying to use it later, which will dereference a pointer to something
537 that has been free'd, and crash.  There are known ways to avoid this, but
538 those ways are not currently used in Wireshark's Lua API implementation;
539 except Tvb and TvbRange do implement a simple model of reference counting to
540 protect against this.
541
542 If possible/reasonable, the best model is to malloc the object when you push
543 it into Lua, usually in a class function (not method) named 'new', and then
544 free it in the __gc metamethod.  But if that's not reasonable, then the next
545 best model is to have a boolean member of the class called something like
546 'expired', which is set to true if the C-code decides it is dead/no-longer-
547 useful, and then have every Lua-to-C accessor method for that class type check
548 that boolean before trying to use it, and have the __gc metamethod set
549 expired=true or free it if it's already expired by C-side code; and vice-versa
550 for the C-side code.
551
552 In some cases the class is exposed with a specific method to free/remove it,
553 typically called 'remove'; the Listener class does this, for example.  When
554 the Lua script calls myListener:remove(), the C-code for that class method
555 free's the Listener that was malloc'ed previously in Listener.new().  The
556 Listener__gc() metamethod does not do anything, since it's hopefully already
557 been free'd.  The downside with this approach is if the script never calls
558 remove(), then it leaks memory; and if the script ever tries to use the
559 Listener userdata object after it called remove(), then Wireshark crashes.  Of
560 course either case would be a Lua script programming error, and easily
561 fixable, so it's not a huge deal.
562
563 ==============================================================================
564