Rulz Programming Language

Subroutines

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.

Subroutine Parameters

@_                      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

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.

save

The $_ 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, $., temporarily.

private

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

[p p:a,b=1]

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

Where $cat and $dog are "on off" conditions and $rat is set to any argument supplied, with $file set to any non-option (as globals).

The variables $a and $b are used because the following search operators will reset the subpattern variables. This construct is more suited to be in a subroutine. See #Special Subroutines.

local

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

Rulz File Format

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

This Rule:

.< lib.rul
sub

Simply prints "sub".

Special Subroutines

Like Perl there are some special subroutines that are run internally.

For the _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.

Data Subroutines

These special subroutines, which are run after a progam is loaded, are for creating data — though not really subroutines, they just share the syntax.

The _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.

^ $var			; prints (1,2,"a")
[_list var]
1
2
a
^ FOO BAR		; prints 1 2
[_const]
FOO 1
BAR 2
^ 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.