Subroutines are a set of rules — a Rule. Subroutines are defined only (there is no need to declare them). Subroutine names are one or more lowercase letters within square brackets.
[product] = 1 ; set rval to 1 @for @_ ; each value in $_ *= $_ ; result in $0 @end
A subroutine ends at the end of the file or with any following subroutine definition. The loop termination operator,
@end, is not needed if it would be the last operator of a subroutine.
A subroutine is called just like any BCF, followed by any arguments which are stored in the special parameter variable
@_ as an array. Parameters are passed by copy.
product 2 4 6 8 ; call subroutine with four numbers ^ ; print result (in $0)
Currently there is no "return value" of subroutines, though any variable will do (they are all global). (A real return value will be implemented.)
The "return value" is generally by
$0, as in the example, but since all variables are global any variable can be used.
product 2 4 6 8 ^ $p [product] = p 1 @for @_ *= p $_ ; result in $p
Like Perl, arguments are passed as an array, with multiple arguments concatenated.
product (2,4,6,8) product (2,4) 6 8 = b (6,8) product (2,4) $b
The Rulz convention for subroutine names is "the shorter the better"; which, for short Rulz programs, "p" would be used rather than "product".
Redefining a subroutine is not an error; it wil simply overwrite the existing one.
@_ list of parameters @# count of parameters @* all parameters expanded to a string @0 first parameter @1 second parameter, etc., with @9 the limit @A first parameter @B second parameter, etc., with @Z the limit
The special variable
$@ is an alias to
Subroutine attributes are for saving special variables, "private" variables (same as Perl's "my"), and "local" variables (same as "static" in PHP).
Attributes have the format id:varhref and follow the subroutine name separated by spaces.
$_ special variable is automatically saved and restored. Other special variables are saved by the s: attribute. This attribute does not separate it's arguments with commas (so to allow the saving of
$,). (See href.)
p foo ^ foo [p s:.] = . "\r\n" ^ @0
That subroutine changes the line termination special variable,
Perl's "my" is implemented as p:.
[p p:p] = p 1 @for @_ *= p $_ @end = $p
There can be multiple variables per attribute and optionally can be set to a value. (The default is NULL.)
Testing program arguments can be done this way.
[args p:a,b] @for $ARGS ! /^(\-[a-z]+)(=?)(.*)/ >. =file $_ =a $1 =b $3 ? /-c/ $a =cat 1 ? /-d/ $a =dog 1 ? /-r/ $a =rat $b
$dog are "on off" conditions and
$rat is set to any argument supplied, with
$file set to any non-option (as globals).
$bare used because the following search operators will reset the subpattern variables. This construct is more suited to be in a subroutine. See #Special Subroutines.
A "local" variable (scope in the subroutine only) is by l:.
@for (1..4) sub [sub l:s] ++s ^ $s
$ ./rulz local.rul 1 2 3 4
Subroutines can recurse.
rsub [rsub l:s=1] ++s >? $s 4 .. ^ $s rsub
There are three file "forms" or a Rulz file. The first is with one or more rules.
# form one ^ just some rules
The second contains rules followed by one or more subroutines.
# form two sub [sub] ^ in subroutine
In this form all rules before any subroutine(s) are call "Top Rules".
The final form contains just subroutines and are useful as loadable libraries. Gine this file:
# lib.rul - an API [sub] ^ sub
.< lib.rul sub
Simply prints "sub".
Like Perl there are some special subroutines that are run internally.
_beginrun first after a program has been loaded.
_endrun last before program termination.
_suboptionally run before each and every other subroutine is run.
_sub subroutine to run the
$SUB Rulz variable need to be set to true (default is false), which is:
= SUB 1
Unlike Perl there can be only one of these subroutines per program.
_stopall further data are ignored.
These special subroutines, which are run after a progam is loaded, are for creating data — though not really subroutines, they just share the syntax.
_dataall lines following (until EOF or another subroutine) placed into
_data special subroutine is like Perl's
__END__ token. It is not like Perl's DATA file handle however; all text following it populates the Rulz variable $DATA.
_listall lines following placed into a list.
^ $var ; prints (1,2,"a") [_list var] 1 2 a
_constall lines following to define constants.
^ FOO BAR ; prints 1 2 [_const] FOO 1 BAR 2
_enumall lines following define constants starting from 1.
^ FOO BAR ; prints 1 2 [_enum] FOO BAR
All are processed before any top rules are run. Leading whitespace, blank lines and comments are ignored.