RISC DISC 2

home *** CD-ROM | disk | FTP | other *** search

/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / language / bob / doc / Ref / Built_in next >

Wrap

Text File | 1994-12-30 | 25.3 KB | 696 lines

ArmBob v.2.1 Reference GCW 29/11/94 ----------------- BUILT IN NAMES --------------- Operators --------- Armbob has the following operators. Ternary: c?yes:no c an integer. If c is nonzero, the expression evaluates and returns the value of yes (no is not evaluated), otherwise it evaluates and returns the value of no (yes is not evaluated). Binary: x || y x, y integers. If x is nonzero, the expression evaluates to 1, without evaluating y. Otherwise it returns 0 if y is zero and 1 otherwise. x && y x, y integers. If x is zero the expression returns 0 without evaluating y. Otherwise it returns 0 if y is zero and 1 otherwise. x | y x, y integers. Returns the bitwise OR of x and y. x ^ y x, y integers. Returns the bitwise XOR of x and y. x & y x, y integers. Returns the bitwise AND of x and y. x == y x, y both integers, strings or reals. It returns 0 if they are different and 1 if they are equal. x != y x, y both integers, strings or reals. It returns 1 if they are different and 0 if they are equal. x < y x, y both integers, strings or reals. It returns 1 if x strictly precedes y, otherwise it returns 0. x <= y x, y both integers, strings or reals. It returns 1 if x precedes or equals y, otherwise it returns 0. x >= y x, y both integers, strings or reals. It returns 1 if y precedes or equals x, otherwise it returns 0. x > y x, y both integers, strings or reals. It returns 1 if if y strictly precedes x, otherwise it returns 0. x >> y x, y both integers. It returns x arithmetically shifted right by y bits. x << y If x, y are both integers it returns x shifted left by y bits. If x is an iostream and y a string, it outputs y to x and returns the result x. x + y If x, y are both integers or both reals it returns their sum. If x, y are both strings it returns their concatenation. If either x or y is a string and the other argument is an integer, the other argument is converted to the string consisting of the single character given by the ASCII code of the bottom 8 bits and the result is the concatenation of the two strings. x - y x, y both integers or both reals. The difference is returned. x * y x, y are reals or integers. The product is returned. The type of the result is real if either x or y is a real and integer otherwise. x % y x, y both integers. The remainder is returned. x / y If x is an integer, then so must y be and an integer quotient is returned. If x is real y may be either an integer or a real and the real quotient is returned. Unary: -x x integer or real. Minus x. !x x integer. Returns 0 if x is nonzero and 1 otherwise. ~x x integer. Returns the bitwise NOT of x. Binary assignment: x = y Assign y to x, and return x. x += y Assign x+y to x, and return x. x -= y Assign x-y to x, and return x. x *= y Assign x*y to x, and return x. x /= y Assign x/y to x, and return x. x %= y Assign x%y to x, and return x. x &= y Assign x&y to x, and return x. x |= y Assign x|y to x, and return x. x ^= y Assign x^y to x, and return x. x >>= y Assign x>>y to x, and return x. x <<= y Assign x<<y to x, and return x. Unary assignment (integer expressions only): x++ Evaluate x in current expression, and then assign x+1 to x. x-- Evaluate x in current expression, and then assign x-1 to x. ++x Assign x+1 to x before further evaluation. --x Assign x-1 to x before further evaluation. Gazette of built-in values and keywords --------------------------------------- Storage and creation -------------------- $ $(x) The string stored at address x. The string is terminated by any character with ASCII code less than 32. The address x should be an integer divisible by 4. ......................................................... $$ $$(x,s) Place string s at address x. The value of s is returned. Example $$(x,$$(y,s)); stores s at both x and y. ............................................................ @ @(s) The address of the first character of the string s. This address is divisible by 4. Strings are stored as a consecutive array of bytes. Example @s = @(s = "hello"); Note that s = $(@("hello")); is equivalent to s = "hello"; . ............................................................. class Keyword introducing a class definition. Class definitions can only appear at the top level. That is to say, they cannot appear inside a class definition or a function definition. Class definitions must precede the definitions of any of their instance objects. Example class point { q; /* a vector of coordinates */ } We say that the class point has the vector q as its data. Methods for a class can be declared inside the class's definition but this is optional. They must be defined outside the class definition. For example, to add a method to point to read its first coordinate, we could have Example point::x() { return q[0]; } :: Thus, method definitions are exactly like function definitions except that the class name, followed by ::, prefixes the method name. The same method name can be used in different classes. That is to say, data and this method names are local to a class. The variable 'this' can be used in a method to refer to the instance object using the method. Example point::translate(x,y) { q[0] += x; q[1] += y; return this; } To create an instance object of a class a method must be defined with the same name as the class. Example point::point(x,y) { q = newvector(2); q[0] = x; q[1] = y; return this; } A particular point is then created by Example vertex = new point(3.5,6.0); new using the keyword 'new'. It can then be shifted by using the 'translate' method Example vertex = vertex->translate(1.0,-1.0); -> The -> operator connects an expression for an instance object with a method to produce an actual function. Example print("The x-coordinate of vertex is ",vertex->x(),"\n"); Each instance object of a class has its own private copy of the class's data, which can only be updated or accessed using a method A class can inherit the data and methods of another class. Example class particle::point { v; } particle::angular_momentum() { return (q[0]*v[1] - q[1]*v[0]);} The particle class inherits all the data and methods of the point class. static Data and methods in a class definition can be declared to be static, by placing the word 'static' in front of their declaration. Static data and methods are shared by all instances of a class, and static methods may not have the variable 'this' in their definition. A typical use of static variables would be a variable to count the number of instance objects of a certain kind. Example class foo { static total; ........... } foo::foo(...) { if (typeof(total)) total += 1; else total = 1; .............. } foo::current_number() { return total; } ............................................................... enum enum { x1 , ... , xn } This returns the integer n and assigns the values 0, 1, ... (n-1) to the n variables x1, ... xn in order. It is useful for hiding explicit indexing. Example v = newvector(enum {x,y,z}); v[x] = v[y] = v[z] = 0.0; employee = enum { name,salary,department }; fred = newvector(employee); fred[name] = "Fred"; fred[salary] = 20000; fred[department] = Widget_Handling; ................................................................. gc gc() Calling this function forces a garbage collection of the heap. The value nil is returned. ................................................................ in .. put { ... } in b put { x1 ; .... ; xn;} The expression b denotes either a string or an integer address expression specifying a buffer into which the integers or strings x1 ... xn are to be put. This is useful for defining windows, icons or menus. ................................................................... new This word is used to create a new instance object of a class. See the section on class. .................................................................... newstring newstring(n) Allocates an array of n bytes in the heap, starting on a word boundary, initializes them to zero, and returns the string which has this array as its value. ..................................................................... newvector newvector(n) Allocates space in the heap for an n-component vector, whose values are all nil, and returns this vector. ...................................................................... nil The single value of type NIL. ....................................................................... put See the section in ... put { ..... } ...................................................................... sizeof sizeof(s) Returns the number of characters in a string s, or the number of components of a vector s, as an integer. ...................................................................... static Introduces static data or method names in class definitions. See the section on class. ....................................................................... typeof typeof(x) Returns the integer code describing the type of x. The type of nil is 0, and all other values return a nonzero value. This is useful for coping with undefined vector components. Example a = typeof(a)?a:0; ..................................................................... vector vector { x1 , ... , xn } Returns a new vector with components x1, ... , xn. There must be at least one component and not more than 255 for this construction. ...................................................................... ` `(x) Returns as an integer the contents of the byte at the address x or in the string x. If s is a string `(s) is the same as s[0]. ...................................................................... `` ``(x,c) Place byte c at address x, and return c. ...................................................................... £ £(x) Returns as an integer the contents of the word at the address x or in the string x. ...................................................................... ££ ££(x,n) Place integer n as a word at address x, and return n. ................................................................. Condition and repetition ------------------------ break break; Jump out of the current structure. It only makes sense within a 'switch', 'do'/'repeat', 'for' or 'while' structure. ........................................................... case case x: See the section on 'switch'. ............................................................ continue continue; Start the next iteration of the smallest enclosing 'do'/'repeat', 'for' or 'while' structure. ............................................................. default See the section on 'switch'. .............................................................. do .. until/while do .. until (x); do .. while (x); Looping construct where the body is executed at least once. ............................................................... else Optional part of 'if' construct. See the section on 'if'. ................................................................ for for(<start>;<terminate>;<action>) ... iteration construct Example for(i = 0; i<sizeof(v); i++) print("v[",i,"] = ",v[i],"\n"); .................................................................. if .. else .. if (<condition>) .... conditional construct if (<condition>) .... else .... A condition is regarded as false if it is either the integer 0 or the value nil. Other values count as true. FALSE FALSE is a synonym for 0. TRUE TRUE is a synonym for 1. ................................................................... repeat .. until/while repeat ....... until <condition> repeat ....... while <condition> 'repeat' is a synonym for 'do'. See the section for 'do'. See the section for 'if' for a discussion of conditions. ................................................................... return return x; Return x from a function. return; is equivalent to return nil; Functions with no return statement return nil. ..................................................................... switch .. case .. default switch (x) If the integer or string value { x matches a value following a 'case' case y: the corresponding statements are ............. executed. Note that unless one wants case z: to drop through to the next match ............. the statements should be terminated ............... by 'break'. If no matches occur, the default: statements following 'default:' are ............. executed. The 'default' part is } optional. ................................................................... while while (x) ........ while construct. ..................................................................... Random integers --------------- rnd rnd() Returns a random positive integer. Example chance = rnd()%n; .............................................................. seed seed(n) Seeds the random number generator with the integer n and returns nil. Example seed(time()); ................................................................ Input/Output ------------ EOF EOF End of file value, -1. .......................................................... fclose fclose(fp) Closes the IOSTREAM fp and returns nil. ............................................................ fopen fopen(filename,mode) Opens a new IOSTREAM connected to the file named by 'filename', in mode 'mode' and returns either nil, if it cannot open the channel, or the IOSTREAM. The mode variable can take the values "r" (read), "w" (write) and "a" (append). .............................................................. getarg getarg(i) Return the i-th argument on the command line as a string, if there is one, and nil if there is none. The 0-th argument is the command itself (the program's pathname). Example for(i = 1; typeof(arg = getarg(i)); i++) process(arg); ................................................................ getc getc(fp) Returns a character or EOF from the IOSTREAM fp. ............................................................... input input() Returns an input string. Leading spaces are not removed. To input a number use the function val. Example print("Input a number.\n? "); x = val(input()); This should not be used in a wimp program. .................................................................. print print(x1, ... ,xn) Print the items x1, .... xn and return nil. Newlines are not automatically appended. The digrams \n, \t, \\ can be used in strings for newline, tab and \, respectively. This should not be used in a wimp program. The expression fp << s will output a string s to the iostream fp. The value of this expression is fp, and << associates to the left, so that fp << s1 << s2 ..... is equivalent to fp << (s1 + s2 + ...... ) .................................................................... putc putc(ch,fp) Writes the character ch to the IOSTREAM fp. Returns nil. ................................................................ stderr stderr Built in IOSTREAM constants. stdin stdin stdout stdout .................................................................. Conversion ---------- val val(s) Converts as many characters of the string s to a number as it can. Decimal or hexadecimal numbers (prefixed by &) are recognized. Note that the hexadecimal digits a,b,c,d,e,f are in lower case. Reals are distinguished by a decimal point. ....................................................................... Real arithmetic functions ------------------------- acos acos(x) Arc-cosine asin asin(x) Arc-sine atan atan(x) Arc-tangent cos cos(x) Cosine exp exp(x) Exponential log log(x) Natural Logarithm sin sin(x) Sine sqrt sqrt(x) Square root tan tan(x) Tangent pi pi Built in constant. System ------ oscli oscli(s) Sends a string s to the command line interpreter. The value nil is returned. ................................................................... quit quit(s) Causes the program to exit with a message string s to stderr and returns nil. In wimp programs, wimp_closedown is called. ................................................................... start_task start_task(s) Takes a command in the string s to start up a child task, and returns its task handle. This works both from BobFiles (i.e. from a command window) or from BobTasks (i.e. from a taskwindow). This function should only be used outside wimp programs (i.e. before wimp_init or after wimp_closedown). There are other means of starting a child task from within a wimp program. .................................................................. swi swi(x,r) x is either the SWI integer or the SWI's name as a string. r is a vector of at least 8 integers. SWI x is called with register values given by the components r[0], r[1], ... r[7] and the function returns nil with the returned values of the registers in the components of r. Example getenv() { local r; swi("OS_GetEnv",r = newvector(8)); return($(r[0])); } This function to get the command string is superfluous in view of the function getarg, but it illustrates the use of swi. Note that even though a SWI may pass no values in registers, it is necessary for the second argument of swi to be a vector with at least 8 components. ................................................................... sysvar sysvar(s) Returns the string value of the string system variable s, or nil if it does not exist. Example print(sysvar("Bob$Path"),"\n"); ..................................................................... time time() Returns the first 32 bits of the time in centiseconds since the beginning of the century. Example start = time(); process(); end = time(); print("That took ",(end-start)*0.01," seconds\n"); ................................................................. wimp_closedown wimp_closedown() Programs running as wimp tasks must use the function wimp_closedown before terminating. It returns nil. ................................................................. wimp_init wimp_init(vn,name,mesg_list) vn is 100 times the version of RISC OS being used, name is the name of the wimp task, and mesg_list is a buffer, given as a string or its integer address, containing the messages, stored as words and terminated by 0, which the task wishes to receive. The function returns the task handle as an integer. After wimp_init the following function is useful for factoring wimp programs. Example event_process(maskptr,buffer,action,user) { local r, respond, go_on; r = newvector(8); go_on = TRUE; while(go_on) { r[0] = maskptr[0]; r[1] = buffer; swi("Wimp_Poll",r); go_on = (typeof(respond = action[r[0]])== BYTECODE)? respond(buffer,user,maskptr):TRUE; } wimp_closedown(); } This function event_process takes as arguments: maskptr - a 1-component vector containing the bit mask for Wimp_Poll. Handler functions can update the mask via their third argument. buffer - a buffer for wimp messages, passed to handler functions as the first argument. action - a 20-component vector of handler functions expecting 3 arguments, that return zero to cause an exit and a nonzero integer to continue. user - a user variable to pass on to handler functions as the second argument. The wimp program can now be controlled by the vector, indexed by wimp_poll reason codes, of handler functions. .................................................................. wimp_report wimp_report(s) Display string s in a dialogue box and return 0 if no key or mouse button is clicked, 1 if the OK button is selected, and 2 if the CANCEL button is selected. ------------- END -------------------