MUF Libraries

Libraries allow MUF 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 $include 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 MUF programs. Section 3.2.6, the MUF Library Reference, gives comprehensive documentation of routines available from the standard libraries. In addition, you can create your own libraries.

Using Library Functions:

To use library functions in your programs, include the library or libraries needed by placing an $include statement in your code, before any library functions are called, and outside of any functions. (Most programmers put all $include 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:

    $include $lib/reflist

At any point after this line, functions defined in lib-reflist can be used in your program.

To list the the libraries available on your MUCK, type @register lib. To view a library's documentation, type @view $lib/<library name>.

Creating Libraries:

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 public declaration, and set some properties that give the server the information it will need to coordinate between programs and give 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 lib-sort, a library of sorting functions. Take glance at the file now, and refer to it as we discuss its implementation.

Step 1: Create a program with useful, generic routines. Programs frequently need to sort data, but neither MUF nor the standard libraries include functions for doing this (actually, lib-edit does include a function for sorting strings... EDITsort). 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 in the stack. A more complete discussion of stack ranges is available in Section 3.2.6.) For example, if we had five strings on the stack that we wanted to sort alphabetically...

  "mink" "timber wolf" "otter" "woolly pterydactyl" "linsang"

... 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 sort function...

  "mink" "timber wolf" "otter" "woolly pterydactyl" "linsang" 5
  sort

Lib-sort would return the five items in alphabetical order, with the count integer removed:

  "linsang" "mink" "otter" "timber wolf" "woolly pterydactyl"

Lib-sort provides two public functions: sort, which returns the range sorted in ascending order, and sort-d, which returns the range in descending order. All items in the range must be of the same data type (string, integer, or dbref). Lib-sort looks at the data type of the top item in the range to determine how to sort the range.

(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 MUF programming exercise.)

Step 2: 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: sort and sort-d. 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, sort and sort-d need to be declared public, and the others should not be. We do this by putting the lines...

  public sort
  public sort-d

...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.

Step 3: 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.

Step 4: Set the program's _docs property to allow users to @view the documentation: @set lib-sort=_docs:@list $lib/sort=1-49 .

Step 5: Set the program Link_OK, so that other programs can access its public functions and users can view its documentation with @view: @set lib-sort=L.

Step 6: Configure the interface for each public function by setting a _defs/ property. These properties give the server the information it needs to match statements in local programs to public functions in the library.

    @set lib-sort=_defs/sort:"$lib/sort" match "sort" call
    @set lib-sort=_defs/sort-d:"$lib/sort-d" match "sort-d" call

That's it!