DECLARE subroutineName {argumentVector} [#["optional arg name list"]] {@"category name"} [?"Description String"]

Normally in Statistics101 a subroutine must be defined in the program text before it is invoked. Occasionally, it is desirable to reverse that order. The DECLARE command allows you to declare the "signature" of a subroutine. A signature is the name of the subroutine followed by all its dummy argument names. Once the signature has been declared, the subroutine may be invoked in the text by a program or subroutine as long as the subroutine will eventually defined by a NEWCMD somewhere in the text.

The reason for the rule that a subroutine must be defined before it is invoked is that Statistics101 makes only one pass over the program when it is compiling it. Therefore, it needs to have passed over the subroutine definition before it arrives at a subroutine invocation. The DECLARE command provides sufficient information to Statistics101 allowing it to construct an invocation without having seen the actual commands inside the subroutine. Statistics101 fills in the commands later when it finds the NEWCMD command that defines the subroutine.

The DECLARE command must follow these rules:

  • The subroutine name and the argument vector list must be identical in name, number, and order to the subroutine name and argument vector list in the subsequent NEWCMD command.

  • If the matching NEWCMD has optional arguments, indicated by "#", then the DECLARE command also must also indicate the existence of optional arguments with the "#".

  • The category name list, introduced by "@", and the description string, introduced by "?", are optional and need not match those of the NEWCMD command, but if the NEWCMD also has them, those on the NEWCMD will override those on the DECLARE command.

  • Multiple DECLARE commands, each for a different subroutine, are allowed.

  • Duplicate DECLARE commands (for the same subroutine) are allowed but only the first has any effect. Any duplicates are ignored.

See also: NEWCMD.

Here's a meaningless example to demonstrate the use of the DECLARE command:

DECLARE MY_DECLARED_SUBROUTINE arg1 arg2 #"optionalArg" 

'Here's a subroutine that invokes the as-yet
'undefined, but forward-declared subroutine:
NEWCMD TEST argx
   MY_DECLARED_SUBROUTINE 4 5 argx
   MY_DECLARED_SUBROUTINE 6 7 argx
END

'Here's the main program that invokes the
'forward-declared subroutine, then invokes
'another subroutine that also invokes the
'as-yet undefined subroutine:
MY_DECLARED_SUBROUTINE 10 11 100
TEST 200

'Finally, we find the actual definition
'of the subroutine:
NEWCMD MY_DECLARED_SUBROUTINE arg1 arg2 #"optionalArg" 
   GETARG 1 optionalArg
   PRINT "MY_DECLARED_SUBROUTINE running..." arg1 arg2 optionalArg
END

Here is the output from the above program:

MY_DECLARED_SUBROUTINE running...
MY_DECLARED_SUBROUTINE.arg1: 10.0
MY_DECLARED_SUBROUTINE.arg2: 11.0
MY_DECLARED_SUBROUTINE.optionalArg: 100.0
MY_DECLARED_SUBROUTINE running...
MY_DECLARED_SUBROUTINE.arg1: 4.0
MY_DECLARED_SUBROUTINE.arg2: 5.0
MY_DECLARED_SUBROUTINE.optionalArg: 200.0
MY_DECLARED_SUBROUTINE running...
MY_DECLARED_SUBROUTINE.arg1: 6.0
MY_DECLARED_SUBROUTINE.arg2: 7.0
MY_DECLARED_SUBROUTINE.optionalArg: 200.0


For a real example, see the file lib/Generate_Permutations.txt or lib/Generate_Combinations.txt.