1 | This tolua++ is modified with support for exception handling, and more will |
---|
2 | likely come over time. |
---|
3 | |
---|
4 | So to avoid forgetting how it works and what's new, all added features will |
---|
5 | be documented in full in this file: |
---|
6 | |
---|
7 | *********************** |
---|
8 | * Exception handling: * |
---|
9 | *********************** |
---|
10 | A new function modifier 'tolua_throws' has been added. It goes the same place |
---|
11 | as 'tolua_outside' etc. - so before the function name and return type. |
---|
12 | |
---|
13 | Two "types" of exceptions are supported internally, but they can be customized |
---|
14 | by making the tolua++ binary execute a Lua script before parsing with the '-L' |
---|
15 | command line option. |
---|
16 | Look in '../LuaScriptModule/package/exceptions.lua' to see the format. It's |
---|
17 | fairly simple and gives you alot of control. |
---|
18 | |
---|
19 | You always have 'std::exception' and 'any' (which means ...) available. |
---|
20 | |
---|
21 | This first example would be valid in a .pkg file for tolua++, and would ensure |
---|
22 | that any exceptions based on 'std::exception' thrown by the real C++ function |
---|
23 | would result in return value of 'nil' in Lua: |
---|
24 | |
---|
25 | tolua_throws|std::exception,nil| void I_Throw:StdException(); |
---|
26 | |
---|
27 | Inside the pipes the exception name follow by return values (or actions) are |
---|
28 | listed. The syntax is like so: |
---|
29 | |
---|
30 | tolua_throws|<exceptionName>[,<ret1>[,<ret2> ... [, <retN>]]]|[<exceptionName>...|] |
---|
31 | |
---|
32 | The return values can by any of the following: |
---|
33 | * nil |
---|
34 | * message (the exception message, or 'Unknown' if not possible. |
---|
35 | * true |
---|
36 | * false |
---|
37 | * error (can only be used alone, will contain the exception is possible) |
---|
38 | |
---|
39 | In case no return values are specified, it will default to: 'nil, message'. |
---|
40 | |
---|
41 | Example 1: |
---|
42 | ---------- |
---|
43 | Returns 'nil, false' for all exceptions: |
---|
44 | |
---|
45 | tolua_throws|any,nil,false| |
---|
46 | |
---|
47 | Example 2: |
---|
48 | ---------- |
---|
49 | Returns 'nil, message' if a 'std::exception' is thrown: |
---|
50 | |
---|
51 | tolua_throws|std::exception,nil,message| |
---|
52 | |
---|
53 | Example 3: |
---|
54 | ---------- |
---|
55 | If a CEGUI::Exception is thrown, return 'nil, message'. |
---|
56 | If any other kind of exception is thrown abort (error). |
---|
57 | |
---|
58 | tolua_throws|CEGUI::Exception|any,error| |
---|