3.7.1 Procedure definition

Syntax:

[static] proc proc_name [parameter_list]
["help_text"]
{
     procedure_body
}
[example
{
     sequence_of_commands;
}]

Purpose:

defines a new function, the proc proc_name, with the additional information help_text, which is copied to the screen by help proc_name; and the example section which is executed by example proc_name;.
The help_text, the parameter_list, and the example section are optional. The default for a parameter_list is (list #), see Parameter list. The help and example sections are ignored if the procedure is defined interactively, i.e., if it was not loaded from a file by a LIB command (LIB).
Specifying static in front of the proc-definition (in a library file) makes this procedure local to the library, i.e., accessible only for the other procedures in the same library, but not for the users. So there is no reason anymore to define a procedure within another one (it just makes debugging harder).

Example of an interactive procedure definition

  proc milnor_number (poly p)
  {
    ideal i= std(jacob(p));
    int m_nr=vdim(i);
    if (m_nr<0)
    {
      "// not an isolated singularity";
    }
    return(m_nr);         // the value of m_nr is returned
  }
  ring r1=0,(x,y,z),ds;
  poly p=x^2+y^2+z^5;
  milnor_number(p);
→ 4

Example of a procedure definition in a library

First, the library definition:

// Example of a user accessible procedure
proc tab (int n)
"USAGE:    tab(n);  (n integer)
RETURNS:  string of n space tabs
EXAMPLE:  example tab; shows an example"
{ return(internal_tab(n)); }
example
{
  "EXAMPLE:"; echo=2;
  for(int n=0; n<=4; n=n+1)
  { tab(4-n)+"*"+tab(n)+"+"+tab(n)+"*"; }
}

// Example of a static procedure
static proc internal_tab (int n)
{ return(" "[1,n]); }

Now, we load the library and execute the procedures defined there:

  LIB "sample.lib";        // load the library sample.lib
  example tab;             // show an example
→ // proc tab from lib sample.lib
→ EXAMPLE:
→   for(int n=0; n<=4; n=n+1)
→   { tab(4-n)+"*"+tab(n)+"+"+tab(n)+"*"; }
→     *+*
→    * + *
→   *  +  *
→  *   +   *
→ *    +    *
→ 
  "*"+tab(3)+"*";          // use the procedure tab
→ *   *
  // the static procedure internal_tab is not accessible
  "*"+internal_tab(3)+"*";
→    ? 'sample.lib::internal_tab()' is a local procedure and cannot be acce\
   ssed by an user.
→    ? error occurred in line 5: `  "*"+internal_tab(3)+"*";`
  // show the help section for tab
  help tab;
→ // ** Could not get IdxFile. 
→ // ** Either set environment variable SINGULAR_IDX_FILE to IdxFile,
→ // ** or make sure that IdxFile is at /home/hannes/singular/2-0/doc/singu\
   lar.idx
→ // proc tab from lib sample.lib
→ proc tab (int n)
→ USAGE:    tab(n);  (n integer)
→ RETURNS:  string of n space tabs
→ EXAMPLE:  example tab; shows an example

Guidelines for the help text of a procedure

There are no enforced rules on the format of the help section of a procedure.

Nevertheless, we recommend that the help text of a procedure should contain information about the usage, purpose, return values and generated objects. Particular assumptions or limitations should be listed. It should also be mentioned if global objects are generated or manipulated.

The help text of procedures contained in libraries of the SINGULAR distribution should furthermore comply with certain rules as explained in The help string of procedures.