MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | CONCEPT |
| 2 | functions |
| 3 | |
| 4 | DESCRIPTION |
| 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 | |
| 172 | SEE ALSO |
| 173 | types(LPC), modifiers(LPC), varargs(LPC), references(LPC), |
| 174 | call_other(E), simul_efun(C), call_out(E) |