ArborX

?

Longname: ?   Open the Documentation Legend
Released: 1.00 
Created: 1.00 
Last modified: 7.51c 
See also: addstr defstr { } :
3B2 Scripting Expressions (n/a)

Summary
 3B2's script extension has a condition tester that allows macros to be executed only when the condition is true. As with labels and jumps the condition tester, in this form, is only available within scripts executed with trun. Examples of all 'conditions' and their operators are documented below.
Example extract
 ?0^count }finish 1
 ?+^num trun --1 3
 ?-^say @hello 5
 ?+-^end {loop 7

Syntax (1.00)
? condition:n component1:m  component2:m? macro:m
condition:n
0 or =  Test if element1 has a value of zero, or element1 and element2 are equal.
+  Test if element1 has a value greater than zero, or element1 is greater than element2.
-  Test if element1 has a value less than zero, or element1 is less than element2.
#  Verify strings.
Version specific information7.60a  Pre V7.60a the = operator was added for you by default. Post V7.60a for * and # the = will only be added for if =, 0, + or - were not already given. This makes reverse logic tests easier.
/  Compare a regular expression. = (or 0), +, - operators will always be ignored in conjuction with this operator. The tester returns 0 (false) if the expression does not match. If there is a match, the actual match position is returned (1st char at position 1).
@  Force case sensitive comparison.
*  Use wild card on right parameter.
Version specific information7.60a  Pre V7.60a the = operator was added for you by default. Post V7.60a for * and # the = will only be added for if =, 0, + or - were not already given. This makes reverse logic tests easier.
' '   A space after the condition will allow spaces in your test
component:
^variable  Any valid variable name preceded with a ^ character.
"string"  Any valid stream name, i.e. ^tx1 refers to the variable and ^"tx1" refers to the text stream.
Version specific information7.00  Post 3B2 Version 7 this will only retrieve 159 characters, if the stream is longer then the surplus is ignored (see )
.
integer  Any 32 bit number e.g. -2 147 483 and 2 147 483.
^(expres)  Any 3B2 expression, see .
element2:

In addition to the same values as element1, element2 can also take various test options listed below, specify the test range and the option:

i  Tests the element is an integer in the range low...high
u  Tests the element is a unit in the range low..high, where 10000 represents 1mm.
m  Tests that the element is a fixed point number in the range low..high, where the ranges are multiplied by 10000. i.e. 10000..20000m will check for a number in the range 1.0000 to 2.0000.
S  Tests that the element contains a valid tag name.
s  Tests that the element contains a string whose number of characters is between low...high inclusive.
q  Tests that the element contains an optional unit plus a fraction of the width or height. low...high are the allowable ranges for the unit.
N  Tests that the element contains a valid page number. This also allows for the extended syntax of sub-page-numbers when pages have been frozen, i.e. <?show $p> instead of <?show $g>. If low.. is 1, then the separator between sub-page-numbers is '_' instead of ' . '
c  Tests that the field is a valid colour description.

The macro you want to run if condition is true. This can either be a normal 3B2 macro or, uniquely, a { or } macro to jump to a certain section of your script.

If the macro contains any variables that need replacing with a value (by terminating the line with a ^) the replacement does not take place until the macro portion of the line is passed to the normal macro processor. (This means that the variable(s) which make up part of the test at the beginning of the line do not get replaced.)

Examples of various conditional tests are detailed below.
Example
 ?=^var1,^var2 }finish

If ^var1 is equal to ^var2, jump to label.

 ?^var1,^(1) tpgoto 100

If ^var1 is greater than 1, go to page 100

 ?-^var1,^(^page+^count) {top

If ^var1 is less than total of ^page plus ^count jump to label (see Expressions_en

 ?=^char,'a' @Letter 'a' was pressed

If ^char is equal to the Keycode of 'a' then insert text

 ?= 1,^value @Value is -1

If ^value is -1 then insert text
Example

Another commonly needed requirement is to test whether a string is empty (contains no characters at all). You can do this by comparing it with a blank string represented by " ":

 ?=^string1,^string2 @Streams are equal 3
 ?+-^string1,^string2 (^string1=Strings were different):(boxit \^string1^) 5
 ?=^string," "}empty_string 7
 :empty_string 9
Example

It can also be necessary to check whether or not a number is odd or even. Because numeric variables are always whole numbers, dividing the number you want to test by two, and then multiplying it by two, will produce different results according to whether the number was odd or even. In the example below we find out if the last page of a document is even or odd:

 getvar 01535 "lastpage" 3
 ^tmp=^lastpage 5
 ^tmp/2 7
 ^tmp*2 9
 ^tmp-^lastpage 11
 ?=^tmp boxit \^lastpage is even^ 13
 ?-^tmp boxit \^lastpage is odd^ 15
Example

Verify strings let you test a string for certain criteria, and return a result of true or false, depending on whether the string matched the given criteria or not, see the test option parameter.

This example of the 'i' option tests if the variable ^num contains an integer number in the range 1 to 20 and if so display to the screen.

 ^num=20 4
 ?=#^num,"1..20i"}show_me 6
 ?+#^num,"1..20i"}exit 8
 :show_me 10
 boxit ^num is valid^ 12
 :exit 14
 trun 0 16
11
Set the variable ^num to the value 20
13
If ^num contains an integer in the range 0 → 20 then jump to label
15
If ^num contains an integer greater than the range 0 → 20 then jump to label
17
Label
19
Using boxit display the contents of ^num and the following text
21
Label
23
Stop script
Example

Regular expressions add a powerful extension to the conditional test macro see also Regular expressions_en.

The examples below illustrate some of the many options available using regular expressions.

 ?=/^var1,"[0-5]" }loop 4
 ?=/^string1,"[^a-zA-Z]" }num 6
 ?=/^name,"a.b" @Match is good 8
Example

Execute macro if test not true. In this case we are testing if the ^text variable contains something other than a tag who's name consists of characters a-z.

 ?+-#^text,"/(<[a-z]>+)"macro
Example

As shown in the example below the 'wild card' enables you to test for data without exact comparison being known, as '?' in search and replace.

 ?=*^filename,"*.3d" }end
Example

Enables 'case sensitive' tests on strings. The example below will not execute the macro, as a capital 'A' will have a higher value than the lower case 'a'.

 ^var1=a 1
 ^var2=A 2
 ?=@^var1,^var2 }loop 3

If ^var1 is equal to ^var2 then jump to label

Document created on 08-Feb-2003 (revision 1)