Previous Page Next Page Contents

package -- load a package of new library functions

Introduction

package(dirname) loads a new library package.

Call(s)

package(dirname <, Quiet> <, Forced>)

Parameters

dirname - a valid directory path: a character string

Options

Quiet - suppresses screen output while loading the library
Forced - enforces reloading of libraries that are already loaded

Returns

the value of the last statement in the initialization file init.mu of the package.

Side Effects

The path dirname/lib is prepended to the search path LIBPATH. The path dirname/modules/OSName is prepended to the search path READPATH (OSName is the name of the operating system; cf. sysname). This way, library functions are first searched for in the package. Modules contained in the package are found automatically. In case of a naming conflict, a package function overrides a function of the system's main library.

Related Functions

export, LIBPATH, loadmod, loadproc, newDomain, read, READPATH

Details

Option: Quiet

Option: Forced

Example 1

In the following, we demonstrate how a package should be organized that generates a new library domain containing user-defined functions. In example 2, we load the same functions, but include them in one of MuPAD's standard libraries rather than create a new library domain.

Suppose we have implemented some functions operating on integers such as a factorial function and a new function for computing powers of integers. It is a good idea to combine these functions into one package. The new library domain is to be called numfuncs (for elementary number theoretic functions). It is organized as a package stored in the folder demoPack1. This folder has the following structure:

      demoPack1/lib/init.mu
      demoPack1/lib/LIBFILES/numfuncs.mu
      demoPack1/lib/NUMFUNCS/factorial.mu
      demoPack1/lib/NUMFUNCS/russian.mu

The initialization file init.mu may be implemented as follows:

      // ----- file demoPack1/lib/init.mu ----- 
      // loads the library 'numfuncs'
      alias(path = pathname("LIBFILES")):
      numfuncs := loadproc(numfuncs, path, "numfuncs"):
      stdlib::LIBRARIES := stdlib::LIBRARIES union {"numfuncs"}:
      unalias(path):
      // return value of package:
      "library 'numfuncs' successfully loaded":
      // -------- end of file init.mu ---------

The function pathname is used to create the pathname in a form that is appropriate for the currently used operating system. The loadproc call refers to the actual definition of the new library domain in the file LIBFILES/numfuncs.mu:

      // --- file demoPack1/lib/LIBFILES/numfuncs.mu ---
      // numfuncs -- the library for elementary number theory
      numfuncs := newDomain("numfuncs"):
      numfuncs::Name := "numfuncs":
      numfuncs::info := "Library 'numfuncs': the library of ".
                        "functions for elementary number theory":
      numfuncs::interface := {hold(factorial), hold(russianPower)}:
      // define the functions implemented in ../NUMFUNCS/factorial.mu etc:
      alias(path = pathname("NUMFUNCS")):
      numfuncs::factorial := 
             loadproc(numfuncs::factorial, path, "factorial"):
      numfuncs::odd := 
             loadproc(numfuncs::odd, path, "russian"):
      numfuncs::russianPower := 
             loadproc(numfuncs::russianPower, path, "russian"):
      unalias(path):
      null():
      // --------- end of file numfuncs.mu ---------

Here, the new library domain is created via newDomain. Any library domain should have the entries Name and info. One may also define an interface entry, which is to contain all the functions a user should be aware of.

This file also contains the definitions of the functions factorial, odd, and russianPower which are implemented in the subfolder demoPack1/lib/NUMFUNCS. (See example 2 for details of the implementation; just replace numlib by numfuncs.)

The function numfuncs::factorial is implemented in a separate file. The functions numfuncs::odd and numfuncs::russianPower are both installed in the file russian.mu.

Note that numfuncs::odd is not added to the interface slot, because it is a utility function that should not be seen and used by the user.

Finally, we demonstrate the loading of the library package. Suppose that we have several packages, installed in the folder myMuPADFolder:

      /home/myLoginName/myMuPADFolder/demoPack1
      /home/myLoginName/myMuPADFolder/demoPack2
      ...

The library numfuncs installed in demoPack1 is loaded by a call to the package function:

>> package("/home/myLoginName/myMuPADFolder/demoPack1")
      Library 'numfuncs': the library of functions for elementary \
      number theory
      
      -- Interface:
      numfuncs::factorial, numfuncs::russianPower  
      
                "library 'numfuncs' successfully loaded"

In the initialization file init.mu, the new library was added to stdlib::LIBRARIES. For the reason, loading causes the above information about the library to be printed. By default, a library package can be loaded only once:

>> package("/home/myLoginName/myMuPADFolder/demoPack1")
      Warning: Package already defined. For redefinition use option \
      Forced [package]

Following the warning, we overwrite the existing library numfuncs by another call to package using the option Forced:

>> package("/home/myLoginName/myMuPADFolder/demoPack1",
           Forced)
      Warning: Package redefined [package]
      
                 "library 'numfuncs' successfully loaded"

After loading, the new library numfuncs is fully integrated into the system. Its functions can be called like any other function of MuPAD's main library:

>> numfuncs::factorial(41)
            33452526613163807108170062053440751665152000000000
>> numfuncs::russianPower(123, 12)
                        11991163848716906297072721

Example 2

We demonstrate how a package should be organized that adds new functions to an existing library domain.

We consider the same functions as in example 1. However, instead of creating a new library domain, we wish to add these functions to the existing library domain numlib of MuPAD's main library. In particular, the package is to install the new functions numlib::factorial and numlib::russianPower. Before loading such functions, we should make sure that they do not overwrite existing functions of the standard numlib installation. As a simple test to check that the standard installation does not provide a function numlib::factorial, one may simply try to call this function:

>> numlib::factorial      
                                   FAIL

Indeed, this function does not exist yet and shall now be provided by an extension installed in a folder demoPack2:

      demoPack2/lib/init.mu
      demoPack2/lib/NUMLIB/factorial.mu
      demoPack2/lib/NUMLIB/russian.mu

In this case, no new library domain is to be created. Hence, in contrast to example 1, no file demoPack2/lib/LIBFILES/numlib.mu needs to be installed (which would be in conflict with the corresponding file defining the numlib library domain of the standard installation). Instead, the new functions may be declared directly in the initialization file init.mu as follows:

      // ------ file demoPack2/lib/init.mu -------
      // loads additional functions for the existing library 'numlib'
      numlib::interface := numlib::interface
            union {hold(factorial), hold(russianPower)}:
      // define the functions implemented in ../NUMLIB/factorial.mu etc:
      alias(path = pathname ("NUMLIB")):
      numlib::factorial :=
            loadproc(numlib::factorial, path, "factorial"):
      numlib::odd :=
            loadproc(numlib::odd, path, "russian"):
      numlib::russianPower := 
            loadproc(numlib::russianPower, path, "russian"):
      unalias(path):
      // return value of package:
      "new numlib functions successfully loaded":
      // ---------- end of file init.mu ----------

Similar to example 1, we added the main functions to the existing interface slot of numlib.

We now have a look into the files factorial.mu and russian.mu containing the source code of the functions:

      // ---- file demoPack2/lib/NUMLIB/factorial.mu ----
      numlib::factorial :=
        proc(n : Type::NonNegInt) : Type::PosInt
          // factorial(n) computes n!
        begin
          if n = 0 then 1
          else n*numlib::factorial(n - 1)
          end_if
        end_proc:
      // -------- end of file factorial.mu ---------

The routine numlib::odd is a utility function for numlib::russianPower. Bothe functions are coded in one file:

      // ---- file demoPack2/lib/NUMLIB/russian.mu ----
      numlib::odd := m -> not(iszero(m mod 2)):
      
      numlib::russianPower :=
        proc(m : DOM_INT, n : Type::NonNegInt) : DOM_INT
          // computes the n-th power of m using the
          // russian peasant method of multiplication
          local d;
        begin
          d := 1;
          while n>0 do
            if numlib::odd(n) then
              d := d*m;
              n := n - 1;
            else
              m := m*m;
              n := n div 2;
            end_if
          end_while;
          d
        end_proc:
      // ----------- end of file russian.mu ------------

Finally, we demonstrate the loading of the functions. Suppose that we have several packages, installed in the folder myMuPADFolder:

      /home/myLoginName/myMuPADFolder/demoPack1
      /home/myLoginName/myMuPADFolder/demoPack2
      ...

The functions installed in demoPack2 are loaded by a call to the package function:

>> package("/home/myLoginName/myMuPADFolder/demoPack2")
                "new numlib functions successfully loaded"

The new functions added to the interface slot of numlib are listed by an info call:

>> info(numlib)
      Library 'numlib': the package for elementary number theory
      
      -- Interface:
      numlib::Lambda,           numlib::Omega, 
      ...
      numlib::factorial,        numlib::fibonacci, 
      ...
      numlib::proveprime,       numlib::russianPower, 
      ...

After loading, the new functions are fully integrated into the library and can be called like any other function of MuPAD's library:

>> numlib::factorial(41)
            33452526613163807108170062053440751665152000000000
>> numlib::russianPower(123, 12)
                        11991163848716906297072721

Changes




Do you have questions or comments?


Copyright © SciFace Software GmbH & Co. KG 2000