-
Notifications
You must be signed in to change notification settings - Fork 0
/
muflibs.html
176 lines (146 loc) · 6.63 KB
/
muflibs.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
<html>
<head>
<title>The MUCK Manual: MUF Libraries</title>
</head>
<body bgcolor="#FFFFFF">
<center>
<a href="mucklev.html">prev</a>|
<a href="toc.html">toc</a>|
<a href="mufmacs.html">next</a>
</center>
<table>
<tr>
<td width="20%"> </tc>
<td>
<!-- BODY CONTENT HERE -->
<p><b>MUF Libraries</b></p>
<p>Libraries allow <code>MUF</code> programs to share code: frequently
used, generic routines can be written and compiled once, in a library;
other programs can use these routines by using an <code>$include</code>
statement to include the library. Once a library has been included, any
routines defined in the library can be used in the local program. A
number of standard libraries are available, and will be needed to
compile a number of the standard <code>MUF</code> programs. <a
href="muflibref.html">Section 3.2.6</a>, the <code>MUF</code> Library
Reference, gives comprehensive documentation of routines available from
the standard libraries. In addition, you can create your own
libraries.</p>
<p><em>Using Library Functions</em>:</p>
<p>To use library functions in your programs, include the library or
libraries needed by placing an <code>$include</code> statement in your
code, before any library functions are called, and outside of any
functions. (Most programmers put all <code>$include</code> statements at
the top of their programs). Libraries are specified by their registered
names. For example, to use the reflist-handling functions from
lib-reflist, you would put the following line of code in your
program:</p>
<p><code>
$include $lib/reflist
</code></p>
<p>At any point after this line, functions defined in lib-reflist can be
used in your program.</p>
<p>To list the the libraries available on your <code>MUCK,</code> type
<code>@register lib</code>. To view a library's documentation, type
<code>@view $lib/<library name></code>.</p>
<p><em>Creating Libraries</em>:</p>
<p>Creating libraries is relatively straightforward. You simply write
code that could be useful to include in multiple programs, make
individual functions available to other programs with the
<code>public</code> declaration, and set some properties that give the
server the information it will need to coordinate between programs and
programmmers the information they will need in order to make good use of
your library. The remainder of this page illustrates these by example:
we'll create, configure, and use <a href="lib-sort.html">lib-sort</a>, a
library of sorting functions. Take glance at the file now, and refer to
it as we discuss its implementation.</p>
<p><em>Step 1:</em> Create a program with useful, generic routines. Programs
frequently need to sort data, but neither <code>MUF</code> nor the standard
libraries include functions for doing this. Lib-sort addresses this need. It
uses a simple bubble sort to sort a stack range of items. (A `stack range' is
a group of items on the stack and an integer indicating how many items are to
be considered part of the range. A more complete discussion of stack ranges is
available in <a href="muflibref.html#stackrange">Section 3.2.6</a>.) For
example, if we had five strings on the stack that we wanted to sort
alphabetically...</p>
<p><code>
<nobr>
"mink" "timber wolf" "otter" "woolly pterydactyl" "linsang"
</nobr>
</code></p>
<p>... we could do so by putting an integer that gives the `count' of
the range on top of the stack, and then calling lib-sort's
<code>sort</code> function...
<p><code>
<nobr>
"mink" "timber wolf" "otter" "woolly pterydactyl" "linsang" 5<br>
</nobr>
sort
</code></p>
<p>Lib-sort would return the five items in alphabetical order, with the
count integer removed:
<p><code>
<nobr>
"linsang" "mink" "otter" "timber wolf" "woolly pterydactyl"
</nobr>
</code></p>
<p>Lib-sort provides two public functions: <code>sort</code>, which
returns the range sorted in ascending order, and <code>sort-d</code>,
which returns the range in descending order. All items in the range must
be of the same data type (<code>string</code>, <code>integer</code>, or
<code>dbref</code>). Lib-sort looks at the data type of the top item in
the range to determine how to sort the range.</p>
<p>(A bubble sort is not the most efficient algorithm: it is relatively
slow when sorting large sets (though it is probably the most efficient
algorithm for very small sets), and it does not finish any faster if the
data is already sorted or mostly sorted. Other algorithms, such as a
qsort, would be better in many situations. Implementing a sorting
library with more sophisticated algorithms would be a good advanced
<code>MUF</code> programming exercise.)</p>
<p><em>Step 2</em>: Declare the appropriate public functions. Lib-sort
includes a total of eight functions, but only two of them are meant to
be called by other programs: <code>sort</code> and <code>sort-d</code>.
These two functions look at the stack range and call one of the
remaining six functions, which sort, ascending or descending, according
to datatype. So, <code>sort</code> and <code>sort-d</code> need to be
declared public, and the others should not be. We do this by putting the
lines...
<p><code>
public sort<br>
public sort-d
</code></p>
<p>...in the program, after the functions are defined, outside of any
function definitions. Here, we put them after each function. Another
common convention is to put all the public declarations at the end of
the program.</p>
<p><em>Step 3</em>: Document the program. Lib-sort uses the most common
documentation method, a header comment. Lines 1 to 49 explain how to
install and use the program.
<p><em>Step 4</em>: Set the program's <code>_docs</code> property to
allow users to <code>@view</code> the documentation: <code>@set
lib-sort=_docs:@list $lib/sort=1-49</code> .</p>
<p><em>Step 5</em>: Set the program <code>Link_OK</code>, so that other
programs can access its public functions and users can view its
documentation with <code>@view</code>: <code>@set lib-sort=L</code>.</p>
<p><em>Step 6</em>: Configure the interface for each public function by
setting a <code>_defs/</code> property. These properties give the server
the information it needs to match statements in local programs to public
functions in the library.</p>
<p><code>
<nobr>
@set lib-sort=_defs/sort:"$lib/sort" match "sort" call<br>
</nobr><nobr>
@set lib-sort=_defs/sort-d:"$lib/sort-d" match "sort-d" call
</nobr>
</code></p>
<p>That's it!</p>
<center>
<a href="mucklev.html">prev</a>|
<a href="toc.html">toc</a>|
<a href="#top">top</a>|
<a href="mufmacs.html">next</a>
</center>
</td>
<td width="20%"> </tc>
</table>
</body>
</html>