uman >> uman > disp_usage

disp_usage

affiche les syntaxes autorisées pour une fonction donnée

Syntaxe

disp_usage()
disp_usage(fname)

Arguments

fname
texte = nom d'une fonction écrite en langage Scilab ou d'une primitive Scilab compilée.

Description

disp_usage() affiche dans la console les différentes syntaxes utilisables pour la fonction depuis laquelle disp_usage() est appelée. Ces informations peuvent être utilement rappelées à l'utilisateur par exemple lorsqu'une erreur de syntaxe relative à un argument d'entrée ou de sortie est détectée. À cette fin, disp_usage() sera appelée juste avant error(..).

Lorsqu'un nom de fonction fname est explicitement fourni, les syntaxes utilisables pour cette fonction fname sont affichées.

Exemple d'affichage :

--> disp_usage unwrap

Scilab > Fonctions Elémentaires > unwrap
........................................
USAGES
                    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)

Le mode d'alignement des syntaxes dans le bloc peut être modifié en utilisant l'option "Alignement des syntaxes" disponible dans les préférences de uman().
disp_usage('fname') est équivalent à uman fname u. Cette syntaxe explicite doit être préférée.
disp_usage() peut être appelée sans argument d'entrée uniquement à l'intérieur d'un bloc function / endfunction. fname est alors implicitement le nom de la fonction hôte écrite en langage Scilab.
Si la fonction nommée fname n'a pas de page d'aide standard mais est documentée par un bloc de commentaires en en-tête de définition, disp_usage(..) affiche les commentaires d'aide en entier, pas uniquement la liste des syntaxes.
disp_usage(..) utilise uman(..) et requiert le module externe uman dans lequel elle est normalement distribuée.

Exemples

Exemple n° 1 : la fonction unwrap(..) est définie et dispose d'une page d'aide. Nous la redéfinissons artificiellement ci-dessous afin d'y introduire un appel à disp_usage() en montrant l'usage :

fp = funcprot(); funcprot(0);
function unwrap(x)
    if typeof(x)~="constant"
        // warning(...) peut être éventuellement appelée
        disp_usage()  // <<<=======
        // error(...) peut aussi être utilisée, si la condition est bloquante
    end
endfunction
funcprot(fp);
// Appelons "unwrap" avec un argument non admis :
unwrap("abc")
clear unwrap  // ( restaure la vraie version de unwrap() )

Exemple n° 2 : usage dans une fonction documentée uniquement par des commentaires.

function r=foo(a, b, c)
    // USAGE:
    // foo()          // démo
    // r = foo(a,b)   // produit a^2 - b
    // r = foo(a,b,c) // produit a^2 - b + sin(c)
    //
    // DESCRIPTION
    // foo() est une fonction test visant à illustrer 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("Nombre d''arguments incorrect")
    end
endfunction
foo(%pi) // Affiche les commentaires complets résidant en tête de foo(),
         //  en guise d'aide, à défaut de page d'aide standard.
         // Les syntaxes de foo() admises doivent si possible être indiquées
         //  en premières lignes du bloc de commentaires.
--> foo(%pi) // Affiche les commentaires complets résidant en tête de foo(),

function [r] = foo(a,b,c)
 USAGE:
 foo()          // démo
 r = foo(a,b)   // produit a^2 - b
 r = foo(a,b,c) // produit a^2 - b + sin(c)

 DESCRIPTION
 foo() est une fonction test visant à illustrer disp_usage()

à la ligne    20 de la fonction foo
Nombre d'arguments incorrect

Exemple n° 3 : appel externe de disp_usage() pour une fonction Scilab ou compilée donnée.

// Appel fonctionnel :
disp_usage("members")

// Appel orienté console :
disp_usage meshgrid

// Appel équivalent à uman(..) :
uman meshgrid u

Voir aussi

Historique

VersionDescription
2.1 2016-10-30
  • Le bloc des syntaxes est désormais aligné. Nouvelle variable de configuration "umanAlignSyntaxes" de uman.

  • Traduction de cette page en français.
2.0 2016-04-06 : Première publication de disp_usage(), au sein du module uman.

<< uman .. @ uman Preferences >>