ARM Club 3

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

/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / perl / perl_1 / Perl5001 / Perl < prev next >

Wrap

Text File | 1992-09-11 | 54.4 KB | 1,925 lines

A P Oliver 11 Sept 92 This file is in the public domain. Please notify aoliver@acorn.co.uk of any errors or omissions. %accept Not implemented under RISC OS %alarm Not implemented under RISC OS %bind Not implemented under RISC OS %binmode Not implemented under RISC OS %chmod Not implemented under RISC OS %chown Not implemented under RISC OS %chroot Not implemented under RISC OS %connect Not implemented under RISC OS %crypt Not implemented under RISC OS %dump Not implemented under RISC OS %fcntl Not implemented under RISC OS %fileno Not implemented under RISC OS %flock Not implemented under RISC OS %fork Not implemented under RISC OS %getgrent Not implemented under RISC OS %setgrent Not implemented under RISC OS %endgrent Not implemented under RISC OS %getgrgid Not implemented under RISC OS %getgrnam Not implemented under RISC OS %gethostbyaddr Not implemented under RISC OS %gethostbyname Not implemented under RISC OS %gethostent Not implemented under RISC OS %getlogin Not implemented under RISC OS %getnetbyaddr Not implemented under RISC OS %getnetbyname Not implemented under RISC OS %getnetent Not implemented under RISC OS %getpeername Not implemented under RISC OS %getpgrp Not implemented under RISC OS %getppid Not implemented under RISC OS %getpriority Not implemented under RISC OS %getprotobyname Not implemented under RISC OS %getprotobynumber Not implemented under RISC OS %getprotoent Not implemented under RISC OS %getpwent Not implemented under RISC OS %getpwnam Not implemented under RISC OS %getpwuid Not implemented under RISC OS %getservbyname Not implemented under RISC OS %getservbyport Not implemented under RISC OS %getservent Not implemented under RISC OS %getsockname Not implemented under RISC OS %getsockopt Not implemented under RISC OS %ioctl Not implemented under RISC OS %semctl Not implemented under RISC OS %semget Not implemented under RISC OS %semop Not implemented under RISC OS %send Not implemented under RISC OS %setgrp Not implemented under RISC OS %setpriority Not implemented under RISC OS %setsockopt Not implemented under RISC OS %shmctl Not implemented under RISC OS %shmget Not implemented under RISC OS %shmread Not implemented under RISC OS %shmwrite Not implemented under RISC OS %shutdown Not implemented under RISC OS %socket Not implemented under RISC OS %socketpair Not implemented under RISC OS %symlink Not implemented under RISC OS %sysread Not implemented under RISC OS %syswrite Not implemented under RISC OS %times Not implemented under RISC OS %umask Not implemented under RISC OS %utime Not implemented under RISC OS %wait Not implemented under RISC OS %waitpid Not implemented under RISC OS %atan2(X,Y) returns arctangent X/Y in the range -pi to +pi %caller caller(EXPR) caller EXPR caller returns stack frame information as:- ($package, $filename, $line) = caller EXPR (if present) is number of stack frames to rise through %chdir chdir(EXPR) chdir EXPR chdir changes CSD to EXPR if possible. With no parameter changes to root of default drive. Returns 1 for succes or 0 for failure. %chop chop(LIST) chop(VARIABLE) chop VARIABLE chop chops the last character from a string and returns the character removed. With no variable chops $_. Given a list chops each item of the list and returns the (former) last character of the last item. Lvalues may be chopped:- $answer=chop(<STDIN>); %close close(FILEHANDLE) close FILEHANDLE closes a file or pipe and resets the line counter ($.) Closing a pipe waits for the pipe to exit and sets $?. FILEHANDLE may be an expression evaluating to a real filehandle name. %closedir closedir(DIRHANDLE) closedir DIRHANDLE closes a directory opened by opendir %cos cos(EXPR) cos EXPR returns cosine of EXPR (taken as radians) %dbmclose dbmclose(ASSOC_ARRAY) dbmclose ASSOC_ARRAY breaks the binding between a dbm file and an associative array %dbmopen dbmopen(ASSOC_ARRAY,DBNAME,MODE) binds ASSOC_ARRAY to dbm file called DBMNAME uses GNU dbm package and is believed to be rather slow. %defined defined(EXPR) defined EXPR EXPR is an lvalue thus print "$val\n" while defined($val = pop(@ary)); is perfectly valid; returns 1 if EXPR has a defined value, 0 otherwise packages may be checked for die "No XYZ" unless defined %_XYZ; %delete delete $ASSOC{KEY} deletes the specified value from the specified associative array. If the array is bound to a dbm file then deletes the corresponding entry. %die die(LIST) die LIST die i) Outside an eval prints the concatenated LIST to STDERR and exits with the current value of $! unless $! is 0 in which case ($? >> 8) is used to allow for `commands`. With no LIST uses "Died". If the LIST does not have a terminal newline the die function appends the script filename, line number, and input line number (if any), with a newline. ii) Within an eval as above except that the $@ variable contains the string that would have been output on STDERR, the eval is aborted and itself returns the undefined value. %do do BLOCK do SUBROUTINE(LIST) do EXPR i) The do BLOCK form returns the value of the last command in the enclosed sequence. When modified by a loop modifier, e.g. do { ... } unless CONDITION the BLOCK is executed at least once before the CONDITION is tested. ii) The do SUBROUTINE(LIST) is a subroutine invocation. The brackets are essential (even with an empty list) to disambiguate this from the do EXPR form. SUBROUTINE may be a simple scalar variable containing the name of a subroutine to call. The arguments are always evaluated in an array context. The alternative (and generally recommended) form is &SUBROUTINE(LIST) in this form the parentheses are optional if the list is empty in which case the @_ array is not passed to the subroutine. iii) The do EXPR form should be considered as an obsolescent version of the requires operator which should be preferred in new code. %each each(ASSOC_ARRAY) each ASSOC_ARRAY returns a two element list, ($key,$value), formed from the next value of the associative array. On exhausting the associative array returns a null array before starting again on the next call. The iterator can be reset only by reading all of the elements and the array must not be modified while iterating over it. The iterator is shared with the keys() and values() functions for any given associative array. Is not too clever in Perl v3.0 and should not be pushed too hard. %eof eof(FILEHANDLE) eof() eof Returns 1 if the next read on FILEHANDLE will return eof or if the file is closed. Uses ungetc so is useless in an interactive context. A bare eof refers to the last file read (and therefore distinguishes individual files within the @ARGV pseudo file. eof() on the other hand would return true only for the last file in the @ARGV stream. %eval eval(EXPR) eval EXPR eval The value returned by EXPR is parsed and executed as a perl program within the context of the current program. The eval text is a block so variables may be localised. Eval returns the undefined value if there were any syntax or runtime errors with the error string in $@. Otherwise a null string is guaranteed to be returned in $@ with the eval returning the value of the last expression evaluated. $_ will be evaluated if no parameter is given. The parameter itself does not need to contain a terminal semicolon. A simple perl shell is formed by while (<>) { eval; print $@; } %exec exec(LIST) exec LIST replaces the current perl program with the program specified in list. Therefore exec never normally returns. If it does it returns false and $! should be checked for an indication of what went wrong. Note that exec does not flush any buffers so the value of $| may need to be adjusted to avoid lost output. %exit exit(EXPR) exit EXPR Exits immediately with the specified value. Note that exit cannot be trapped, therefore die is better used within subroutines. %exp exp(EXPR) exp EXPR Returns e to the power of EXPR. %format format NAME = FORMLIST . If NAME is omitted it default to STDOUT FORMLIST is a sequence of lines. Lines beginning with '#' are treated as comments. Other lines are picture lines that print literally apart from picture fields as described below, or argument lines containing lists of names of variables whose values will be inserted into the previous picture line. Picture fields are: @<<<<<< left justified field @>>>> right justified field @||||||| centred field @###.## numeric field, point justified @* a multi-line field (should be alone on a line) Picture fields may start with ^ instead of @ in which case the variable is 'shifted' by the amount actually used and the remainder is available next time the variable is referenced. This allows block filling at the expense of destroying the original contents of the variable. The string '...' may be used for the final line of the block in which case '...' will appear on the output if the variable didn't fit. Blank lines may be supressed by putting a '~' anywhere in the line. Example: format = Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< $subject Index: @<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<< # ## $DESCRIPTION WILL BE DESTROYED # $index, $description Priority: @<<<<<<<<< Date: @<<<<< ^<<<<<<<<<<<<<<<<<< $priority, $date, $description From: @<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<< $from, $description Assigned to: @<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<< $programmer, $description ~ ^<<<<<<<<<<<<<<<... $description . %getc getc(FILEHANDLE) getc FILEHANDLE getc returns the next character from the file attached to the filehandle or STDIN if none. Returns a null string at eof. Very slow, probably only useful in interactive contexts. %gmtime gmtime(EXPR) gmtime EXPR gmtime returns a nine element list. Typically used as ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =gmtime(time); note that most of the arrays are zero based. if EXPR is omitted a£the value returned is as for gmtime(time). Under RISC OS 3 the value returned is as contained in Sys$Time and the $isdst element is zero, so the time may be BST or GMT. /* There must be a better way of getting at this than do { open(T,"status|"); local(@T)=<T>; grep(/BST/,@T); } which bit of the CMOS do we read? where are my RISC OS 3 PRMs?? */ %goto goto LABEL Although a function this does not return a value. The LABEL must be on a statement in the main body that is not inside a do {} construct. Present only for backward compatibility. %grep grep(EXPR,LIST) Evaluates EXPR for each element of LISt and returns a new list constructed of those elements of LIST for which EXPR evaluated true. Inside the EXPR, $_ contains the LIST element being considered. Modifying $_ is supported, but will have unpredictable results if LIST is not a named array. If evaluated in a scalar context returns the number of times that EXPR evaluated true. EXPR may, of course, be an arbitrarily long 'do {BLOCK}'. %hex hex(EXPR) hex EXPR returns the decimal value of EXPR treated as a hex string. Use oct for strings that might start 0 or 0x. Spintf can be used for the reverse, $number=hex("ffff12c0"), sprintf("%lx",$number) %index index(STR,SUBSTR,OFFSET) index(STR,SUBSTR) Returns the position of the first occurence of SUBSTR in STR. If OFFSET is specified, searching commences there. OFFSETs run from 0 unless $[ is altered. If SUBSTR is not found, $[-1 is returned, usually -1. %int int(EXPR) int EXPR Returns the integer portion of EXPR. %join join(EXPR,LIST) Returns a string formed by joining the separate strings of LIST into a single string with fields separated by the value of EXPR. %keys keys(ASSOC_ARRAY) keys ASSOC_ARRAY Returns a normal array containing all the keys of the associative array. With associative arrays bound to dbm files the resulting array could be very large, in which case the use of 'each' and handling the keys one at a time might be preferable. %kill kill EXPR Raises the signal represented by EXPR (which should evaluate to an integer or a signal name). Signals are:- ABRT 1 /* abort */ FPE 2 /* arithmetic exception */ ILL 3 /* illegal instruction */ INT 4 /* attention request from user */ SEGV 5 /* bad memory access */ TERM 6 /* termination request */ STAK 7 /* stack overflow*/ USR1 8 USR2 9 SERROR 10 Only SIGINT (Escape) is likely to be worth raising or trapping %length length(EXPR) length EXPR returns the length in characters of EXPR %local local(LIST) LIST must be composed of legal lvalues. The elements of LIST are then declared to be local to the enclosing block, subroutine, eval, or require. The LIST may be assigned if desired: a common idiom for naming parameters to sub-routines (and changing call-by-reference to call-by-value at the same time. local($min,$max) = @_ %localtime localtime(EXPR) similar to gmtime, but supposed to return a time corrected for the local time zone. Unlikely to be any different under RISC OS. %log log(EXPR) log EXPR returns log base e of EXPR %lstat lstat(FILEHANDLE) lstat FILEHANDLE lstat EXPR should return the same value as stat on a system without symbolic links. However, appears to be undefined in this port. %mkdir mkdir(FILENAME) mkdir FILENAME creates a directory with the specified name. Returns 1 for success, 0 for failure. If the return is 0, $! should be set. %oct oct(EXPR) oct EXPR returns the decimal value given by interpreting EXPR as an octal string. If EXPR starts "0x" it will be taken as hex instead. To handle a general numeric $val = oct($val) if $val =~ /^0/; The inverse can be achieved with sprintf("%lo", $number) %open open(FILEHANDLE,EXPR) open(FILEHANDLE) open FILEHANDLE opens the file whose filename is given by EXPR and places the filehandle in FILEHANDLE. If filename is not given it is assumed to be held in the scalar variable of the same name as FILEHANDLE. Filenames may be of the forms:- "<foo" read (default) "foo" (as above) ">foo" write ">>foo" append "+>foo" read/write "+<foo" (as above) "|foo" pipe to foo "foo|" pipe from foo "-" open STDIN ">-" open STDOUT [N.B. executables compiled with CLib support redirection and thus can be opened as pipes. Others can be co-erced into this behaviour if their name is prefixed with a '%'. E.g. open(LIB, "%LibFile Lib -l |") Forgetting this is also a common source of error with `commands` which also require redirection to work correctly.] open returns non-zero for success, the undefined value otherwise. Opening an already open file does an implicit close first, but does not reset the line counter ($.) as an explicit close would. Opening involving dup, ">&" etc, is not supported under RISC OS, neither is "-|" or "|-". %opendir opendir(DIRHANDLE,EXPR) opens the direcxotry specified by EXPR returns true if succesful directory and file handles have distinct name sapces. %ord ord(EXPR) ord EXPR returns the ASCII value of the first character of EXPR %pack pack(TEMPLATE,LIST) returns a string equivalent to a binary structure encoding the items of LIST as dicated by the TEMPLATE The TEMPLATE is a string containing one or more field specifiers of the form '<key><count>'. The field specifiers may be separated by whitespace which is ignored. The <key> may be any of a An ASCII string, null padded A An ASCII string, space padded b A bit string, lo-to-hi, vec() compatible B A bit string, hi-to-lo h A hex string, low nybble first H A hex string, high nybble first c A signed char C An unsigned char s A signed short S An unsigned short i A signed integer I An unsigned integer l A signed long L An unsigned long f A single-precision float d A double-precision float (default for perl) p A pointer to a string x A null byte X Back up a byte @ Null fill to absolute position u A uuencoded string T A 5-byte 2s complement integer The <count> is a simple repeat count except for a, A where it is a character length. A count of '*' means use the rest of the LIST. A missing count is treated as 1. POSSIBLE BUG. There is a suspicion that the 'hHbB' templates are broken. %pop pop(ARRAY) pop ARRAY removes and retruns the last item of the array. It has the same effect as $ARRAY($#ARRAY--) returns undef if the array was empty %print print(FILEHANDLE LIST) print(LIST) print FILEHANDLE LIST print LIST print prints the LIST - whcih may be a string or comma-separated list of strings, to the file specified by FILEHANDLE. The FILEHANDLE may be indirect via a simple scalar variable as normal. If the FILEHANDLE is omitted, uses the currently selected ouptut stream which will be STDOUT in the absence of specific select statements. If LIST is omitted uses $_. Remember that because print expect a LIST its operands are evaluated in an array context, thus print <T>; will not print a single line from T, but rather the entire contents of T. %printf printf(FILEHANDLE FORMAT, LIST) printf(FORMAT, LIST) printf FILEHANDLE FORMAT, LIST printf FORMAT, LIST equivalent to print FILEHANDLE sprintf(LIST); %push push(ARRAY, LIST) Treats array (the '@' is optional) as a stack and pushes LIST onto the end. Equivalent to foreach $value (LIST) { $ARRAY[++$#ARRAY] = $value; } %rand rand(EXPR) rand EXPR rand Returns an arbitrary real number between 0 and EXPR (exclusive). EXPR should be positive. EXPR is taken as 1 if omitted. %read read(FILEHANDLE,SCALAR,LENGTH,OFFSET) read(FILEHANDLE,SCALAR,LENGTH) attempts to read LENGTH bytes from FILEHANDLE into SCALAR. Returns number of bytes actually read, 0 on eof, undef on failure. If OFFSET is used it specifies where, in SCALAR, to start placing the bytes read. Do not intersperse with calls to sysread() Read may be buffered by the system %readdir readdir(DIRHANDLE) readdir DIRHANDLE In array context returns all the (remaining) entries in a directory opened using opendir. In a scalar context returns the next entry only. If there are no more gives an empty list (array) or undef (scalar). %rename rename(OLDNAME, NEWNAME) renames the file in question. Returns 1 for success. Unlike Unix implementations, if NEWNAME already exists it is not destroyed. Unfortunately, rename still returns 1 in this instance (as it does if OLDNAME doesn't exist!). %require require(EXPR) require EXPR require includes and executes any Perl code found in the file whose name is given by EXPR. Require will check the @INC array to ensure that the code has not already been included and will update the @INC array if necessary. require will also use the search path held in @INC to find the file if necessary. %reset reset(EXPR) reset EXPR reset reset EXPR treats EXPR as a list of characters and resets all variables (including arrays) beginning with one of those letters. Thus reset 'a-z'; resets all variables whose names begin with a lowercase letter. Note that reset 'A-Z' would kill the ARGV, ENV, INC, and SIG arrays. Resetting an array bound to a dbm file merely flushes the cache. For single variables - particularly arrays - undef(ARRAY) is more efficient. Reset with no parameter resets ?? searches so that they match again. The scope of a either type of reset is confined to the current package. Reset always returns 1. %return return LIST returns from a subroutine with the value specified. Illegal outside subroutines. Allowing an implicit return of the last expression evaluated is more efficient. %reverse reverse(LIST) reverse LIST In an array context returns an array containing the elements of LIST in the opposite order. It is implemented fairly efficiently. It can also invert associative arrays %VNE = reverse %ENV In a scalar context returns a string consisting of the first element of LIST in reverse order. %rewinddir rewinddir(DIRHANDLE) rewinddir DIRHANDLE causes the next use of readdir() on the DIRHANDLE to return the first (scalar context) or all (array context) entries in the directory specified once again. %rindex rindex(STR,SUBSET,OFFSET) rindex(STR,SUBSET) works a index does except that it returns the position of the last occurence of of SUBSTR in STR. OFFSET, if specified, is the rightmost position that may be returned. %rmdir rmdir(FILENAME) rmdir FILENAME Deletes the directory specified by FILENAME if it exists and is empty when it returns 1. Otherwise it returns 0 with an error code in $!. %s s/PATTERN/REPLACEMENT/[g][i][e][o] searches a string for the pattern, if found replaces that pattern with the replacement text, and returns the number of replacements made. Only the first occurence is replaced unless the g (global) modifiers is used. The i modifier causes case-insensitive behaviour. The e modifier means that REPLACEMENT will be treated as an expression rather than as a string. Additional 'e's may be specified to cause additional evaluation of the resulting string. The pattern is also subject to variable interpolation as strings usually are. The o modifier may be used to indicate once-only evaluation of the string where the interpolated variables will not change over the life time of the substitution and may be a valuable optimization in loops. The o modifier has no effect if there are no variables in the pattern. Any non-alpahanumeric may be used instead of the '/'s. In particular single quotes prevent interpretation of the replacement text (this is, however, over-ridden by the e modifier). If backquotes are used, the replacement string is a command whose result will be used as the replacement text. If no other string is specified using the =~ or !~ operators, then $_ is searched and modified. The string specified must be an lvalue. Forgetting that the second subpattern is specified as \2 within the pattern but $2 within the replacement is a common error. (As is thinking that \0 is the first sub-pattern because of contact with brain-dead editors such as !Edit or !SrcEdit). \0 is a null, \1 is the first subpattern. %scalar scalar(EXPR) A pseudo function forcing EXPR to be evaluated in a scalar context rather than in an array context. Useful, therefore, when EXPR is to be used as an element of a list. Not using scalar in operations such as local($nextline) = scalar(<STDIN>); is a common error. The argument of local is a list. Assignment to a list is an array operation. Thus <STDIN> would be in an array context resulting in a read to eof rather than eol were it not for the use of scalar. %seek seek(FILEHANDLE,POSITION,WHENCE) positions the file pointer for FILEHANDLE as specified. WHENCE specifies what POSITION should be taken as relative to: 0 for beginning, 1 for current position, 2 for end of file. POSITION is thus >=0 if WHENCE is 0, <=0 if WHENCE is 2, and positive or negative for a WHENCE of 1. seek returns 1 for success and 0 for failure. seek is useful for resetting eof on dynamic files, e.g. for (;;) { while (<FILE>) { print; } sleep 5; seek(FILE,0,1) # Seek to the current poistion in the file # thus clearing the eof error } which would print out lines as they were added *IF* RISC OS allowed writing to files open for reading elsewhere. Boring, or what. %seekdir seekdir(DIRHANDLE,POS) Sets the current position for the readdir() routine. On some systems POS must be a value returned by telldir(), but under RISC OS integers 0 .. n appear to be fine. %select select(FILEHANDLE) select select(RBITS,WBITS,EBITS,TIMEOUT) The first form returns the currently selected filehandle and sets it if FILEHANDLE is supplied. The currently selected filehandle is significant to 'write' or 'print' when used without a filehandle. Special variables related to output also refer to the current filehandle. Subroutines should ideally exit with the selected filehandle unaltered. Since FILEHANDLE may be an expression evaluating to a filehandle it is not difficult to do a save and restore. Which leads to one of Larrys' favourite bits of bizarre Perl: setting stderr unbuffered while leaving the current filehandle unaltered. select((select(STDERR), $| = 1)[$[]) The second form of select (which has nothing to do with the first) is not implemented under RISC OS %shift shift(ARRAY) shift ARRAY shift returns the first element of an array and shortens the array by one element from the left. Without arguments operates on @ARGV in the main program and @_ in subroutines. If the array has no elements it returns the undefined value. %sin sin(EXPR) sin EXPR returns the sine of EXPR (taken as radians). %sleep sleep(EXPR) sleep EXPR sleep suspends the script for EXPR seconds. If EXPR is omitted sleeps forever! On some systems sleep may be interrupted by a signal and suitable handler, but under RISC OS a SIGINT appears to bypass the handler if the script is sleeping, so the script just terminates. syscall() and suitable swis would need to be used instead. returns the number of seconds actually slept. This may be a lot longer than the number asked for if RISC OS has its attention distracted in the meantime (e.g. by a non-wimp task). %sort sort(SUBROUTINE LIST) sort(LIST) sort SUBROUTINE LIST sort LIST sorts the list and returns a sorted array. If SUBROUTINE is omitted soes a string comparison sort. SUBROUTINE, if specified, is the name of a subroutine that will return -1, 0, or 1, when presented with two elements. For efficiency reasons, SUBROUTINE is not called in the normal way. It may not be recursive, @_ is not used, the two parameters are passed by reference as $a and $b. If SUBROUTINE is a simple scalar variable this should evaluate to the name of the actual subroutine to use. sub numerically { $a <=> $b; } @sortednumerically = sort numerically 53,29,11,32,7; note that sort reverse @a is equivalent to reverse sort @a because of the way that lists work. %splice splice(ARRAY,OFFSET,LENGTH,LIST) splice(ARRAY,OFFSET,LENGTH) splice(ARRAY,OFFSET) removes the elements of ARRAY designated by OFFSET and LENGTH and replaces them with LIST if LIST is provided. OFFSET may be negative in which case it is reckoned from rigyt to left. Returns the elements removed. The array shrinks or grows as needed. If LENGTH is omitted everything from OFFSET onwards is removed. Note the following equivalencies: push(@a, $x, $y) splice(@a, $#a+1, 0, $x, $y) pop(@a) splice(@a, -1) shift(@a) splice(@a, 0, 1) unshift(@a, $x, $y) splice(@a, 0, 0, $x, $y) $a[$x]=$y splice(@a, $x, 1, $y) %split split(/PATTERN/,EXPR,LIMIT) split(/PATTERN/,EXPR) split(/PATTERN/) split splits the string specified by EXPR into an array of strings which it returns. If EXPR is omitted, split uses $_. The pattern matches the delimiters separating the sub-strings. The delimiters are not returned. In a scalar context splits into @_ and returns the number of substrings. In an array context the split can be forced into @_ by using ?? as the pattern delimiters (but the array value is still returned). If PATTERN is elided the split is on whitespace: /[ \t\n]+/ PATTERN may match more than one character. If the match fails the original string is returned. If a LIMIT is specified the split is into no more than LIMIT fileds. If LIMIT is unspecified any trailing null fileds are stripped. If PATTERN can match the null string then the split is into individual characters at that point. join(':', split(/ */,'hi there')); returns "h:i:t:h:e:r:e". Notice that the space - which matched as a delimiter - is not returned as is the norm for delimiters. LIMIT is widely used for partial splitting, as in ($command,$flags,$filelist)=split(/[ \t]+/,$_,3); In the case of assignment to a list if a LIMIT is not given a limit of one greater than the number of elements in the list is actually used. Splitting into more fields than are needed should be avoided for efficiency. If the delimiters are required, then parentheses should be used in the pattern round those delimiters wanted split(/(-)|,/, '1-10,20'); produces (1,'-',10,20) The /PATTERN/ argument may be replaced with a variable as /$pattern/, in this case the o modifier may be used for invariant patterns /$pattern/o A literal space replacing the whole of PATTERN splits on whitespace but ignores leading whitespace. These are all subtley different:- split or split(/[ \t]+/) splits on whitespace, leading space gives null fields split(' ') splits on whitespace, no leading null fields split(/ /) split on literal single space, may give nulls %sprintf sprintf(FORMAT,LIST) returns a string which is created from LIST using the supplied FORMAT. The FORMAT is a string containing fileds of the approximate form %m.nx, one per element of the list to be used. The m is the minimum field length, -ve for left justified, padding is done with zeroes for numbers and spaces for non-numerics. The n is typically a maximum length or a precision for exponential formats. The x is one of:- s string c character d decimal number ld long decimal number u unsigned decimal number lu long unsigned decimal number x hexadecimal number lx long hexadecimal number o octal number lo long octak number e exponential fp f fixed point fp g compact fp %sqrt sqrt(EXPR) sqrt EXPR returns the square root of EXPR. Returns the largets possible -ve number if asked for the square root of a negative quantity. %srand srand(EXPR) srand EXPR sets the random number seed with the value of EXPR. If EXPR is omitted does srand(time) which may be fairly predictable. %stat stat(FILEHANDLE) stat FILEHANDLE stat(EXPR) returns an eight element array ($found,$filetype,$loadaddress,$execaddress,$length,$attributes,$ts1,$ts2) =stat($file); $found is 0 for not found, 1 for a file, and 2 for a directory $ts1 is a RISC OS 5-byte time (see the P key to unpack), i.e. centiseconds from 00:00:00.00 1/1/1900 $ts2 is Unix format, i.e.seconds from 00:00:00 1/1/1970 %study study(SCALAR) study SCALAR study builds an index for SCALAR ($_ if unspecified). This can result in speed enhancement if many pattern matches are to be done against the string. It carries the overhead of building the index so may or may not be faster overall. Short constant string searches benefit most, but not if they are anchored. Only one study may be active at a time. A new study forgets the older one. For strings not known till runtime, search loops can be built as strings and then 'eval'ed. Together with setting $/ to input entire files as single records (given the memory ;-) this can be extremely fast. %substr substr(EXPR,OFFSET,LENGTH) substr(EXPR,OFFSET) extracts a substring from EXPR and returns it. OFFSET runs from $[, normally 0 If OFFSET is negative it is a character length from the right of the string If LENGTH is omitted everything to the end of the string is returned. substr() can be an lvalue if EXPR is also an lvalue. In this case the string may grow or shrink if if LENGTH is not the same as the length of the item assigned. %syscall syscall(LIST) syscall LIST Normally called with LIST containing ($swi_name_or_number, $r0, ..., %$r9) the swi specified is called with the remaining values placed in the registers. Only as many registers as are needed need be specified. If $rn is a number it is used directly, if it is a string a pointer to the string is passed. Care should be taken because of Perl's tendency to convert numbers to strings and vice versa. Use $rn+0 to ensure a numeric interpretation and $rn.'' to ensure a string interpretation in cases of doubt. Obviously if values are returned in strings the caller must ensure that the string is large enough to accept the return value. Buffers may be created as $buffer='\0' x 512; # A 512 byte null filled buffer or $buffer=pack("x512",'') # Another one. Generally with strings used for return values, call-by-reference is wanted. NOT call by value, so be careful with assignments, particularly in subroutines. Actual pointers can be obtained by using $pointer=unpack("I",pack("p",$buffer)) though the use to which such 'pointers' are put is at the users's risk! Pointer comparison is known to be ok, and some pointer arithemetic, eg $end_of_buffer=unpack("I",pack("p",$buffer))+length($buffer); for those awkward little swis that want start and end rather than start and length. Syscall returns either a null string (in the case of errors) in which instance $! may be diagnostic or a packed structure containing ARM registers R0 to R9. (@reg[0..8],$flags)=unpack('I10', syscall("Wimp_Initialise", @reg)); %system system(LIST) system LIST attempts to have the sytem execute LIST. Returns unlike exec. The value returned should be zero for success and -ve for failure but this isnot completely consistent under RISC OS. $! will hold the error, if any. %tell tell(FILEHANDLE) tell FILEHANDLE tell Returns the position of the file pointer (in bytes). FILEHANDLE may be an expression evaluating to a file handle. If FILEHANDLE is omitted, tell targets the last file read. tell() has no meaning for devices or pipes. %telldir telldir(DIRHANDLE) telldir DIRHANDLE Returns the current position of readdir() on DIRHANDLE. May be used as a parameter to seekdir() %time time This function returns the number of seconds since 1/1/1970. %tr tr/SEARCHLIST/REPLACEMENTLIST/[c][d][s] y/SEARCHLIST/REPLACEMENTLIST/[c][d][s] SEARCHLIST and REPLACEMENTLIST are placed in a one-to-one correspondence. If REPLACEMENTLIST is shorter than SEARCHLIST then the last character of REPLACEMENTLIST is repeated as necessary (except with the d option). If REPLACEMENTLIST is null a copy of SEARCHLIST is used (except with the d option). The function replaces all characters in SEARCHLIST with their corresponding character from REPLACEMENTLIST. The returned value is the number of replacements made. The c option complements SEARCHLIST: in effect the SEARCHLIST given is removed from the range \001-\377 and the result used as SEARCHLIST. The d option deletes all characters within SEARCHLIST that are not found in REPLACEMENTLIST. The s option causes any substitutions that would result in multiple identical REPLACEMENTLIST characters being output to be replaced by a single occurence of that character. y is a synonym for tr. If no string is specified via =~ or !~ the $_ string is used. The string specified must be an lvalue. %truncate truncate(FILEHANDLE,LENGTH) truncate(EXPR,LENGTH) This function does not appear to be implemented in the current port. %undef undef(EXPR) undef EXPR undef Makes the value of EXPR (which must be an lvalue) undefined. Subroutine names should be prefixed with '&'. Storage is recovered, so undeffing large arrays when they are finished with can make smaller tasks. The function always returns the undef value. The principal use of undef with no argument is as an error return from subroutines. %unlink unlink(LIST) unlink LIST Equivalent to *remove - i.e. tries to delete the files named, but does not provoke an error if it cannot. unlink() will not delete directories (unless Perl is started with the -U flag). Use rmdir() instead. %unpack unpack(TEMPLATE,EXPR) Almost the reverse of pack(), except that some templates make no sense when packing, others make no sense when unpacking. EXPR is a string representing a structure and unpack unpacks this into an array according to the pattern given in TEMPLATE. Keys recognized in TEMPLATE are a An ASCII string, unstripped A An ASCII string, trailing spaces and nulls stripped b A bit string, lo-to-hi, vec() compatible B A bit string, hi-to-lo h A hex string, low nybble first H A hex string, high nybble first c A signed char C An unsigned char s A signed short S An unsigned short i A signed integer I An unsigned integer l A signed long L An unsigned long f A single-precision float d A double-precision float (default for perl arithmetic) p A pointer to a string x Skip forward a byte X Back up a byte @ Go to absolute position in string for next field, @* is end of string u A string to uudecode T A 5-byte 2s complement integer P A pointer to a string whose length is given in the count. P is not recognized in pack() as there is no way to ensure the exact length of the string. Reads exactly count bytes from the string pointed to, regardless of what these bytes are (p1 would stop at a \0). The <count> is a simple repeat count except for a, A where it is a character length. A count of '*' means use the rest of the LIST. A missing count is treated as 1. Prefixing a TEMPLATE field with %<num> means that you want a <num>-bit checksum of the item rather than the item itself. POSSIBLE BUG: There is a suspicion that the 'hHbB' templates are broken %unshift unshift(ARRAY,LIST) Does the opposite of a shift(). It attaches LIST to the front of array ARRAY and adjusts the length of ARRAY as needed. %values values(ASSOC_ARRAY) values ASSOC_ARRAY returns a normal array consisting of all the valuesin the named associative array. Using values on an array bound to a dbm file can produce huge arrays. %vec vec(EXPR,OFFSET,BITS) treats the string which EXPR evaluates to as an array of bits (the conversion is as unsigned integers). The OFFSET is the number of *elements* to skip over (not the number of bits), BITS is the number of bits in each element. BITS must be one of 1,2,4,8,16,or 32. The ordering is such that vec($string,0,1) is the lowest bit of the first byte of $string. (IE. the ordering is 32107654ba98fedc where 0-f represent 0-15) A true bit vector (i.e. with BITS=1) can be translated to/from strings of 1s and 0s by using a b* template with pack() and unpack(). vec() may be used as an lvalue to set specific bits Note that EXPR is a scalar and will be irredeemably treated as the printed representation of EXPR. Thus vec(0xff,... will return a bit string related to 0x323535 - i.e. the character string '255'. This limits its usefulness somewhat. %wantarray wantarray This pseudo function returns true if the current context is looking for an array and false if it is looking for a scalar. Typical use return wantarray ? () : undef; %warn warn(LIST) warn LIST Similar to die() but doesn't exit. E.g. warn "Debugging enabled" if $debug %write write(FILEHANDLE) write(EXPR) write writes a formatted record to the specified file using the format established for that file. By default that is the format with the same name as the FILEHANDLE, but the format for the current filehandle may be explicitly set with $~. The default top-of-page format has the same name as the format with _TOP appended, but may be set using $^ The number of lines left on a page is held in $- which can be set to 0 to force a new page for the next write() which will be done automatically if there is insufficient room for the next record. %$_ $_ Default input, parameter, and pattern %$. $. Current input line on last filehandle read %$/ $/ Input record separator, newline by default %$, $, Output field separator for print operator %$" $" Separator for array elements interpolated in strings %$\ $\ Output record separator for print operator %$# $# Output format for numbers, default "%.20g" %$* $* If set to 0 (default) assume in pattern matching that strings contain only a single line. If set to 1, strings will be matched as if they might contain multiple lines. %$? $? Status return from last `command`, pipe, or system operator. %$] $] Perl version string %$[ $[ Index of first elements in arrays. Default 0. %$; $; Subscript separator for multi-dimensional array emulation. Default \034 %$! $! As a number evaluates to an error no. As a string evaluates as the last error string. I.e. set to the value of _kernel_last_oserror whenever an OS call returns an error. %$@ $@ Perl error message from last eval, require, etc %$: $: The set of characters on which strings may be broken in '^' fields of formats. Default ' \n-' %$0 $0 The name of the file containing the script being executed. %$$ $$ Not implemented under RISC OS %$< $< The pathname of the CSD when Perl started Note, under Unix this would the real uid %$> $> The pathname of the current CSD Note, under Unix this would be the effective uid %$( $( Not implemented under RISC OS %$) $) Not implemented under RISC OS %$^T $^T The time (in time() format) when the script began execution %$% $% Curent page number on currently selected output %$= $= Page length of currently selected ouput. Default 60 %$- $- Number of lines left on current page %$~ $~ The name of the report format for the currently selected output channel %$^ $^ The name of the top of page format on the current output channel %$| $| If set non-zero forces flushing of buffers after every write or print on the selected output channel. Default is 0. %$ARGV $ARGV Current file name when reading from <> %$& $& String matched by last pattern match %$` $` String preceding match in last pattern %$' $' String following match in last pattern %$+ $+ The portion of the string matched by the last bracket in the last pattern %@ARGV @ARGV array containing command line arguments %@INC @INC array containg places to search for scripts %@_ @_ Parameter array in subroutines. Used by split() in scalar contexts. %ENV ENV Contains the current environment. May be written to set variables, but is read at script initialisation only - i.e. variables set/altered by other tasks after the script started will not be reflected in %ENV. %INC INC List of files that have been 'require'-d. %SIG SIG Array containing signal handlers. A signal handler may be installed by putting the name of a subroutine in the appropriate element. Help for kill() has a list of signals. The tokens 'IGNORE' and 'DEFAULT' are also valid in this array. %FILE __FILE__ Token containing current filename. Returns (eval) inside evals. May not be interpolated in strings. %LINE __LINE__ Line number in current script. May not be interpolated in strings. Returns null string in evals. %END __END__ Everything after this token is ignored by the parser but may be accessed via filehandle <DATA>. %<< <<STRING 'here-is' text quoting. All following lines up to a line starting and containing STRING alone are effectively inserted at the identified place. If quotes are used in the first instance the following lines are treated accordingly. >>EOF >>"EOF" The lines are used after string interpolation >>'EOF' The lines are used literally >>`EOF` The lines are executed as commands %re Regular Expressions 1. Regular expressions may be separated by '|' to express alternatives. The '|' has a lower precedence than anything else. 2. Regular expressions surrounded by () match whatever the enclosed expression matches. 3. Assertions are:- ^ start of string (line if $* set) $ end of string (line if $* set) \b word boundary (except inside '[]' where it is a backspace character) \B not a word boundary assertions match on the 'gaps' between characters 4. Quantified atoms are atoms followed by a quantifier. Quantifiers are:- {n,m} must occur at least n and not more than m times {n,} must occur at least n times {n} must occur exactly n times * 0 or more times - {0,} + 1 or more times - {1,} ? 0 or 1 times only - {0,1} 5. Atoms are:- \0 matches null \nn or \nnn matches the ASCII character whose octal code is nn or nnn. \xnn matches the ASCII character whose code in hexadecimal is nn. \cx where x is a single character matches the corresponding control character, thus \cI and \x09 are equivalent atoms. \\ matches \ \b matches backspace, but only if inside a character class '[]'. A list of characters in square brackets, [], matches any character in the brackets. If the first character is '^' the match is for any character not in the brackets. If ']' is needed as a character it must be the first character (or second after '^'). If '^' is needed as a character it must not be first. Ranges may be used by inserting '-' between two characters. '\-' may be used to prevent this interpretation of hyphen. . matches any character except \n \n newline \r carriage return \t tab \f formfeed \d a digit [0-9] \D a non-digit [^0-9] \w an alphanumeric [0-9A-Z_a-z] \W a non-alphanumeric \s a whitespace [ \t\n\r\f] \S a non-whitespace Any character not previously mentioned matches itself. Any character preceded by a backslash and not mentioned above matches itself. \1, \2, \3, .. are backreferences and match whatever the 1st, 2nd, 3rd, parenthesised expression matched. %op Operators, from lowest to highest precedence 1. list operators, nonassociative. 2. , left assoc., expression separator as C e.g. <EXPR1>,<EXPR2> has the value <EXPR2> 3. = right assoc., assignment There are a host of assignment operators, += -= *= /= %= |= &= ^= >>= <<= **= .= x= 4. ?: right assoc., conditional operator as C <CONDITION> ? <EXPR_T> : <EXPR_F> has value <EXPR_T> if <CONDITION> is true (non-zero, non-null, & defined) and <EXPR_F> otherwise. 5. .. nonassoc., range operator. In array context returns an array of values from its left value to its right value. @digits = (0..9) @alphabet = ('A'..'Z') In scalar context returns a boolean value. This is false as long as the left value is false, then true until the right value becomes true after which it returns false again. While returning false the right value is not evaluated and contrariwise while returning true. The 'true' value returned is actually a sequence number from '1' up to 'nnE0' (the E0 does not affect the numeric value, but makes the last item easier to check for). If either (or both values) are static numbers an implicit comparison with $. (the current input line number) is done. 6. || left assoc., logical or 7. && left assoc., logical and 8. | left assoc., bitwise or ^ left assoc., bitwise eor 9. & left assoc., bitwise and 10. == nonassoc., numeric equality != nonassoc., numeric inequality <=> nonassoc., numeric comparison, returns -1, 0, 1 eq nonassoc., string equality ne nonassoc., string inequality cmp nonassoc., string comparison 11. < nonassoc., numeric less than > nonassoc., numeric greater than <= nonassoc., >= nonassoc., lt nonassoc., string less than gt nonassoc., string greater than le nonassoc., ge nonassoc., 12. named unary operators nonassoc., 13. file test operators nonassoc., -Z EXPR EXPR is a filename or filehandle. $_ is used if EXPR is omitted (except -t which uses STDIN). If _ is used as the EXPR then the information from the last test is used (which saves another statand is much more efficient). -r/-R file is readable/publicly readable -w/-W file is writeable/publicly writeable -e/-z/-s file exists/has zero/has non-zero size -f/-d file is a plain file/directory -t filehandle is a terminal -T/-B filename (not handle) is text/binary this is based on an opinion formed by examining the first few blocks. both return true on null files. Both return false on directories. -A file time stamp test. Returns difference in age between file and time program started as given by $^T and measured in days. Presumably can be negative for files created after the program started. Note that for directories this will use the actual 'creation on disc' date as returned by INFO and not the date displayed by Filer. -L file is locked 14. << left assoc., bitwise shift left >> left assoc., bitwise shift right 15. + left assoc., addition - left assoc., subtraction . left assoc., string concatenation 16. * left assoc., multiplication / left assoc., f.pt. division % left assoc., modulo division x left assoc., string reproduction 17. =~ left assoc., pattern binding operator !~ left assoc., negated pattern binding 18. ! right assoc., negation operator - right assoc., unary minus ~ right assoc., bitwise NOT 19. ** right assoc., exponentiation operator 20. ++ nonassoc., string or numeric autoincrement -- nonassoc., numeric autodecrement 21. '(' left assoc., functions and parenthesis %glob File globbing is supported if Glob is found on the Run$Path. The RISC OS standard is followed * any number of characters # any single character %mode $Mode The current screen mode. Can be assigned to. %Rows $Rows Screen rows currently available %Cols $Cols Screen columns currently available %osrdch &osrdch() returns a single character string from OS_ReadC %oswrch &oswrch(INT) writes the character whos ASCII code is INT using OS_WriteC. Returns 1 for success, undef for failure. %osrdstr &osrdstr(LEN,LO,HI) reads a string using OS_ReadLine. Uses a buffer of length LEN characters to hold it internally. LO and HI are boundaries on the codes accepted, default 32 and 255. Returns the string. %oswrstr &oswrstr(STR) writes STR to the screen. STR may contain control characters which will be interpreted as VDU codes, e.g. &oswrstr("\026\000") changes to mode 0. Returns 1 for success, undef for failure. %fx &fx(NUM,X,Y) peforms OS_Byte call NUM with the given X and Y values. Returns an integer whose bottom byte is R1, second byte R2, third byte 0 or 1 as carry was clear or set, and fourth byte 0.