MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | CONCEPT |
| 2 | modifiers |
| 3 | |
| 4 | DESCRIPTION |
| 5 | A modifier changes the syntactic and/or semantic behaviour of |
| 6 | an object-global variable or a function in an object. |
| 7 | The existing modifiers are described below. |
| 8 | To use a modifier just prepend it to the declaration. If several |
| 9 | modifiers are to be used their order does not matter: |
| 10 | |
| 11 | private int bar; // example for a variable |
| 12 | protected nomask int foo() { return 3; } // example for a function |
| 13 | |
| 14 | For functions: |
| 15 | ~~~~~~~~~~~~~~ |
| 16 | private -- such functions can only be called with an internal |
| 17 | call from within this file. Not even inheriting |
| 18 | objects can call these functions. You can nevertheless |
| 19 | build an lfun-closure with #' out of a private function |
| 20 | (but you cannot save and restore it). |
| 21 | protected -- such functions can be called from within the object, |
| 22 | or from inheriting objects; but in neither case |
| 23 | with call_other(). It is possible to create #' closures |
| 24 | or use symbol_function() from within the object. |
| 25 | Its use is preferred over the older "static". |
| 26 | static -- such functions can be called from within the object |
| 27 | in either way (internal call or with call_other()). |
| 28 | Inheriting objects can call such functions. |
| 29 | But it is not possible to call static functions from |
| 30 | other objects via call_other(). |
| 31 | The use of 'static' in new code is not recommended. |
| 32 | Note that an add_action() is treated like a call |
| 33 | from within the object except the player who got the |
| 34 | add_action() was forced (thus it is a simple way to |
| 35 | secure an add_action() against forces, although this |
| 36 | method has the severe disadvantages of raising an error |
| 37 | at the force so better use the security system). |
| 38 | Also efuns like call_out() or input_to() can call |
| 39 | these functions if given as a string. |
| 40 | public -- this is the default type. Such functions can be called |
| 41 | from within the file as well as from inheriting objects |
| 42 | and other objects via call_other(). |
| 43 | To declare a function public only results in the |
| 44 | impossibility to change the accessibility at the |
| 45 | inherit statement (see below). No error will occur, |
| 46 | only the type will not be modified by the inherit |
| 47 | statement. |
| 48 | nomask -- such functions cannot be overridden by inheriting |
| 49 | objects. If you have the fun foo() defined in your |
| 50 | object and inherit an object which also has declared |
| 51 | a function foo() and this nomask, you will get an |
| 52 | compile error if you try to load your object. |
| 53 | Furthermore a shadow will fail if it tries to shadow |
| 54 | a nomask declared function. |
| 55 | varargs -- this changes the syntax of the function in a way that |
| 56 | not all of the arguments in the declaration must be |
| 57 | given at the call. This is often very usefull if some |
| 58 | of the arguments shall be omitable (the omitted |
| 59 | arguments are set to 0 if the function is called with |
| 60 | fewer arguments than specified). |
| 61 | This is mainly within the object really necessary; |
| 62 | call_other()s usually (that is if they do not have a |
| 63 | certain pragma ('man pragma')) do not need the called |
| 64 | function to be declared varargs to omit any arguments, |
| 65 | but it is good style to use this modifier to document |
| 66 | the code by this. |
| 67 | deprecated - Whenever this function is called, a warning is issued. |
| 68 | Usually this is done at compile-time. Exceptions are |
| 69 | call_others and symbol_function() which warn at run-time. |
| 70 | |
| 71 | For object-global variables: |
| 72 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 73 | private -- such variables can only be accessed from within the |
| 74 | same object. Not even inheriting objects can access |
| 75 | private variables. |
| 76 | It is a good style to declare all internal variables |
| 77 | private to prevent inheriting objects from accessing |
| 78 | the variables directly without using functions. |
| 79 | nosave -- such variables are neither stored with save_object() |
| 80 | nor restored with restore_object(). This can be very |
| 81 | useful if you want a room to use save_object() and |
| 82 | restore_object() to save your own defined variables |
| 83 | but not the hundreds of variables inherited from a |
| 84 | room-class (e.g. /complex/room). You then use the modifier |
| 85 | at the inherit statement (see below). |
| 86 | Note that nosave and private do not overlap in any |
| 87 | way. They are absolutely independant. |
| 88 | static -- the old name for 'nosave'. Its use is deprecated. |
| 89 | public -- declares the variable public. It cannot be declared |
| 90 | private or static by inheriting. No error will occur, |
| 91 | only the type will not be modified by the inherit |
| 92 | statement. |
| 93 | deprecated - Whenever this variable is used, a warning is issue. |
| 94 | Usually this is done at compile-time, but |
| 95 | symbol_variable() warns at run-time. |
| 96 | |
| 97 | It is no good style to let inheriting objects have access to |
| 98 | internal variables so declare them as private and offer functions |
| 99 | to query and change the variables if possible. |
| 100 | |
| 101 | It is also possible to redeclare all variables and/or functions |
| 102 | of an inherited object for the own object at the inheriting |
| 103 | statement: |
| 104 | |
| 105 | private functions nosave variables inherit "complex/room"; |
| 106 | public variables inherit "complex/room"; |
| 107 | private functions inherit "complex/room"; |
| 108 | |
| 109 | To redeclare a function or a variable declared public in the |
| 110 | inherited object to be private or protected is not possible. |
| 111 | |
| 112 | There also exists a modifier explicitly for the inherit statement: |
| 113 | |
| 114 | virtual -- inherits the given object virtually. This only makes |
| 115 | sense in a complex inherit tree. |
| 116 | If an object is inherited normally (not virtually) |
| 117 | twice somewhere in the inherit tree the intern |
| 118 | variables exist twice. If inherited virtually they |
| 119 | exist only once. |
| 120 | Example: |
| 121 | A inherits B and C. |
| 122 | B inherits D. |
| 123 | C inherits D. |
| 124 | If the inheritance of D is virtual in B and C |
| 125 | D's variables exist only once in A. If A changes |
| 126 | D's variables via functions of B this also changes |
| 127 | the variables of D as known by C. |
| 128 | |
| 129 | virtual: non-virtual: |
| 130 | A A |
| 131 | / \ / \ |
| 132 | B C B C |
| 133 | \ / | | |
| 134 | D D D |
| 135 | |
| 136 | |
| 137 | To simplify the adoption of existing code, LPC allows to specify |
| 138 | a default visibility for functions and variables, using a syntax |
| 139 | similar to the inherit syntax: |
| 140 | |
| 141 | default private; |
| 142 | |
| 143 | All variables and functions are by default private. |
| 144 | |
| 145 | default private variables public functions; |
| 146 | |
| 147 | All variables are by default private, but functions are public. |
| 148 | |
| 149 | Only the modifiers 'private', 'public' and 'protected' (and 'static' |
| 150 | for functions only) are allowed here. |
| 151 | |
| 152 | The default visibility thus set affects only variables/functions with |
| 153 | no explicite visibility: |
| 154 | |
| 155 | default private; |
| 156 | |
| 157 | int private_var; |
| 158 | public int public_var; |
| 159 | |
| 160 | The definition is valid from the point of the 'default' statement |
| 161 | until the end of the file, or until the next 'default' statement: |
| 162 | |
| 163 | default private; |
| 164 | |
| 165 | int private_var; |
| 166 | |
| 167 | default public; |
| 168 | |
| 169 | int public_var; |
| 170 | |
| 171 | Note that this default visibility does not affect inherits. |
| 172 | |
| 173 | |
| 174 | HISTORY |
| 175 | The modifier 'static' for variables was renamed to 'nosave' |
| 176 | with LDMud 3.2.8. 'static' is still recognized as an alias. |
| 177 | |
| 178 | The default visibility was added in LDMud 3.2.9 as experimental |
| 179 | feature. |
| 180 | |
| 181 | SEE ALSO |
| 182 | closures(LPC), inheritance(LPC), functions(LPC), types(LPC) |