roo!™ syntax summary

# 1 Command line usage:

The roo!™ program operates as a Windows 32 console application. The following is the syntax of a roo!™ program request, that is entered as a DOS command prompt. There are four variations. In the first variation, roo!™ is the only program that is executed. The remaining variations are command pipelines. The vertical bars separate pipeline command segments.

roo programName [argumentText] [ < inFile ] [ [>]> outFile ] roo programName [argumentText] [ < inFile ] | programB programA | roo programName [argumentText] [ [>]> outFile ] programA | roo programName [argumentText] | programB

# 2 Instructions:

Assignment

variable = expression

objectRef = ^^ className[( argumentExpression [ , argumentExpression [ , ...etc ] ] ) ]

result = objectRef ~ methodName[( [ argumentExpression [ , argumentExpression [ , ...etc ] ] ) ]

result = ^ methodName[( [ argumentExpression [ , argumentExpression [ , ...etc ] ] ) ]

arrayRef [ index ] = expression

stemVariable [ index ] = expression

vectorRef = { value, value, ... } ...

Function calls

result = functionName( [ argumentExpression [ , argumentExpression [ , ...etc ] ] )

result = objectRef ~ methodName[( [ argumentExpression [ , argumentExpression [ , ...etc ] ] ) ]

result = ^ methodName[( [ argumentExpression [ , argumentExpression [ , ...etc ] ] ) ]

result = 'base' ~ methodName[( [ argumentExpression [ , argumentExpression [ , ...etc ] ] ) ]

result = 'self' ~ methodName[( [ argumentExpression [ , argumentExpression [ , ...etc ] ] ) ]

Address

1. address environmentName
2. address [ VALUE ] environmentExpression
3. address
4. address environmentName commandExpression

Arg

arg [ template ]

Call

call procedureName [ argumentExpression [ , argumentExpression [ , ...etc ] ]

Call

call ON conditionName [ NAME trapLabel ]

call OFF conditionName

Catch

catch [e = ] condition instruction(s)

Class

classNameLabel : class [extends baseClass [ explicitly ] ]

Command

commandExpression

! rooObjectExpression

Do

do
instruction
instruction
...etc
catch [e = ] condition
instruction(s)

finally
instruction(s)

end

Do

do [ repetitorClause ] [ conditionalClause ]
instruction
instruction
...etc
catch [e = ] condition
instruction(s)

finally
instruction(s)

end [ name ]

the repetitorClause can be one of the following:

controlVariable = initialValue [ to limitValue ] [ by stepValue ] [ for repetitionValue ]
repetitionValueExpression
forever

the conditionalClause can be one of the following:

while booleanExpression
until booleanExpression

Drop

drop variableList

End

end [ loopControlVariableName ]

Exit

exit [ valueExpression ]

Finally

finally instruction(s)

If

if booleanExpression then ... else ...

If

if booleanExpression then instruction if booleanExpression then instruction else instruction if booleanExpression then do instruction instruction ...etc end if booleanExpression then instruction else do instruction instruction ...etc end if booleanExpression then do instruction instruction ...etc end else do instruction instruction ...etc end if booleanExpression then do instruction instruction ...etc end else instruction

Interpret

interpret sourceExpression

Iterate

iterate [ loopControlVariableName ]

Leave

leave [ loopControlVariableName ]

Local

local variableName [ variableName2 ... ]

Loop

loop ix over aggregateObjectRef
instruction
instruction
...etc
catch [e = ] condition
instruction(s)

finally
instruction(s)

end

loop ix over compoundStem
instruction
instruction
...etc
catch [e = ] condition
instruction(s)

finally
instruction(s)

end

Method

methodNameLabel : method

The following methods are special:

- initialize

- terminate

- preinitialize

- finalize

Nop

nop

Numeric

numeric DIGITS [ digitsExpression ]

numeric SCIENTIFIC

numeric ENGINEERING

numeric FORM [ VALUE ] formValueExpression

numeric FUZZ [ fuzzExpression ]

Object instruction

... objectReference ~ method( ... ) ...

... A [ index ] ...

^^ className[( argumentExpression [ , argumentExpression [ , ...etc ] ] ) ] ~ method( ... ) ...

Options

options optionSetting(s)

Parse

parse [ upper ] valueToParse [ template ]

Where, valueToParse is one of the following:

arg

linein

pull

source

value [ expression ] with

var variableName

version

Procedure

procedureNameLabel : [ procedure [ expose variableList ] ]

Pull

pull [ template ]

Push

push [ valueExpression ]

Queue

queue [ valueExpression ]

Return

return [ valueExpression ]

Say

SAY [expression]

Select

select
when booleanExpression then instruction(s)
when booleanExpression then instruction(s)
...etc.
[ otherwise [ instructions ] ]
end

Shared

shared variableName [ variableName2 ... ]

Signal

signal labelName

signal [ VALUE ] labelExpression

Signal

signal ON conditionName [ NAME trapLabel ]

signal OFF conditionName

The conditionName in the signal ON or OFF is one of the following:

- ERROR

- FAILURE

- HALT

- NOTREADY

- NOVALUE

- OBJECTION

- SYNTAX

Static

static variableName [ variableName2 ... ]

Trace

1. trace setting
2. trace [ VALUE ] settingExpression
3. trace

# 3 Built-in functions

abbrev

result = Abbrev( information, info [, length ] ] )

abs

result = Abs( number )

address

result = Address()

arg

result = Arg( [ n [, option ] ] )

b2x

result = B2X( binary-string )

bitand

result = BitAnd( [ string1 [, [string2] [, pad ] ] ] )

bitor

result = BitOr( [ string1 [, [string2] [, pad ] ] ] )

bitxor

result = BitXor( [ string1 [, [string2] [, pad ] ] ] )

c2d

result = C2D( string [, n ] )

c2x

result = C2X( string )

callback

result = Callback( [ optionalArgument [ , optionalArgument ...etc] ] )

center

result = Centre( string, length [, pad ] )

center

result = Center( string, length [, pad ] )

changestr

result = Changestr( string, value, replacement )

charin

result = Charin( [ stream 1 ] [, [ start ] [, length ] ] )

charout

result = Charout( [ stream 1 ] [, [ string ] [, start ] ] )

chars

result = Chars( [ stream 1 ] )

compare

result = Compare( string1, string2 [, pad ] ] )

condition

result = Condition( [ option ] )

copies

result = Copies( string, n )

countstr

result = Countstr( string, value )

d2c

result = D2C( number [, length ] )

d2x

result = D2X( number [, length ] )

datatype

result = Datatype( string [, type ] )

date

result = Date( [ format ] )

delstr

result = Delstr( string, offset [, length ] )

delword

result = Delword( string, offset [, length ] )

digits

result = Digits()

errortext

result = Errortext( number )

exists

result = Exists( stem, compoundIndex )

form

result = Form()

format

result = Format( number [, [ before ] [, [ after ] [, [ expp ] [, [ expt ] ] ] ] )

fuzz

result = Fuzz()

insert

result = Insert( new, target [, [ offset ] [, [ length ] [, pad ] ] ] )

lastpos

result = Lastpos( needle, haystack [, offset ] )

left

result = Left( string, length [, pad ] )

length

result = Length( string )

linein

result = Linein( [ stream 1 ] [, [ line# ] [, count ] ] )

lineout

result = Lineout( [ stream 1 ] [, [ string ] [, line# ] ] )

lines

result = Lines( [ stream 1 ] )

lower

result = Lower( string [, n [, length ] ] )

max

result = Max( n1 [, n2 ] [, ... ] )

min

result = Min( n1 [, n2 ] [, ... ] )

nap

result = Nap( numberOfMilliseconds )

overlay

result = Overlay( new, target [, [ offset ] [, [ length ] [, pad ] ] ] )

pos

result = Pos( needle, haystack [, offset ] )

queued

result = Queued()

raiseobjection

call RaiseObjection conditionErrorText [, additionalInformation ]

random

result = Random( [ minOrMax ] [, [ max ] ] [, seed ] ] )

reverse

result = Reverse( string )

right

result = Right( string, length [, pad ] )

sign

result = Sign( number )

sourceline

result = Sourceline( [ line# ] )

space

result = Space( string [, [ n ] [, pad ] ] )

split

vectorRef = Split( string, separator )

squareroot

result = Squareroot( nonNegativeNumber )

stream

result = Stream( name 1, [, operation [, command ] ] )

strip

result = Strip( string [, [ option ] [, character ] ] )

substr

result = Substr( string, n [, [ length ] [, pad ] ] )

subword

result = Subword( string, n [, [ length ] )

symbol

result = Symbol( name )

time

result = Time( [ format ] )

trace

result = Trace( [ setting ] )

translate

result = Translate( string [, [after] [, [before] [, pad ] ] ] )

trunc

result = Trunc( number [, n ] )

upper

result = Upper( string [, n [, length ] ] )

value

result = Value( symbol [, [ newvalue ] [, selectorPool 2 ] ] )

verify

result = Verify( string, charSet [, [ option ] [, start ] ] )

word

result = Word( string, n )

wordindex

result = Wordindex( string, n )

wordlength

result = Wordlength( string, n )

wordpos

result = Wordpos( phrase, string [, ] )

words

result = Words( string )

x2b

result = X2B( hexadecimalString )

x2c

result = X2C( hexadecimalString )

x2d

result = X2D( hexadecimalString [, n ] )

xrange

result = Xrange( [ start ] [, end ] )

# 4 Expression operators:

Concatenation expression

(space) | date() time() | the space between the functions is a space concatenation operator
|| | date() || time() | the '||' operator is an explicit concatenation operator
(abuttal) | date()' at 'time() | the quoted string is implicitly concatenated to the adjacent terms

Arithmetic expression

+ | Add | 21 + 21
- | Subtract | 44 - 2
* | Multiply | 6 * 7
/ | Divide | 84 / 2
% | Integer divide | 85 % 2
// | Remainder | 42 // 50 | similar to modulo but the result can be negative
** | Power (exponent) | 2 ** 4
Prefix + | (0 + number) | + 42
Prefix - | (0 - number) | - 42

Comparison expression

= | equal
¬=, \=, ><, <> | not equal
> | greater than
< | less than
>=, ¬<, \< | greater than or equal; not less than
<=, ¬>, \> | less than or equal; not greater than

Strict comparison expression

== | strictly equal
¬==, \== | strictly not equal
>> | strictly greater than
<< | strictly less than
>>=, ¬<<, \<< | strictly greater than or equal; strictly not less than
<<=, ¬>>, \>> | strictly less than or equal; strictly not greater than

Logical expression

& | And | returns '1' when both terms are true, and '0' otherwise
| | Or | returns '1' when either term is true, and '0' otherwise
&& | Exclusive or | returns '1' when one of the terms is true (but not both), and '0' otherwise
Prefix ¬, Prefix \ | Logical not | returns '1' when the term is '0', and '0' when the term is '1'.

# 5 Stream names -- CHARIN, CHAROUT, CHARS, LINEIN, LINEOUT, LINES, or STREAM built-in function

1 The name of a stream is one of: 'console' is a special stream name. Stream builtin functions that access the 'console' stream interact with the Windows 32 command console. A single exclamation point ('!') is an abbreviated alias for the 'console' stream. the empty string ('') is a special stream name which denotes either the default input stream (stdin) or the default output stream (stdout). When a stream name is not specified in a CHARIN, CHAROUT, CHARS, LINEIN, LINEOUT, LINES, or STREAM built-in function request, either the default input stream or the default output stream is used. a file name, such as: statisticsFile.dat The file name can be qualified with a leading folder (directory) path: c:\MyDocuments\statisticsFile.dat The file name can be a relative folder (directory) path: ..\documents\statisticsFile.dat

# 6 Selector pool names -- VALUE built-in function

2 When the selectorPool option of the VALUE function is specified, it is interpreted as follows: If the selector option is 'system', then values are associated with environment variables of the ROO program scope. Revisions to environment variables will be seen by commands started by ROO. These revisions are lost when the ROO program concludes. Thus, ROO programs can not permanently alter environment variables. The environment variable access section below shows how to set and reference environment variable values. The 'registry' selector option is used to access and revise system registry values. Revisions to registry values are permanently altered. The registry value access section below shows how to access and revise system registry values. Any other selector option is considered to be the name of a file. If the file name does not have a backslash, then the file is stored in the same directory as ROO.EXE. Values are stored when the ROO program terminates.

# 7 Environment variable access

The following shows how the VALUE function is used to set and reference environment variable values.

/* DOENV.REX */ call value 'magic', 'abracadabra', 'system' /* set magic environment variable */ say value( 'magic', , 'system' ) /* get magic environment variable */

# 8 Registry value access

Access to system registry information allows r4™ to prepare and reference information that is used by other system software. This is a powerful capability. However, since system registry information is critical to correct system operation, r4™ can only perform some registry operations. You should be particularly careful when revising registry values. Erroneous revisions can have serious consequences. These changes cannot be undone.

Due to the sensitivity of system registry information, r4™ can only be used to access and revise registry values. The product does not provide capabilities for accessing registry keys directly, and registry keys and values can not be removed. All registry values that are accessed by r4™ must be strings. No other registry value format is supported.

As an extra precaution, registry revisions are only permitted when the ROOREGISTRYWRITE environment variable has value: 'Y'. You can locally alter this value, as shown in the example below. No error occurs if this environment variable has not been set.

You are strongly advised to B-A-C-K-U-P the system registry before attempting to revise it with an ROO program.

If you are unfamiliar with the detailed characteristics of the system registry, you should discuss what you plan to do with a business colleague or friend, BEFORE attempting to revise registry information.

Registry values are accessed using a three part name, that has the following structure:
root\keyPath[valueName]

The keyPath consists of a hierarchy of keys separated by backslashes.

The valueName must be enclosed in square brackets.

The root must be one of the following:
'HKEY_CLASSES_ROOT'
'HKEY_CURRENT_USER'
'HKEY_LOCAL_MACHINE'
'HKEY_USERS'
'HKEY_CURRENT_CONFIG'
'HKEY_DYN_DATA'

The following root aliases are supported:

'HKCU' | HKEY_CURRENT_USER
'HKLM' | HKEY_LOCAL_MACHINE
'HKCR' | HKEY_CLASSES_ROOT
'HKU' | HKEY_USERS
'HKCC' | HKEY_CURRENT_CONFIG
'HKDD' | HKEY_DYN_DATA

The following shows how the VALUE function is used to access and revise system registry values.

/* DOREG.REX */ root = 'HKEY_CURRENT_USER' keypath = 'Software\Kilowatt Software\DoReg' regvalue = 'Magic' /* enable registry revision */ call value 'ROOREGISTRYWRITE', 'Y', 'system' /* set ROOREGISTRYWRITE=Y */ /* revise registry value */ call value root'\'keypath'['regvalue']', 'abracadabra', 'registry' /* disable registry revision */ call value 'ROOREGISTRYWRITE', 'N', 'system' /* set ROOREGISTRYWRITE=N */ /* registry values can still be retrieved */ /* get registry value */ say value( root'\'keypath'['regvalue']', , 'registry' )

Copyright © 2002-2007
All Rights Reserved.
Web: http://www.kilowattsoftware.com/
E-Mail: r4support@kilowattsoftware.com

Last updated on: 18 Jun 2004