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:

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, ... } ...

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

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

arg [ template ]

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

call ON conditionName [ NAME trapLabel ]
  

---


call OFF conditionName

catch [e = ] condition instruction(s)

  classNameLabel : class [extends baseClass [ explicitly ] ]

commandExpression
  

---


! rooObjectExpression

do
  instruction
  instruction
  ...etc

  catch [e = ] condition
    instruction(s)


  finally
    instruction(s)


  end

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 variableList

end [ loopControlVariableName ]

exit [ valueExpression ]

finally instruction(s)

if booleanExpression then ... else ...

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 sourceExpression

iterate [ loopControlVariableName ]

leave [ loopControlVariableName ]

  local variableName [ variableName2 ... ]

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

  methodNameLabel : method

The following methods are special:

• initialize

• terminate

• preinitialize

• finalize

  nop

numeric DIGITS [ digitsExpression ]

---

numeric SCIENTIFIC

---

numeric ENGINEERING

---

numeric FORM [ VALUE ] formValueExpression

---

numeric FUZZ [ fuzzExpression ]

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

---

... A [ index ] ...
  

---

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

options optionSetting(s)

parse [ upper ] valueToParse [ template ]
  

---

Where, valueToParse is one of the following:

  arg

  linein

  pull

  source

  value [ expression ] with

  var variableName

  version

procedureNameLabel : [ procedure [ expose variableList ] ]

pull [ template ]

push [ valueExpression ]

queue [ valueExpression ]

return [ valueExpression ]

SAY [expression]

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

  shared variableName [ variableName2 ... ]

signal labelName
  

---

signal [ VALUE ] labelExpression

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 variableName [ variableName2 ... ]

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

3 Built-in functions

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

  result = Abs( number )

  result = Address()

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

  result = B2X( binary-string )

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

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

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

  result = C2D( string [, n ] )

  result = C2X( string )

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

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

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

  result = Changestr( string, value, replacement )

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

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

  result = Chars( [ stream ¹ ] )

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

  result = Condition( [ option ] )

  result = Copies( string, n )

  result = Countstr( string, value )

  result = D2C( number [, length ] )

  result = D2X( number [, length ] )

  result = Datatype( string [, type ] )

  result = Date( [ format ] )

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

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

  result = Digits()

  result = Errortext( number )

  result = Exists( stem, compoundIndex )

  result = Form()

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

  result = Fuzz()

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

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

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

  result = Length( string )

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

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

  result = Lines( [ stream ¹ ] )

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

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

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

  result = Nap( numberOfMilliseconds )

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

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

  result = Queued()

  call RaiseObjection conditionErrorText [, additionalInformation ]

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

  result = Reverse( string )

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

  result = Sign( number )

  result = Sourceline( [ line# ] )

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

  vectorRef = Split( string, separator )

  result = Squareroot( nonNegativeNumber )

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

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

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

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

  result = Symbol( name )

  result = Time( [ format ] )

  result = Trace( [ setting ] )

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

  result = Trunc( number [, n ] )

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

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

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

  result = Word( string, n )

  result = Wordindex( string, n )

  result = Wordlength( string, n )

  result = Wordpos( phrase, string [, ] )

  result = Words( string )

  result = X2B( hexadecimalString )

  result = X2C( hexadecimalString )

  result = X2D( hexadecimalString [, n ] )

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

4 Expression operators:

(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

+	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

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

==	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

&	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

6 Selector pool names -- VALUE built-in function

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