blob: 50c39a0a4b8eb8115e317ad41e9463866649616b [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001CONCEPT
2 functions
3
4DESCRIPTION
5 Functions are named blocks of code which are be called with
6 a number of argument values, and which return a result value
7 to the caller.
8
9 Functions are defined in an object and are also known as
10 "local funs" or short "lfuns".
11
12
13 DEFINING A FUNCTION
14
15 A function definition takes the form
16
17 <modifiers> <type> name ( <arguments> ) {
18 statements...
19 }
20
21 The parts in detail:
22 - <modifiers> can be any one of "static", "private", "public"
23 and "protected" (see modifiers(LPC)), optionally combined
24 with "varargs" (see varargs(LPC)) and/or "nomask".
25 If not specified, the function behaves as if it was
26 specified as "public", but this visibility can be restricted
27 in derived object through non-public inheritance.
28 - <type> is the type of the result returned by the function.
29 If specified as "void", the function is compiled to return
30 the value 0 under all circumstances. If not specified, the
31 type is assumed to be "mixed", furthermore typechecking is
32 disabled for this function.
33 - name is the name of the function, e.g. "short", or "Nice_Try",
34 under which it is made known.
35 - <arguments> is a list of variable definitions in the
36 normal '<type> <name>' style, separated by comma.
37 Examples: () : no argument taken
38 (int a) : takes on integer argument
39 (mixed a, object *b): takes two arguments, one
40 arbitrary type, one array of objects.
41 - { statements... } defines the code for this function. This
42 is a normal block (see block(LPC)) and as such can define
43 its own local variables.
44
45
46 DECLARING A FUNCTION
47
48 A function declaration makes the name and type of a function known
49 to the compiler with the assertion that the code for this function
50 will be provided "elsewhere".
51
52 The form is:
53
54 <modifiers> <type> name ( <arguments> );
55
56 Typical uses are:
57 - to declare in advance functions which are called before they
58 can be defined; for example if the create() function of an object
59 calls other functions which are defined after the create().
60 - to declare functions which will be provided by an inheriting
61 object.
62
63 Calling a declared but undefined function results in a runtime error.
64
65
66 CALLING A FUNCTION
67
68 Functions in other objects are called with the call_other() efun,
69 which can be shortened to '->':
70
71 ob->fun(a, b, c)
72 call_other(ob, "fun", a, b, c)
73
74 Note: See the entry H_DEFAULT_METHOD in hooks(C) for a modification
75 of this behaviour.
76
77 Functions in the same object are called just by writing their name,
78 followed by the arguments in parenthesis:
79
80 short()
81 compute(a)
82 do_that(a, "foo")
83
84 Array function arguments can be 'flattened' with the '...' operator.
85 For example:
86
87 mixed * m = ({ "foo", "bar" });
88 fun(m..., 1);
89
90 will be executed as:
91
92 fun("foo", "bar", 1);
93
94
95 If the number of values passed to the function does not match the
96 number of expected arguments (and if type checking is not enabled), the
97 driver will perform the necessary adaption at call time: excess
98 values are ignored, missing values are substituted by the number 0.
99 The values passed to the called function are massaged by the driver
100 to match the argument list
101
102
103 FUNCTIONS AND INHERITANCE
104
105 A "public" or "protected" (== "static") function defined in one
106 object is also visible in all inheriting objects. The exception from
107 this rule is when an inheriting child redefines ("overloads") the
108 inherited function with its own. When compiling with type checking,
109 the argument list of the redefined function has to match the
110 original one.
111
112 When a function is called, the driver looks for the function first
113 in the object called, and if not found there, then in the inherited
114 objects.
115
116 To explicitely call an inherited function (useful when a redefining
117 functions wants to use the original one), the "::" operator is used:
118
119 ::create()
120 ::compute(a)
121
122 The named function is searched only in the inherited objects, and
123 the first found is used.
124
125
126 If the function is inherited from several objects and a specific
127 one is to be called, the "::" can be extended to contain the
128 partial or full name of the inherited object:
129
130 inherit "/obj/cooker";
131 inherit "/obj/container";
132
133 tainer::create()
134 container::create()
135 "tainer"::create()
136 "container"::create()
137 "obj/container"::create()
138 "/obj/container"::create()
139
140 all call the create() in the container inherit. Note that the
141 name given to the :: operator is matched against the ends of
142 the inherited names.
143
144
145 One special form of this call is
146
147 efun::find_object()
148
149 which bypasses any redefinition of an efun (here find_object())
150 and directly calls the efun itself. This is only possible for
151 efun-redefinitions which do not use the "nomask" modifier.
152
153
154 Additionally, a call to a function inherited from several objects
155 can be instructed to call _all_ inherited functions through the
156 use of the wildcards "*" (match any number of arbitrary characters)
157 and "?" (match one arbitrary character):
158
159 inherit "/obj/cooker";
160 inherit "/obj/container";
161
162 "*"::create()
163 "co*"::create()
164 "*er"::create()
165
166 all call both inherited create()s. The function called this way
167 must not take arguments, and the single results from all calls are
168 combined into one array used as final result. If there is no such
169 function inherited at all, the statement will just return
170 an empty array.
171
172SEE ALSO
173 types(LPC), modifiers(LPC), varargs(LPC), references(LPC),
174 call_other(E), simul_efun(C), call_out(E)