## `userinfo` -- print progress information

#### Introduction

`userinfo``(n, message)` prints a message if an information level larger or equal to `n` is set via `setuserinfo`.

`userinfo``(n1..n2, message)` prints a message if the information level set by `setuserinfo` is between `n1` and `n2`.

#### Call(s)

`userinfo( <Text,> n, message1, message2...)`
`userinfo( <Text,> n1..n2, message1, message2...)`

#### Parameters

`n, n1, n2` | - | the information levels: nonnegative integers
`message1, message2...` | - | arbitrary MuPAD objects. Typically, character strings.

#### Options

`Text` | - | do not separate the arguments by commas in the output

#### Returns

the void object of type `DOM_NULL`.

#### Side Effects

The formatting of the output of `userinfo` is sensitive to the environment variable `TEXTWIDTH`.

#### Related Functions

`print`, `setuserinfo`, `warning`

#### Details

- `userinfo` must not be used on the interactive level. It should be built into the body of a procedure or of a domain method to print status information such as the chosen algorithm, intermediate results etc. If a `userinfo` command is built into a procedure by the name `f`, say, then it is activated by setting an appropriate information level via `setuserinfo``(f, n)`. The information is printed during subsequent calls to `f`.

- The print output consists of the evaluation of the message arguments, possibly followed by the name of the procedure (see the function `setuserinfo`). Strings are printed without quotes. The pretty printer is not used. Unless the option Text is given, the message arguments are separated by commas in the output.

- The information level of a single procedure, of all procedures of a domain, or, of all procedures in general can be specified using `setuserinfo`. All three levels may apply to a procedure simultaneously.

- Most of the functions in the MuPAD library provide status information via `userinfo`. See example 3.

- `userinfo` is a function of the system kernel.

#### Example 1

The function `expr2text` is useful for incorporating MuPAD objects in a text message:

    >> f := proc(x)
            begin
              userinfo(2, "the argument is " . expr2text(x));
              x^2
            end_proc:

    >> setuserinfo(f, 2, Name): f(12)

          Info: the argument is 12 [f]

                                        144

    >> setuserinfo(f, 0): delete f:

#### Example 2

A call of the form `userinfo``(n, message)` causes `message` to be displayed if the information level is at least as high as `n`. If you want `message` to be displayed only if the information level equals `n`, use a range that consists of one point only:

    >> f := proc()
            begin
              userinfo(2..2, "Infolevel = 2");
              userinfo(2, "Infolevel >= 2");
            end_proc:

    >> setuserinfo(f, 2): f():

          Info: Infolevel = 2
          Info: Infolevel >= 2

    >> setuserinfo(f, 3): f():

          Info: Infolevel >= 2

    >> setuserinfo(f, 0): delete f:

#### Example 3

By setting the information level of `faclib` to 5, we get information on the algorithms used for factorization:

    >> setuserinfo(faclib, 5): factor(x^2 + 2*x + 1)

          Info: faclib::monomial called with poly(x^2 + 2*x + 1, [x])
          Info: Squarefree factorization (Yun's algorithm) called

                                            2
                                     (x + 1)

    >> setuserinfo(faclib, 0):

#### Background

- `userinfo` does not evaluate the messages unless they are printed.
- The global table of information levels for all procedures can be obtained by the call `setuserinfo()`.

#### Changes

- `userinfo` now prints the procedure name in a different way.
- The option Pretty was removed; `userinfo` does not use the pretty printer.
- The option Text was added.
- `userinfo` now is a kernel function.

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