blob: 4f44cdc032894a2af41189e339c5e7b30194183c [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001 LPC Basics
2 Written by Descartes of Borg
3 first edition: 23 april 1993
4 second edition: 22 june 1993
5
6CHAPTER 4: Functions
7
84.1 Review
9By this point, you should be aware that LPC objects consist of functions
10which manipulate variables. The functions manipulate variables when they
11are executed, and they get executed through *calls* to those functions.
12The order in which the functions are placed in a file does not matter.
13Inside a function, the variables get manipulated. They are stored in
14computer memory and used by the computer as 0's and 1's which
15get translated to and from useable output and input through a device
16called data typing. String data types tell the driver that the
17data should appear to you and come from you in the form of alphanumeric
18characters. Variables of type int are represented to you as whole
19number values. Type status is represented to you as either 1 or 0.
20And finally type void has no value to you or the machine, and is not
21really used with variable data types.
22
234.2 What is a function?
24Like math functions, LPC functions take input and return output.
25Languages like Pascal distinguish between the concept of proceedure abd
26the concept of function. LPC does not, however, it is useful to
27understand this distinction. What Pascal calls a proceedure, LPC
28calls a function of type void. In other words, a proceedure, or function
29of type void returns no output. What Pascal calls a function differs
30in that it does return output. In LPC, the most trivial, correct
31function is:
32
33-----
34void do_nothing() { }
35-----
36
37This function accepts no input, performs no instructions, and returns no
38value.
39
40There are three parts to every properly written LPC function:
411) The declaration
422) The definition
433) The call
44
45Like with variables, functions must be declared. This will allow the
46driver to know 1) what type of data the function is returning as output,
47and 2) how many input(s) and of what type those input(s) are. The
48more common word for input is parameters.
49A function declaration therefore consists of:
50type name(parameter1, parameter2, ..., parameterN);
51The declaration of a function called drink_water() which accepts a string as
52input and an int as output would thus look like this:
53
54-----
55int drink_water(string str);
56-----
57
58where str is the name of the input as it will be used inside the function.
59
60The function definition is the code which describes what the function actually
61does with the input sent to it.
62The call is any place in other functions which invokes the execution of the
63function in question. For two functions write_vals() and add(), you thus
64might have the following bit of code:
65
66-----
67/* First, function declarations. They usually appear at the beginning
68 of object code.
69*/
70void write_vals();
71int add(int x, int y);
72
73/* Next, the definition of the function write_vals(). We assume that
74 this function is going to be called from outside the object
75*/
76void write_vals() {
77 int x;
78
79 /*N Now we assign x the value of the output of add() through a call */
80 x = add(2, 2);
81 write(x+"\n");
82}
83
84/* Finally, the definition of add() */
85int add(int x, int y) {
86 return (x + y);
87}
88-----
89
90Remember, it does not matter which function definition appears first in the
91code. This is because functions are not executed consecutively. Instead,
92functions are executed as called. The only requirement is that the
93declaration of a function appear before its definition and before the
94definition of any function which makes a call to it.
95
964.3 Efuns
97Perhaps you have heard people refer to efuns. They are externally defined
98functions. Namely, they are defined by the mud driver. If you have
99played around at all with coding in LPC, you have probably found some
100expressions you were told to use like this_player(), write(), say(),
101this_object(), etc. look a lot like functions. That is because they are
102efuns. The value of efuns is that they are much faster than LPC functions,
103since they already exist in the binary form the computer understands.
104
105In the function write_vals() above, two functions calls were made. The first was to
106the functions add(), which you declared and defined. The second call, however,
107was to a function called write(), and efun. The driver has already declared
108and defined this function for you. You needs only to make calls to it.
109
110Efuns are created to hanldle common, every day function calls, to handle
111input/output to the internet sockets, and other matters difficult to be
112dealt with in LPC. They are written in C in the game driver and compiled
113along with the driver before the mud comes up, making them much faster
114in execution. But for your purposes, efun calls are just like calls
115made to your functions. Still, it is important to know two things of any
116efun: 1) what return type does it have, and 2) what parameters of what
117types does it take.
118
119Information on efuns such as input parameters and return types is often
120found in a directory called /doc/efun on your mud. I cannot
121detail efuns here, because efuns vary from driver to driver. However,
122you can often access this information using the commands "man" or "help"
123depending on your mudlib. For instance, the command "man write" would
124give you information on the write efun. But if all else fails,
125"more /doc/efun/write" should work.
126
127By looking it up, you will find write is declared as follows:
128
129-----
130void write(string);
131-----
132
133This tells you an appropriate call to write expects no return value and
134passes a single parameter of type string.
135
1364.4 Defining your own functions
137Although ordering your functions within the file does not matter, ordering
138the code which defines a function is most important. Once a function
139has been called, function code is executed in the order it appears
140in the function definition. In write_vals() above, the instruction:
141
142-----
143x = add(2, 2);
144-----
145
146Must come before the write() efun call if you want to see the appropriate
147value of x used in write().
148
149With respect to values returned by function, this is done through the "return"
150instruction followed by a value of the same data type as the function. In
151add() above, the instruction is "return (x+y);", where the value of (x+y)
152is the value returned to write_vals() and assigned to x. On a more
153general level, "return" halts the execution of a function and returns
154code execution to the function which called that function. In addition,
155it returns to the calling function the value of any expression that follows.
156To stop the execution of a function of type void out of order, use
157"return"; without any value following. Once again, remember, the data
158type of the value of any expression returned using "return" MUST be the
159same as the data type of the function itself.
160
1614.5 Chapter Summary
162The files which define LPC objects are made of of functions. Functions, in
163turn, are made up of three parts:
164 1) The declaration
165 2) The definition
166 3) The call
167Function declarations generally appear at the top of the file before any
168defintions, although the requirement is that the declaration must appear
169before the function definition and before the definition of any function
170which calls it.
171Function definitions may appear in the file in any order so long as they
172come after their declaration. In addition, you may not define one function
173inside another function.
174Function calls appear inside the definition of other functions where you
175want the code to begin execution of your function. They may also appear
176within the definition of the function itself, but this is not recommended
177for new coders, as it can easily lead to infinite loops.
178
179The function definition consists of the following in this order:
180 1) function return type
181 2) function name
182 3) opening ( followed by a parameter list and a closing )
183 4) an opening { instructing the driver that execution begins here
184 5) declarations of any variables to be used only in that function
185 6) instructions, expressions, and calls to other functions as needed
186 7) a closing } stating that the function code ends here and, if no
187 "return" instruction has been given at this point (type void functions
188 only), execution returns to the calling function as if a r"return"
189 instruction was given
190
191The trivial function would thus be:
192
193-----
194void do_nothing() {}
195-----
196
197since this function does not accept any input, perform any instructions, or
198return any output.
199
200Any function which is not of type void MUST return a value of a data type
201matching the function's data type.
202
203Each driver has a set of functions already defined for you called efuns
204These you need neither need to declare nor define since it has already
205been done for you. Furthermore, execution of these functions is faster
206than the execution of your functions since efuns are in the driver.
207In addition, each mudlib has special functions like efuns in that they
208are already defined and declared for you, but different in that they
209are defined in the mudlib and in LPC. They are called simul_efuns, or
210simulated efuns. You can find out all about each of these as they are
211listed in the /doc/efun directory on most muds. In addition many
212muds have a command called "man" or a "help" command which allows you
213simply to call up the info files on them.
214
215Note on style:
216Some drivers may not require you to declare your functions, and some
217may not require you to specify the return type of the function in its
218definition. Regardless of this fact, you should never omit this information
219for the following reasons:
220 1) It is easier for other people (and you at later dates) to read your
221 code and understand what is meant. This is particularly useful
222 for debugging, where a large portion of errors (outside of misplaced
223 parentheses and brackets) involve problems with data types (Ever
224 gotten "Bad arg 1 to foo() line 32"?).
225 2) It is simply considered good coding form.