NAME

Blatte::Builtins - Blatte-callable intrinsics

SYNOPSIS

  package MyPackage;

  use Blatte::Builtins;

  eval(...compiled Blatte program...);

DESCRIPTION

This module defines the standard Blatte-callable intrinsic functions.

A Blatte intrinsic is simply a Perl subroutine that (a) has been assigned (by reference) to a scalar variable (whose name begins with a letter), and (b) takes a hash reference as its first argument, in which named parameter values are passed.

INTRINSICS

{\acall FUNCNAME ARG ...}

Calls Perl function FUNCNAME with given arguments in array context. See also \scall.

{\add NUM ...}

Adds the given numbers.

{\ameth OBJ METHNAME ARG ...}

Calls the METHNAME method (i.e., member function) on the Perl object OBJ (a blessed reference) with given arguments in array context. See also \smeth.

{\append LIST ...}

Given one or more lists, combines their top-level elements into a single list.

{\apply FN ARG1 ARG2 ... ARGn}

Calls Blatte function FN on given arguments. If ARGn is a list, then it's interpreted as a list of arguments. (Use \funcall if you don't want this behavior.)

Any named parameters passed to \apply are passed along to FN.

{\aref LIST N}

Returns the Nth element of LIST. LIST is a Blatte list (which is really a Perl ARRAY reference). N is 0-based.

{\aset LIST N VAL}

Sets the Nth element of LIST to VAL.

{\concat STR1 STR2 ...}

Concatenates the given strings.

{\defined VAL}

True iff VAL is a defined value (in the Perl sense).

{\divide N1 N2 ...}

Divides its arguments. If there's only one, returns its multiplicative inverse.

{\flatten OBJ1 OBJ2 ...}

Renders each OBJ as a string and concatenates them.

{\foreach FN LIST}

Returns a list resulting from calling FN on each member of LIST.

{\funcall FN ARG1 ARG2 ...}

Calls Blatte function FN on the given arguments.

Any named parameters passed to \apply are passed along to FN.

{\hashdel HASH KEY}

Deletes from HASH the entry with the given key. HASH is a Blatte hash (which is a Perl hash references).

{\hashkeys HASH}

Returns the keys of HASH, a Blatte hash, in a Blatte list.

{\hashp OBJ}

True iff OBJ is a Blatte hash.

{\hashref HASH KEY}

Returns the element of HASH whose key is KEY.

{\hashset HASH KEY VALUE}

Sets the entry in HASH with key KEY to the given value.

{\hashtest HASH KEY}

True iff HASH contains an element with the given key.

{\int NUM}

Returns the integer portion of NUM.

{\lc STR}

Converts all letters in STR to lowercase.

{\lcfirst STR}

Converts the first letter of STR to lowercase.

{\length OBJ}

Returns of length of OBJ -- in elements, if OBJ is a list, or in characters, if OBJ is a string.

{\list ARG1 ARG2 ...}

Makes a Blatte list out of the given arguments.

{\listp OBJ}

True iff OBJ is a Blatte list.

{\match [\flags=cgimosx] STR REGEX}

True if STR contains a match for the Perl regular expression REGEX. The optional flag letters correspond to Perl's regular expression flags. If REGEX includes parenthesized subexpressions, the return value is a list of the matched strings, otherwise it's the list {1}.

Blatte implements this by performing a Perl regex match in array context. This means you can't use the g flag in scalar mode, which is a bit of a drag.

{\max N1 N2 ...}

Returns the numerically largest argument.

{\min N1 N2 ...}

Returns the numerically smallest argument.

{\mkhash [KEY1 VAL1 KEY2 VAL2 ...]}

Makes a new Blatte hash (a Perl HASH reference), initializing it with the optional key-value pairs.

{\multiply N1 N2 ...}

Multiplies its arguments.

{\not VAL}

Negates the truth value of VAL.

{\numeq N1 N2 ...}

True iff all arguments are numerically equal.

{\numge N1 N2 ...}

True iff N1 >= N2 >= ... (monotonically non-increasing).

{\numgt N1 N2 ...}

True if N1 > N2 > ... (monotonically decreasing).

{\numle N1 N2 ...}

True if N1 <= N2 <= ... (monotonically non-decreasing).

{\numlt N1 N2 ...}

True if N1 < N2 < ... (monotonically increasing).

{\pop LIST}

Removes the last element from LIST and return it.

{\push LIST OBJ1 OBJ2 ...}

Adds the given OBJs to the end of LIST.

{\random [N]}

Returns a random integer from 0 to N-1. If N is omitted, returns a random floating-point number in [0, 1).

{\require MODULE}

Does a Perl require.

{\scall FUNCNAME ARG ...}

Calls Perl function FUNCNAME with given arguments in scalar context. See also \acall.

{\shift LIST}

Removes the first element of LIST and returns it.

{\smeth OBJ METHNAME ARG ...}

Calls the METHNAME method (i.e., member function) on the Perl object OBJ (a blessed reference) with given arguments in scalar context. See also \ameth.

{\split [\flags=cgimosx] STR REGEX [LIMIT]}

Calls Perl's split function, splitting STR at occurrences of REGEX into a Blatte list, which is returned. If optional LIMIT is supplied, the result will have no more than that many elements. The optional \flags argument is the same as in \match.

{\sprintf FORMAT ARG ...}

Constructs a string out of the given sprintf format and arguments.

{\streq S1 S2 ...}

True if S1, S2, etc. are identical strings.

{\strge S1 S2 ...}

True iff S1 ge S2 ge ...

{\strgt S1 S2 ...}

True iff S1 gt S2 gt ...

{\strle S1 S2 ...}

True iff S1 le S2 le ...

{\strlt S1 S2 ...}

True iff S1 lt S2 lt ...

{\subseq LIST START [LEN]}

Extracts a sublist from LIST beginning at START, LEN elements long.

If START is negative, counts backward from the end of LIST.

If LEN is omitted, all elements to the end of LIST are included.

{\subst [\flags=egimosx] STR REGEX REPLACEMENT}

Replaces matches in STR for REGEX with REPLACEMENT. The optional flags, and the syntax of REGEX and REPLACEMENT, are as in Perl's s/// operator.

Unlike Perl, STR is not modified in place. Instead, the modified string is returned.

{\substr STR START [LEN]}

Extracts a substring from STR beginning at START, LEN characters long.

If START is negative, counts backward from the end of STR.

If LEN is omitted, all characters to the end of STR are included.

{\subtract N1 N2 ...}

Subtracts its second and subsequent arguments from its first one. If only one argument is given, returns its additive inverse.

{\uc STR}

Converts all letters in STR to uppercase.

{\ucfirst STR}

Converts the first letter in STR to uppercase.

{\unshift LIST OBJ1 OBJ2 ...}

Adds the given OBJs to the beginning of LIST.

{\use MODULE}

Does a Perl use.

AUTHOR

Bob Glickstein <bobg@zanshin.com>.

Visit the Blatte website, <http://www.blatte.org/>.

LICENSE

Copyright 2001 Bob Glickstein. All rights reserved.

Blatte is distributed under the terms of the GNU General Public License, version 2. See the file LICENSE that accompanies the Blatte distribution.

SEE ALSO

Blatte(3).