Rulz Operator Reference

Notation Convention

Operator Arguments

num                     number
var                     variable name
$var                    variable
[$var]                  optional variable

String Literals

abc                     one or more lower case letters
ABC                     one or more upper case letters
file                    a valid file name
word                    "word" characters (as Perl)
words                   one or more "word"s separated by spaces
text                    printable characters, including space
pattern                 regular expression

Basic Operators

Operators categorized here by number of characters.

Single Character Operators

There are two groups of these. Those always singular; those that can have a prefix modifier character. The prefixed versions are described below.

:                       non-operator
#                       comment
;                       comment
=                       set (assignment)
?                       conditional
!                       conditional
.                       jump
&                       file
^                       print

(Unlike most other languages, the "print function" is an operator.)

Two Character Operators

These operators have three classes.

  1. Two character versions of single character operators (a single character operator with a modifier).
  2. Two character operators (which are like a single character operator that always has a modifier).
  3. Double character operators.

Modified Single Character

These two character operators are single character operators "modified" with a prefix character. They can be grouped by type.

Arithmetic operators modify the Set operator.

+=                      addition
-=                      subtraction
*=                      multiplication
/=                      division
%=                      modulo
.=                      concatenation

Similarly, the Bitwise operators.

~=                      not
&=                      and
|=                      or
^=                      xor
<=                      shift left
>=                      shift right

The Unset operator. (And an example of how Rulz does things differently.)

!=                      unset

The two Constants operators.

,=                      enumeration of arguments
:=                      set constant

The Comparison operators are modified Conditional operators.

=?                      equal
=!                      not equal
<?                      less than
<!                      not less than
>?                      greater than
>!                      not greater than

Similar are the Evaluation operators.

??                      defined (variable)
?!                      not defined
&?                      defined (subroutine)
&!                      not defined

There are two for Constants.

:?                      defined
:!                      not defined

The modified Open operators expand basic open/read/write/close operators.

-&                      open file for writing
+&                      open file for appending
.&                      close
<&                      read line/bytes
[&                      read line with chop
{&                      read character
(&                      read formatted line
/&                      read regular expression
>&                      write line
]&                      write line without EOL
}&                      write character
)&                      write formatted line

modified Open operators expand basic file functions.

@&                      EOF test
=&                      seek
,&                      rewind
?&                      tell
:&                      truncate

Other modified file operators for file names not file handles.

^&                      touch
!&                      delete
|&                      rename/move
%&                      stat

There are several function-like operators that read or write files directly. (Though they can be considered modified read and write operators.)

<<                      get file contents
[<                      get file as list with EOL
(<                      get file as list without EOL
>>                      put file contents
]>                      put list to file with EOL
)>                      put list to file without EOL
+>                      append string to file
->                      prepend string to file

There are operators to read STDIN directly.

=<                      read line
_<                      read line with chomp

The loop control operators are like modified jump operators (loops operators are described below).

..                      break
>.                      continue
<.                      redo

The modified print operators include a few similar functions.

-^                      print with no newline
\^                      print just a newline	
/^                      print escaping control characters
>^                      print to STDERR
%^                      print formatted
~^                      die
.^                      exit

Double Character Operators

Most double characters are similar to other languages (though they can be a bit unique in application).

++                      increment
--                      decrement
!!                      logical not
||                      logical or
&&                      logical and
^^                      logical exclusive or
//                      logical defined or

(See also Multiple Character Pairs for multi-line comments.)

Two Character Operators

These operators are syntactically similar to the modified single character operators but always have two characters.

File Operators

The file operators are based on Bash conditional operators, but use Rulz' "operator prefix" in that the letter occurs first.

f-                      is file
d-                      is directory
r-                      is readable
w-                      is writeable
x-                      is executable

These file operators are like functions.

s-                      file size
p-                      file permissions
t-                      file type
g-                      file group
a-                      file access time
c-                      file change time
m-                      file modification time

Type Operators

The type operators test the type of a variable.

S-                      is string
I-                      is integer
D-                      is double
A-                      is list or hash
N-                      is numeric
B-                      is boolean
U-                      is null
T-                      is true (PHP like)
Z-                      is empty (PHP like)

String Operators

These operators are similar to PCRE generic character types, POSIX notation for character classes, or PHP ctype functions.

u?                      is uppercase
l?                      is lowercase
d?                      is decimal
s?                      is whitespace 
w?                      is word character
n?                      is alpha numeric
a?                      is alpha
c?                      is control
g?                      is graph
p?                      is printable
v?                      is punctuation
x?                      is hexadecimal

All have a ! version to negate the test. (Though they look it, these are not considered modified conditional operators.)

String Function Operators

The operators perform function-like operations on strings.

u~                      to upper case
l~                      to lower case
n~                      length
q~                      quote meta 
i~                      index (substr)
s~                      string occurrence
S~                      string occurrence (case insensitive)
p~                      string position
P~                      string position (case insensitive)
c~                      chop (PHP like)
C~                      chomp (Perl like)
t~                      trim
T~                      trim right
L~                      trim left
f~                      sprintf
F~                      sscanf
h~                      htmlentities
H~                      htmlspecialchars
x~                      explode
w~                      wordwrap
r~                      string replace
R~                      string replace (case insensitive)
e~                      urlencode
E~                      urldecode
y~                      crypt
g~                      preg split
b~                      basename
d~                      dirname

List Operators

List operators perform Perl/PHP functions to create or modify lists.

/[                      split
:[                      join
~[                      values
%[                      keys
@[                      sort
\[                      reverse
<[                      shift
>[                      unshift
-[                      pop
+[                      push
,[                      slice
([                      extract
^[                      difference
=[                      count
?[                      index/key exists (boolean)
![                      value exists (boolean)
'[                      value exists (search) returns value
"[                      random value

Many of the arithmetic and bitwise operators can be applied to lists.

Mathematical Operators

These are like basic mathematical functions of most languages.

v/                      square root
2/                      square
1/                      reciprocal
a/                      absolute
^/                      exponent

(This is not a complete list.)

Percent Operators

These may be unique to the Rulz language (further research needs to occur).

=%                      percentage of
/%                      percentage against
+%                      percentage add
-%                      percentage from
*%                      percentage between

Parameter Operators

These are based on Perl's shift with no argument, and partly on Bash's set.

=@                      set parameters
+@                      append parameter
<@                      shift parameter
>@                      unshift parameter

Character Pair Operators

These operators have a begin and an end character.






Other Operators

Loop Operators

These operators are quite different, and are the only "block" constructs.

@do                     a non-conditional loop
@each                   iterate a hash
@for                    iterate an array
@while                  while true
@until                  while false
@end                    end

These are similar to their typical language constructs.


The two character versions also use @ first — so are listed here rather than previously (as they are a slight violation of the "prefix modified" operators).

@?                      @if
@[                      @each
@(                      @for
@>                      @while
@<                      @until
@=                      @switch
@:                      @case
@.                      @end

Then again, the following alternatives take care of that.

i@                      @if
e@                      @each
f@                      @for
w@                      @while
u@                      @until
s@                      @switch
c@                      @case
@                       @end

Three Character Operators

<<<                     heredoc
>>>                     filedoc

Multiple Character Pairs

Multi-line comments are actually implemented as an operator — though there is an option to discard comments when loading. (Retaining comments is useful for some code diagnostics.)

The start and end character sequences need to be at the start of a line (leading whitespace ignored).

Begin and end on a double hash.

(If at the end of a file or a subroutine the final ## is not required.)

PHP and HTML comments are also supported.

PHP style comment
HTML style comment

(These were supported only because it took only a few lines of code to do so.)