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 information about the function named fname is 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 through the uman preferences.
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 block 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 local user's 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.
--> foo(%pi) // Display the full bloc of heading comments of foo(), in place of any

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()

at line    21 of function foo
Wrong number of input arguments

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
2.1 2016-10-30
  • The block of syntaxes is now aligned. New uman configuration variable "umanAlignSyntaxes".

  • Translation of this page in french.
2.0 2016-04-06 : First publication, bundled within the uman module.

<< uman .. @ uman Preferences >>