blob: a30904e23e7f8c56d96b1b2a495dc643da4a203b [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001CONCEPT
2 modifiers
3
4DESCRIPTION
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
174HISTORY
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
181SEE ALSO
182 closures(LPC), inheritance(LPC), functions(LPC), types(LPC)