## `prog::check` -- Checking MuPAD objects

#### Introduction

`prog::check` checks MuPAD objects and draws attention to errors and possible problems in programming. `prog::check` is very helpful for finding errors in user-defined domains and procedures.

#### Call(s)

`prog::check(object <, infolevel <, options>>)`

#### Parameters

`object` | - | procedure, function environment or domain to check, the identifier `All`, or a list of objects
`infolevel` | - | positive integer that determines the completeness of messages
`options` | - | set of options, a single option, or `All`

#### Options

`Global` | - | report unknown global identifiers
`Local` | - | report unused local variables
`Localf` | - | report unused local variables and unused formal parameters
`Assign` | - | report assignments to formal parameters of procedures
`Level` | - | report applications of `level` to local variables
`Domain` | - | report undefined entries of domains (uses the slot `"undefinedEntries"`)
`Environment` | - | report assignments to environment variables
`Protect` | - | report assignments to (global) protected identifiers
`Special` | - | report special statements
`Escape` | - | report possible pointers to procedure environments

#### Returns

`prog::check` returns the void object `null()`. Output messages are printed on the screen.

#### Related Functions

`debug`, `prog::init`, `prog::isGlobal`, `prog::trace`, `prog::getname`

#### Details

- The call `prog::check(`object`)` checks the MuPAD object `object`. `object` may be a procedure, a function environment, or a domain. One may also give a list of such objects.
- If `All` is given as first parameter, all defined procedures, function environments and domains are checked (see `anames`).
- `infolevel` determines the amount of information given while checking. The following values are useful:
  1
    number of warnings per checked object, if at least one warning occurs (default)
  2
    as 1, but a short message is printed even if no warning was produced
  3
    summary of warnings per checked object
  5
    displays each checked object, followed by individual warnings, followed by a summary and the number of warnings, if any.
  10 ... 15
    additional outputs (for debugging)
- `options` can be a set containing one or more of the following options, a single option or `All` (see options).
- With option `All`, all are checked. Without options, the set `{Domain, Global, Level, Local, Protect}` is used.

- The arguments of `hold` expressions are not checked.

#### Option: Global

- Unknown (global) identifiers

#### Option: Local

- Information about unused local variables are printed. These are variables that were declared by `local`, but never used in the procedure.

#### Option: Localf

- The same as Local, but the same check is additionally performed for formal parameters of a procedure. Those are the argument names as given in the definition of the procedure.

#### Option: Assign

- Information about assignments to formal parameters are printed. Because a formal parameter will be overwritten in MuPAD 2.0, unlike in previous versions, those assignments could indicate a programming error (however, not imperative).

#### Option: Level

- The application of `level` to local variables is reported. Starting with MuPAD 2.0, local variables are simply replaced by their values on evaluation and calling `level` on them does not have any effect.

#### Option: Domain

- Information about undefined required entries of domains are printed.

#### Option: Environment

- Information about assignments to environment variables of MuPAD are printed. These assignments could change the global behavior of MuPADif the change is not undone (preferably using `save`, to catch error conditions).

#### Option: Protect

- Information about assignments to protected variables of MuPAD are printed.

#### Option: Special

- Information about some special cases are printed. Currently, the only implemented special case is assignments to `HISTORY`.

#### Option: Escape

- `prog::check` prints warnings about procedures which may require the option `escape`.

#### Example 1

The following function contains a number of mistakes, some of which were actually legal in previous versions of MuPAD.

Lines `1` and `2` contains declarations of local variables. In line `4` an undeclared (global) variable `g` is used. Line `7` applies `level` to a local variable (the call simply returns the value of `X` in MuPAD 2.0). Line `10` contains an assignment to a formal parameter. This parameter will be overwritten and its old value lost:

    >> f:= proc(X, Y)                //  1  Local
             local a, b;             //  2  Local
           begin                     //  3
             g:= proc(X)             //  4  Global
                   option hold;      //  5
                 begin               //  6
                   a:= level(X, 2);  //  7  Level
                   a:= a + X         //  8
                 end_proc;           //  9
             Y:= g(Y);               // 10  Assign, Global
           end_proc:
       prog::check(f, 3)

          'level' applied to variables: {X} in [f, proc in 'f']
          Global idents: {g} in [f]
          Unused local  var's:  {b} in [f]
          Warnings: 3 [f]

Only search for global variables, but give more messages:

    >> prog::check(f, 5, Global)

          checking f (DOM_PROC)
          Warning: Global variable 'g' in f []
          Warning: Global variable 'g' in f []
          Global idents: {g} in [f]
          Warnings: 1 [f]

Now check everything:

    >> prog::check(f, 5, All)

          checking f (DOM_PROC)
          Warning: Global variable 'g' in f []
          Warning: critical usage of 'level' on local variable 'X' in proc in 'f' [f]
          'level' applied to variables: {X} in [f, proc in 'f']
          Procedure environment of [f] used by
                   [f, proc in 'f']
          Warning: assignment to FORMAL parameter 'Y' in f []
          Warning: Global variable 'g' in f []
          Global idents: {g} in [f]
          Unused local  var's:  {b} in [f]
          Unused formal par's:  {X} in [f]
          Assignments to formal parameters: {Y} in [f]
          Warnings: 5 [f]

#### Further Documentation

From MuPAD 1.4 to MuPAD 2.0

#### Changes

- new function
- `prog::check` includes the functionality of the obsolete functions `misc::checkLib` and `misc::checkFunction`.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000