<< uman uman uman >>
uman >> uman > disp_usage

disp_usage

Displays allowed syntaxes to call a given function

Syntax

disp_usage()
disp_usage(fname)

Arguments

fname
text = name of a function (macro in Scilab language, or Scilab built-in function).

Description

disp_usage() displays in the console the main usage informations about the Scilab function in which disp_usage() is called. This may be used mainly when an error -- for instance about input or output arguments -- is detected. disp_usage() may then be called before calling error(..), as a usage reminder.

When fname is provided, the usage informations about the function named fname are displayed.

Example of display: 

--> disp_usage unwrap

Scilab > Elementary Functions > unwrap
......................................
SYNTAX
                    unwrap() // runs some examples
 [U, breakPoints] = unwrap(Y)
 [U, breakPoints] = unwrap(Y, z_jump)
  [U, cuspPoints] = unwrap(Y, "unfold")
                U = unwrap(Z)
                U = unwrap(Z, z_jump)
                U = unwrap(Z, z_jump, dir)

The alignment mode of syntaxes inside the block may be changed using the uman "umanAlignSyntaxes" configuration variable.
disp_usage('fname') is equivalent to uman fname u. The uman.. call should be prefered.
disp_usage() can be called without input parameters only inside a function / endfunction. Then fname is implicitly the name of the embedding function.
If the function named fname has no standard help page but is only documented through its heading comments, disp_usage(..) displays the full bloc of heading comments, so not necessarily (only) a USAGES section.
disp_usage(..) calls uman(..) and requires the uman module.

Examples

// EXAMPLE #1:
// "unwrap(..)" is an existing function, with its help page.
// We are artificially redefining it herebelow in order to introduce
//    disp_usage() in it to show how it works:
fp = funcprot(); funcprot(0);
function unwrap(x)
    if typeof(x)~="constant"
        // warning(...) may be helpfully called
        disp_usage()  // <<<=======
        // error(...) may additionally be called
    end
endfunction
funcprot(fp);
// Then let's call it
unwrap("abc")
clear unwrap // clearing it automatically recovers the default true version

// EXAMPLE #2 : Usage in a function documented only through heading comments
function r=foo(a, b, c)
    // USAGE:
    // foo()          // demo
    // r = foo(a,b)   // returns a^2 - b
    // r = foo(a,b,c) // returns a^2 - b + sin(c)
    //
    // DESCRIPTION
    // foo() is a test function aiming to illustrate disp_usage()
    //

    select argn(2)
        case 0
            disp("Here should be a demo")
            r = []
        case 2
            r = a.^2 - b
        case 3
            r = a.^2 - b + sin(c)
        else
            disp_usage()
            error("Wrong number of input arguments")
    end
endfunction
foo(%pi) // Display the full bloc of heading comments of foo(), in place of any
         // standard help page.
         // Possible calling syntaxes to foo() must then be indicated in the
         // first lines of comments in this bloc.

// EXAMPLE #3:
// External call of disp_usage() for a specific macro or primitive:
// Functional type of external call:
disp_usage("members")
// Console-oriented type of external call:
disp_usage meshgrid
// uman equivalence:
uman meshgrid u

See Also

History

VersionDescription
uman 2.1
  • The block of syntaxes is now aligned. New uman configuration variable "umanAlignSyntaxes".
  • Translation of this page in french
uman 2.0 First publication, bundled within the uman module.

Report an issue
<< uman uman uman >>