Backtalk Script Language
Reference Manual

Version 1.1.9

© 1996-2001: Jan Wolter, Steve Weiss

Description

The Backtalk script language is used internally by Backtalk to generate html web pages for conferencing. Conference participants should not need to know anything about the script language, since it is used entirely to configure the system.

It is a RPN, stack-based language, quite similar to Postscript (Postscript is a trademark of Adobe Systems incorporated). It is actually a fully-capable and reasonably-efficient programming language, with special commands built in for accessing conferences. It is oriented toward generating text in a batch mode.

Readers of this manual may find the Backtalk Glossary helpful. This describes many of the functions and terminology associated with Backtalk.

Contents

Data Types

Backtalk functions operate on the following kinds of data types:

integer
Backtalk integer objects can have the same range of values as your compiler's int data type. Normally this range is between -2,147,483,648 and 2,147,483,647.

time
Backtalk time objects can represent times in whatever range your version of Unix supports. Usually this range is between Jan 1, 1970 and Jan 18, 2038, but if your Unix can handle dates after 2038, Backtalk will support them too.

mark
Mark objects normally have no value. They are pushed on the stack to mark locations on the stack.

string
String objects may contain an arbitrarily long sequence of ASCII characters.

literal
Literal objects are variable or function names. They can be up to 32 characters long, and may contain letters, digits and underscores, but may not begin with a digit. Literal names are case sensitive, so Count and count are two different literals.

array
Array objects can contain an arbitrary number of other objects. The objects in an array do not all need to be of the same type, and the size of the array will increase or decrease as needed.

regular expressions
Regular expression objects are used for doing fast efficient searches. They are similar to Perl regular expressions and can be used in similar ways.

procedure
Procedures are variations of arrays that contain executable code.

Execution

Backtalk is a stack-based language. Most operations take their operand from the stack and push the results back on the stack. It isn't as pure about this as Postscript is though. Many of the conference-related operators operate on special built-in variables. instead of, or in addition to, the stack.

The program source is read from a file. Source file names must end with a .bt suffix. There is no limit on the size of the file or the lengths of the lines. Comments begin with a percent sign (%), and extend to the end of the line.

There is one special script called config.bt which is used to configure Backtalk. It is automatically included as a header in all other scripts.

The file contains a sequence of tokens, which are executed in order. Tokens may be of several types:

integers
Integer constants are written as usual (i.e., 1023 or 42.) When executed, the value of the integer is pushed on the operand stack.

strings
Strings constants are enclosed in matching parentheses ("(" and ")"). Newlines may appear in strings, and will be stored as newline characters. Alternately, newlines can be typed as "\n". Thus both of the following are equivalent ways to write the same string:
   (One\nTwo\n)

   (One
   Two
   )
There can be parentheses inside the string, but if they do not balance, they need to be preceded by backslashes. When executed, a copy of the string is pushed on the operand stack.

procedures
Procedures are enclosed in matching curly-braces ("{" and "}"). Procedures may contain any sequence of tokens, including sub-procedures, separated by white space. When executed, a copy of the procedure is pushed on the stack.

variables
Names of variables are entered without adornment, or with a preceeding slash ("/") character. If the name of a variable is prefixed with a slash ("/"), then the name of the variable is pushed on the stack when it is executed (this is called a "literal"). If there is no slash, and the variable is defined, then it's value is pushed on the stack. If it is not defined, an error occurs.

constants
Constants have the same syntax as variables, but are replaced with their values during compilation, so they will have entirely disappeared from the program by the time it is run. Thus they act similarly to #define variables in the C programming language. There are some predefined system constants that can only be redefined by the config.bt script. Unlike variables and functions, constants are lexically scoped, so if a constant is defined, it can be used anywhere after that point in the file.

regular expressions
Regular expressions are written enclosed in double-angle brackets, like "<<[a-z]+@[a-z\.]+\.com>>". The full syntax for regular expressions is described below. When executed, they are just pushed on the stack.

functions
Function names obey the same syntax as variables. When executed they pop arguments off the stack and push results on. Some may have side effects, such as defining variables.

When execution terminates, the contents of the operand stack (from bottom up) are automatically printed as if the last command in the script had been a print command. Thus scripts often use the stack as an output buffer. Printing may also be forced earlier with the print command.

In the list of functions below, the keywords before the function indicate the objects that the function removes from the stack when executed. It is an error if they are not present or of the wrong types. The keywords after the function name indicate the results pushed on the stack after execution. A "-" indicates nothing. A "|" indicates the bottom of the stack.

Operators

Operand Stack Operators

The following built-in functions manipulate the operand stack. Most are identical to the corresponding postscript commands.

pop
any pop -

Discard the top element from the stack.

exch
any1 any2 exch any2 any1

Exchange top two elements of the stack.

dup
any dup any any

Duplicate the top element of the stack.

copy
any1...anyn n copy any1...anyn any1...anyn

Duplicate the top n elements of the stack. Doing "1 copy" would be identical to "dup".

index
anyn...any0 n index anyn...any0 anyn

Duplicate an arbitrary element off the stack. Note that the indexing here is zero-based. Doing "0 index" would be identical to "dup".

roll
anyn-1...any0 n j roll anyj-1 mod n...any0 anyn-1...anyj mod n

Roll n elements upward j times. If j is negative, it rolls downward instead. Doing ``2 1 roll'' would be identical to "exch". Doing ``k -1 roll'' brings the kth element of the stack to the top.

select
anyn-1 ... any0 n i select anyi

Of n top elements on the stack, discard all but the i-th one.

mark
- mark mark

This pushes a mark onto the stack. Marks are distinct from all other types of stack elements. The [ command is identical to mark.

clear
| any1...anyn clear |

Discard all elements from the stack.

cleartomark
mark any1...anyn cleartomark -

This deletes all stack elements on top of the topmost mark. It is an error if there is no mark on the stack.

count
| any1...anyn count | any1...anyn n

Push the count of elements that were on the stack before the execution.

counttomark
mark any1...anyn count mark any1...anyn n

This counts the number of stack elements on top of the topmost mark. It is an error if there is no mark on the stack.

Dictionary Operators

Backtalk supports a system dictionary, a constant dictionary, a stack of user dictionaries, and an environment dictionary. This is a more complex than the arrangement in Postscript, but allows us to do more preprocessing at compilation time.
  1. System Dictionary - The system dictionary contains all of Backtalk's built-in functions, variables and constants. It is not possible to add definitions to it, but you can change some of the variables. Note that some system dictionary variables are "protected" so that, like constants, you can't change their values, although their values may change by themselves during a run, so they aren't constants.
  2. Constant Dictionary - All constants defined by the user are stored in the constant dictionary. New constants can be added without limit, but, of course, their values cannot be changed once set. (Actually, this dictionary only exists at compilation time, since constants should all be gone by run time).
  3. User Dictionary Stack - All other user defined functions and variables are stored in the user dictionaries. These are kept on a dictionary stack (which is different from the operand stack). You can create new dictionaries on the stack as needed.
  4. Environment Dictionary - This dictionary contains all Unix environment variables that Backtalk was run with. They are all protected, so you can read them, but not change them. The values of environment variables are always of string type.
When you reference a variable, Backtalk searches for first in the system dictionary, then in the constant dictionary, then through all the user dictionaries, starting at the top of the stack and searching down, and finally, if the variable wasn't defined anywhere else, in the environment dictionary. Note that it is possible for there to be different variables by the same name in more than one dictionary. In this case, if you reference the variable, the value returned is the one from the first dictionary searched in the sequence descriped above.

This differs from Postscript in that in Postscript the built-in symbols are always at the bottom of the dictionary stack, while in Backtalk they are at the top. That means that in Postscript you can redefine system dictionary symbols by creating a new symbol by the same name on top of them. This cannot be done in Backtalk, because the system dictionary is effectively always on the top of the stack. This is a deliberate change, which allows us to bind system dictionary names at compile time, and perform significant amounts of optimization.

Note however that dictionaries in Backtalk are not a full-featured type as in Postscript. You can create new ones on the dictionary stack, and you can pop old ones off, but you can not store them in variables or push them onto the operand stack. We should probably add this in some day, since they would then provide much the same functionality that hashs provide in perl.

Before the execution of any other script, Backtalk will execute the config.bt file, which, among other things, creates the first user dictionary on the user dictionary stack. It then parses the QUERY_STRING generated by the user, and loads all the variables from the query string into the system and user dictionaries. If the variable appears in the system dictionary, (and is not protected or a constant) it will be saved there. Variables which do not appear in the system dictionary will be placed in the user dictionary.

begin
size begin -

Create a dictionary with room pre-allocated for the given number of symbols and push it on top of the dictionary stack. Dictionaries will automatically grow larger if you define more than the given number of symbols, so zero is a legal size for a dictionary, the size given is just an estimate of the size needed and will be the initial size. Note that a begin must be done before any user variables can be defined, since symbols cannot be added to the system dictionary. However, there is normally a begin in the "config.bt" script that will allocate the first user dictionary.

end
- end -

Discard the top dictionary from the user dictionary stack. The system, constants, and environment dictionaries are not actually on the dictionary stack and cannot be discarded.

def
label any def -
any label xdef -

Sets the symbol label to the given value in the current top dictionary. If any is a procedure, this defines a function. The two versions differ only in the order of arguments. Constants and protected variables cannot have their values changed.

store
label any store -
any label xstore -

Sets the symbol label to the given value in the topmost dictionary where it is already defined. If it is not defined, it creates it in the current top dictionary, just like def. If any is a procedure, this defines a function. Constants and protected variables cannot have their values changed.

undef
label undef -

Undefines the symbol label in the topmost dictionary where it is defined. Note that you cannotundefine system or constant dictionary values. If the given symbol is not defined, or is only defined in the system dictionary, nothing happens.

defconstant
label any defconstant -
any label xdefconstant -

Sets the symbol label to the given value in constants dictionary. Constants are expanded at compilation time, so they scope lexically, not dynamically. The two versions differ only in the order of their arguments.

inc
label inc -

This operator increments the named integer variable. It is equivalent to "dup exec 1 + store" but is quicker. It is an error if the variable is undefined, or does not contain an integer.

dec
label dec -

This operator decrements the named integer variable. It is equivalent to "dup exec 1 - store" but is quicker. It is an error if the variable is undefined, or does not contain an integer.

default
label default default value

This checks if the named variable is defined and pushes its value if it is. If it isn't defined, it pushes the given default value instead.

defined
label defined bool

This checks if the named variable is defined and pushes true if it is and false otherwise. This may also be used to check if environment variables are defined.

constant
label constant bool

This checks if the named variable is defined as a constant and pushes true if it is and false otherwise. This is used to do the Backtalk equivalent of the C-language "#if defined()" construct, since it is always resolvable at compile time.

Math Operators

The following built-in functions do integer arithmetic. All operands must be integers, and all results will be integers. Function names are not identical to Postscript.

+
int1 int2 + int_sum
time1 int2 + time_sum
int1 time2 + time_sum

Compute int1 plus int2 and push the resulting integer. You can add an integer number of seconds to a time to get a new time, but you cannot add together two times. Note the the + command is also used for string concatination.

-
int1 int2 - int_difference
time1 int2 - time_difference
time1 time2 - int_difference

Compute int1 minus int2 and push it on the stack. You can also subtract an integer number of seconds from a time to get another time, or you can subtract two times to get an integer number of seconds. Note that in the last case, there may be a possibility of overflow on some systems.

*
int1 int2 * product

Compute int1 times int2.

/
int1 int2 / quotient

Compute the integer part of int1 divided by int2.

mod
int1 int2 mod difference

Compute the remainder part of int1 divided by int2.

neg
int1 neg int2

Negative of int1.

abs
int1 abs int2

Absolute value of int1.

band
int1 int2 band int

Bitwise-and of int1 and int2.

bor
int1 int2 bor int

Bitwise-or of int1 and int2.

~
int ~ int

Bitwise-negation of int.

String Operators

Backtalk is not particularly rich in string operators. (Yet?) Unlike Postscript, each string is unique. For instance, if you do a dup on a string, you get two different strings with the same contents, not two pointers to the same string.

+
string1 string2 + concatenation

Concatenate two strings into one string.

`
'
` any1 any2 ... anyn ' concatenation

Convert any number of tokens into strings and concatinate them all together into a single string. The ` command just pushs a mark on the stack. The ' command pops off everything up to the first ` it finds, converts them all to strings (exactly like cvs would), and concatinates them all into a single string. If there are arrays on the stack, then all their elements are concatinated into the string.

length
string length count

Find the length of a string.

substr
string index length substr substring

Construct a string which contains the subsequences of the given string starting at the given index and extending for the given number of characters. If the length is negative, the string ends at the given index. Indices are zero-based.

chomp
string chomp string

Delete any and all trailing newlines from the end of a string.

search
string pattern icase search offset

Test if a fixed pattern occurs in a string. If the pattern is (), the previous search pattern is reused (saving some preprocessing time). If the search succeeds, the zero-based offset of the matching string in the text is given. If it fails, a -1 is pushed. If the icase argument is true, the search will be case insensitive.

replace
string pattern replacement icase replace newstring

Searches for all occurances of a fixed pattern in a string and replaces them all with the given replacement. If the icase argument is true, the search will be case insensitive.

quote
string quote string

This expands out all less-than (<), greater-than (>), ampersand (&) and quote (") characters to their corresponding html encodings. This should be done to any text that we send to the browser that we want to make sure will not be treated as HTML commands.

cgiquote
string cgiquote string

This replaces all spaces with plus signs, and expands plus sign (+), ampersand (&), less-than (<), greater-than (>), equal (=) and percent (%) sign with 3-character hexadecimal codes. This form of quoting is needed on strings that are to be passed as arguments in a GET style CGI query.

cap
string cap String

Convert the first character of each word in the string from lower case to upper case.

caps
string caps STRING

Convert all lower case characters in the string to upper case.

wrap
string numcols wrap string

This inserts newlines into the given strings so that it contains no lines with longer than numcols.

expand
string expand string

This expands out all less-than (<), greater-than (>) and ampersand (&) characters to their corresponding html encodings, and also makes all substrings that look like URLs into clickable texts that invoke that URL. It also wraps the string to 79 columns. It will also expand out cross-references if the script-writer has defined the functions to process them. This functions should abide by the following descriptions:

format_conf
conf item resp format_conf string...

The function should push onto the stack a "<A HREF=...>" anchor string that will begin a pointer to the conference conf. Normally the item and response inputs can be ignored.

format_item
conf item resp format_item string...

The function should push onto the stack a "<A HREF=...>" anchor string that will begin a pointer to item item in conference conf. Normally the response input can be ignored.

format_resp
conf item resp format_resp string...

The function should push onto the stack a "<A HREF=...>" anchor string that will begin a pointer to response resp of item item in the conference conf.

cleanhtml
html-string cleanhtml html-string

Given an HTML string, this sanitizes it, making sure that all tags are closed, and filtering out tags that we don't consider safe for people to insert into the middle of items and responses. This function is called automatically on all HTML responses submitted passed to the the post_item commands. If the allowgraphics flag is false, image tags are among those stripped out.

unhtml
html-string unhtml text-string

This converts an HTML string into a plain text string, removing all tags, and interpreting many of them so that this acts as a crude browser.

spellcheck
text texttype mode proc spellcheck -

This runs a spell checker on a block of text, running the given procedure once for each misspelled word, in the order in which the words appear in the text. The texttype may be either (text/plain) or (text/html). In the latter case, HTML tags (like <BLOCKQUOTE>) and special characters (like &nbsp;) are not checked. If mode is 0, then before each execution of the procedure, spellcheck will push the misspelled word on the stack. If mode is 1, then before each execution of the procedure, spellcheck will push the portion of text since the last misspelled word on the stack, and then push the misspelled word. When spell checking is done, spellcheck will push the remainder of the correctly spelled text if the mode is 1.

Thus, to get an array of all misspelled words, you could do:

   [ text (text/html) 0 {} spellcheck ]
or to change all misspelled words to upper case:
   ` text (text/html) 1 {caps} spellcheck '

As in other forms of loops, break and continue can be used inside the procedure, however, unlike other loop structures, you cannot use a second spellcheck command inside the procedure (hard to imagine why you would want to). The canspell constant tells if this installation supports spell checking. If it does not, no misspelled words will ever be found. The spell_lang variable tells what language to do the spell checking in.

parse
string del parse rest first

This picks the first word off of a string. The delimiter string gives a list of characters which may appear between, before and after words. Unlike the clip function, parse treats multiple consecutive delimiters as a single delimiter. This can be used to break a text string into lines as well as words.

For example, "(,,foo,;bar;fub) (;,) parse" will pick off the word (foo) and also return the rest of the string (bar;fub). If the string contains no non-delimiter characters, both output strings will be ().

clip
string del clip rest first

This finds the first occurrence in the string of a character in the delimiter list, and returns the segment of the string before and after that character. Unlike the parse function, clip does not treat multiple consecutive delimiters as a single delimiter.

For example, "(foo,,bar) (,) clip" will return the word (foo) and the rest of the string (,bar). Similarly, "(,,foo,;bar;fub) (;,) clip" will return the word () and also return the rest of the string (,foo,;bar;fub), and "(foobar) (,) clip" will return the word (foobar) and reminant ().

split
string del split word1 word2...

This slices up a string into words, where words are substrings of the string separated by any sequence of one or more delimiters (so multiple delimiters count as a single delimiter as in parse.

For example, "(,,foo,;bar;fub;) (;,) split" push "(foo)", "(bar)" and "(fub)" on the stack. If the string contains no non-delimiter characters, nothing is pushed on the stack.

inlist
word list del inlist boolean

This checks if the given word appears in the given list, which is a string of words separated by the delimiters given in the delimiter string.

cvi
any cvi integer

Converts an object to an integer. If the object is already an integer, this is a no-op, but if it is a string like (486), it converts it to the integer 486. It is basically the Unix atoi() call, so it ignores any non-numeric characters after the digits, and returns zero if the string does not begin with digits at all. If the input is a time, it converts it into an integer (there may be overflow problems with this after the year 2038).

cvt
any cvt time

Converts an object to an time. If the object is already a time, this is a no-op, but if it is a string representing a integer, or an integer it gives the time that many seconds after the epoch.

cvs
any cvs string

Converts an object to a string. If the object is already a string, this is a no-op. If the object is an integer like 486, it converts it into a string like (486). If the object is a literal like /abc, it converts it into a string like (abc) If the object is a time, cvs does the same thing as ctime. If the object is a regular expression or mark, it converts them to an empty string. If the object is an array or procedure, it converts everything in it to a string and concatinates them all together.

cvscol
integer numcols cvscol string

Converts an integer to a string, right-justifying it within a string of numcols blanks.

cvn
string cvn literal

Converts a string to a literal variable name. If the string obeys the length and syntax rules for a variable, it is converted into a literal. Thus, the string (abc) becomes the literal /abc.

Array Operators

Arrays store sequences of objects. Not all elements of arrays need to be the same type. They can contain any mixture of integers, strings, marks or subarrays.

If you dup an array, you don't get two identical arrays, but two references to the same array. Similarly, if you have a variable defined to an array value, referencing pushes a pointer to the original array, not a copy of the array onto the stack. This is different from string types, which are always copied in these circumstances.

When a print is done, either explicitly or automatically at termination, arrays are handled by printing all their elements in sequence, as if they had all been on the stack separately.

[
- [ mark

The left bracket pushes a mark on the stack. This operator is identical to the mark operator, but is traditionally used to mark the beginning of a sequence of stack elements that are going to be formed into an array by the ] operator.

]
mark any0...anyn-1 ] array

This takes all stack elements up to the mark off the stack, creates an array to store them in, and pushes the resulting array on the stack.

aload
array aload a0...an-1

This pushes the elements of an array singly onto the stack.

length
array length n

This finds the number of elements in an array.

get
array i get ai

Fetch an element from an array. Indexing is zero-based. It is an error if the index is out of range.

put
array i any put -

Store a value in an array element. The value may be of any type. For this to be useful, the array on the stack should have come from some variable, so that the changed array can be accessed again. If the index is past the end of the array, the array will be automatically grown large enough to have such an index, filling in any gap with empty string values. Thus if we do

    /a [(a) (b)] def
    a 4 (c) put
then we end up with the array "[(a) (b) () () (c)]".

in
any array in i

Given an array and a string, integer or time value, check if that value is in the array. If it is, return the index of the first occurance. If it isn't return -1.

asort
array k ascend asort array

This sorts an array of arrays. K is a zero-based index designating which element of each subarray is the sort key. If ascend is true, it sorts the array into ascending order, otherwise it sorts it into descending order. It is an error if any of the elements of the array are not subarrays, if any of the subarrays have less than k+1 elements, or if the kth elements of all the arrays are not all of the same type. The only types that can be sorted on are strings, integers and times. Uses a fairly decent quicksort implementation.

Selector Manipulation Operators

Selectors are used to designate sequences of conferences, items, or responses. They are simply strings of words separated by commas or dashes. Dashes may only be used between two integers or between an integer and a dollar sign, where a dollar sign indicates the last item or response. Thus typical selectors include "dog,cat,mouse,lemon" or "2,13-15,10,7" or "95-18,10". Negative numbers are not understood in selectors.

next_int
sel max next_int rest first

Extract the next number from an integer-type selector, updating the selector to delete that value. The maximum value given will be understood as the value of any dollar sign that appears in the selector. If the selector is empty, a -1 is returned. If it is syntactically incorrect, a -2 is returned.

in_sel
value sel in_sel bool

This checks if the given value is included in the given selector. The value can be a string or an integer. If the value is an integer, it treats the selector as an integer selecter. Dollar signs are treated as infinity values.

count_sel
sel last count_sel count

This counts the number of objects included in a selector. If there are any dollar-signs in the selector, the integer last is assumed to be its value.

rev_sel
sel rev_sel sel

This reverses the order of a selector. That is "2,13-15,10,7" becomes "7,10,15-13,2".

Relational and Boolean Operators

In Backtalk, booleans are represented by integer, time, or string values. The integer zero, the time "00:00:00 Jan 1, 1970" and the empty string are false, and all other values are true. Functions returning a boolean, return 1 for true and 0 for false. Relational operators may be used on strings, integers, times, and literal names, but you can only compare two objects of the same type.

eq
any1 any2 eq bool

Test if any1 is equal to any2. You can compare times to the integer zero.

ne
any1 any2 ne bool

Test if any1 is not equal to any2. You can compare times to the integer zero.

ge
any1 any2 ge bool

Test if any1 is greater than or equal to any2.

gt
any1 any2 gt bool

Test if any1 is greater than any2.

le
any1 any2 le bool

Test if any1 is less than or equal to any2.

lt
any1 any2 lt bool

Test if any1 is less than any2.

and
bool1 bool2 and bool

Logical-and of bool1 and bool2.

or
bool1 bool2 or bool

Logical-or of bool1 and bool2.

!
bool ! bool

Logical-negation of bool.

Control Operators

Backtalk includes a fair selection of looping and conditional operators. The "boolean" variables mentioned can actually be either string or integer variables. All integer values except zero are treated as true, and all string values except the empty string () are treated as true.

if
bool proc if -

The given procedure is executed if and only if the given boolean is true.

ifelse
bool then-proc else-proc ifelse -

Either of the first or second procedures are executed, depending on whether the boolean is true or not.

loop
proc loop -

Execute the given procedure repeatedly forever, or until a break is performed (or a halt or even a stop for that matter).

while
proc while -

Execute the given procedure for as long as it ends with a true boolean pushed on the stack. Terminate as soon as the procedure pushs a zero or an empty string. The while command discards all the continuation flags pushed on top of the stack at the end of each iteration, but any other values pushed are left on the stack. While loops may be terminated by break as well.

The command "{...} while" is equivalent to "{... ! {break} if} loop".

The command "{... 1} while" is equivalent to "{...} loop".

repeat
count proc repeat -

Execute the given procedure the given number of times. Nothing is put on the stack or removed from the stack by the repeat command. Repeat loops may be terminated by break. If the count is zero or negative, repeat does nothing.

forall
array proc forall -
string proc forall -

Forall loops through the elements of an array or a string. It does one iteration through each element of the array or character of the string. Before each iteration, forall pushs the current element on the stack. String elements are pushed as single-character strings (this is unlike postscript which pushs them as integers). Thus "{} forall" is equivalent to aload.

for
init inc limit proc for -

For loops are given a procedure and three integer arguments. An internal variable is set to the initial value before the first iteration. The increment is added to it before each successive iteration. If it passes the limit, iteration is terminated. (That is, if increment is positive and it becomes greater than the limit, or if increment is negative and it becomes less than the limit). Note that the procedure will not be executed at all if the initial value is greater than the limit and the increment is positive, or if the initial value is less than the limit and the increment is negative. If the increment is zero, this is an infinite loop. In addition, before each execution of the procedure, the current value of the count is pushed on the argument stack. Iteration may also be terminated by a break command.

For example, "1 2 1 n {*} for" computes n factorial.

break
- break -

Terminate execution of the first enclosing iterative context. This can be used in the procedures of loop, while, repeat, forall, and for commands. It may be used from inside a file included or called in a iterative procedure. If used outside of an iterative procedure, it is equivalent to a halt command.

continue
- continue -

Terminate execution of the current iteration of the first enclosing iterative context, so that it continues with the next iteration of the loop. This can be used in the procedures of loop, while, repeat, forall, and for commands. It may be used from inside a file included or called in a iterative procedure. It is an error to use it outside of an iterative construct.

halt
- halt -

Stop the execution entirely. After execution is halted, anything remaining on the operand stack will automatically be printed. If you wish to prevent this, do a clear before the halt.

exec
any exec -

Execute the given token. If the object is a procedure (in curly braces) it gets executed. If it is an array, it gets executed as if it was a procedure. If it is a literal, it gets executed as if it was a symbol (that is "/x exec" is equivalent to "x"). Strings, integers and marks just get pushed back on the stack (so it is a no-op on these).

call
filename call -

Suspend execution of the current file, and run the given file. When the called file is complete, resume execution of this file. The filename must be a relative path with no ``..'' components in it. (That is, you can only include files under the scriptdir directory.)

This is similar to the include command, except that though the two files share variables and function definitions, they do not share not constants, because the call is done at run time, not compile time. Thus constants defined in the current file are not accessible in the called file, and constants defined in the called file are not accessible in the current file, though both may use constants defined by the config.bt file.

include
filename include -

Include the contents of the given file into the current program at this point. The filename must be a relative path with no ``..'' components in it. (That is, you can only include files under the scriptdir directory.) This is similar to the call command, except that since included files are included at compile time, constant definitions from the current file effect the included script, and constants defined in the included script will effect the remainder of the current file. Including files instead of calling them makes a bigger binary file, but will normally run faster.

chain
filename chain -

Include the contents of the given file into the current program at this point, and stop the current program immediately after running it. The filename may not include ``..'' components in the path. This is almost equivalent to doing "include stop", except that it is more slightly more efficient and if the current file is being run under a stopped command, then the termination code of the file we chained to will be returned to the enclosing environment. As with the include command, constants defined in the current file will be usable in the chained file.

jump
filename jump -

Halt the execution of the current file and continue with the execution of the named file. The filename may not include ``..'' components in the path. This is almost equivalent to doing "call stop", except that it is more efficient and if the current file is being run under a stopped command, then the termination code of the file we chained to will be returned to the enclosing environment. As with the call command, variables defined in the current file will be usable in the chained file, but constants will not be.

stopped
filename stopped bool

Insert the contents of the given file. The filename may not include ``..'' components in the path. This is almost equivalent to include except that upon termination it pushs a zero if the execution of the file terminated normally, and a one if the execution terminated with a stop command.

stop
- stop -

Terminate the enclosing file execution. This causes a premature termination of an include or stopped command. If the current context is a stopped command, a one will be pushed on the stack. If there is no enclosing include or stopped, this is equivalent to a halt.

Output Operators

Output is done from the stack. Text formatting is done with separate calls to other routines, not by the output routines themselves, so they aren't very complex.

When outputing an HTML document from CGI programs like Backtalk, it is necessary to prefix the output with the appropriate HTTP headers. Backtalk will automatically output these immediately before the first print, pr or dumpstack command.

You can exert some control over the content of these headers, so long as you do it before the first output statement. If you do so before te first output statement, you can

print
| any1 ... anyn print |

Print out the entire contents of the stack, from bottom up. A print command is automatically executed on termination. Integers and strings are printed the obvious way. Times are printed as if pr

any pr -

Print out the top stack element.

dumpstack
- dumpstack -

Prints a snapshot of the stack to standard output, without altering the stack. This is a debugging tool.

setcookie
name value expire-time setcookie -

Set a cookie by adding a "Set-Cookie" directive to the HTTP headers for this page. This must be done before the first print, pr or dumpstack command, since the headers are output before the first text is output. Name is the name for the cookie and value is its value. The value should not contain any spaces or semicolons (actually, spaces seem to work with at least some browsers). Expire-time is the expiration time for the cookie. If it is zero, the cookie has no expiration time, and will be deleted as soon at the user exits his browser. If it is in the future, the user's browser will keep the cookie until that point in time and then delete it. If it is in the past, the cookie expires immediately (to delete an existing cookies from the user's browser, we overwrite it with one whose expiration date is in the past). You can set more than one cookie from the same page so long as they have different names. If you set the same cookie twice from the same page, only the last value is sent to the browser.

getcookie
name getcookie value 0
name getcookie 1

Get the value of a cookie set on some previous Backtalk page. If the cookie exists, the value is pushed on the stack along with an error code of zero. If it does not exists, only the error code of 1 is pushed. (Note that you can alternatively get cookies out of HTTP_COOKIES environment variable yourself.)

Regular Expression Commands

Backtalk's regular expressions are similar in syntax to those in Perl or in many other Unix programs. You can write the regular expression into your program, enclosing it in double angle-brackets ("<<" and ">>") or you can use the regex command to compile a string into a regular expression. Note that regular expressions entered in double-angle brackets will be compiled at compile time, speeding up their use at run time. Compiled regular expressions can be manipulated like any other Backtalk data type - they can be pushed on the stack, duplicated, assigned to varibles, etc. There aren't many operations you can perform on them except searching with them.

The full syntax of Backtalk regular expressions is described below.

There is a command to compile strings into regular expressions, and several commands to search for regular expressions. The following regular expression commands are known to backtalk:

regex
string flags regex regex 0
string flags regex errmsg 1

Compile a string into a regular expression. The string is a regular expression defined by as below. The flags may be "()", "(m)", "(i)", "(im)" or "(mi)". The "i" means to ignore case, the "m" means to "^" and "$" match against newlines internal to a pattern, not just the beginning and ending of the pattern. If the regular expression syntax is OK, it is compiled and pushed onto the stack, followed by a one. If the syntax of the regular expression is incorrect, an error message string is pushed on the stack, followed by a one.

grep
string regex grep boolean

Check if the given pattern occurs in the string. Push 1 if it is, 0 if it isn't.

ogrep
string regex ogrep array 1
string regex ogrep 0

Just like grep, except if it succeeds it returns information about where the match occured, plus information about what each paranthesized subexpression matched. The returned array has one more element in it than there are pairs of parentheses in the regular expression. Each element of the array is a two element array, giving an beginning offset and the length of a substring of the original string. The zeroth pair indicates the portion of the entire matched by the entire regular expression. The remaining pairs indicate the substrings matched by each set of parenthesis in the regular expression.

sgrep
string regex sgrep array 1
string regex sgrep 0

Just like sgrep, except instead of returning an array of offsets and lengths of matching strings in the original string, it returns an array of strings, where the zeroth element is the substring of the input string that matches the full regular expression, and each other element of the array is the substring of the original text that matches the corresponding parenthesized subexpression in the regular expreassion.

rgrep
string regex nmatch proc rgrep -

This searches the string for sections matching the regular expression. Each time a match is found, the non-matching substring between the last match and this match is pushed on the stack. If nmatch is one, the matching substring is also pushed. If nmatch is greater than one, then nmatch substrings are pushed, the first being the substring that matched the whole expression, and the later ones being the substrings that matched any parenthesized subexpressions. After all this stuff has been pushed the procedure is executed. This continues until no more matches are found or until the procedure does a break. At that time, the remaining unmatched hunk of string will be pushed. A negative nmatch value means push all subexpression matchs.

Warning: This can go into really impressive infinite loops if given a pattern that matches a null string.

You can delete all instances of an expression from a string by doing

` string expression 0 {} rgrep '
You can substitute all occuranges of a regular expression with the text "XXX" by doing
` string expression 0 {(XXX)} rgrep '
To substitute only the first instance, do
` string expression 0 {(XXX) break} rgrep '
You can convert all occuranges of a regular expression to upper case by doing
` string expression 1 {cap} rgrep '
You can do pretty much anything else your heart desires too.

File Commands

File commands take filenames in either of two different formats. The first is the standard Unix format, where the filename is given as a full or partial path. Partial paths are aways relative to scriptdir.

The second format is as a Backtalk file-handle. File handles always start with an asterisk followed by the name of a file. Backtalk figures out the full path of the file by itself. It also knows something about the type of the file and who may write to it.

Commands to read from files will accept either format. Commands to write from files only work with file-handles. Thus only files for which Backtalk has handles may be written to, and Backtalk will enforce rules about who may write to those files. The following handles are known to Backtalk:

(*.backtalk)
The current user's biography and configuration file. Backtalk uses this instead of the Picospan .cfonce file for user configuration.
(*.cflist)
The current user's conference list. Shared with Picospan.
(*.cfonce)
The current user's file of Picospan commands to run on start up. Mostly used by Picospan.
(*.cfrc)
The current user's file of Picospan commands to run on when a new conference is joined. Mostly used by Picospan.
(*.plan)
The current user's .plan file.
(*bbsrc)
A Picospan command file executed for all users when they first enter. Mostly used by Picospan.
(*bull)
The current conference's bulletin file (Rarely used).
(*config)
The current conference's configuration file.
(*confmenu)
The current list of conferences displayed to users (Replaces the Picospan public.txt file).
(*confrc)
A Picospan command file for the current conference. Mostly used by Picospan.
(*dflt.backtalk)
The system-wide defaults for user configuration settings not set in the user's .backtalk file.
(*dflt.cflist)
The system-wide default conference list used for users with no .cflist file.
(*glist)
The current conference's glist file. For closed conferences this is a list of all user group names that can access the conference. (Backtalk only).
(*index)
The current conference's index file. (Rarely used).
(*login)
The current conference's login file. (Ascii text version used by Picospan. The ``login'' tag in the ``*settings'' file is preferred by Backtalk.)
(*logout)
The current conference's logout file. (Ascii text version used by Picospan.)
(*motd.html)
HTML formatted message-of-the-day to be displayed on front page.
(*public.txt)
The system-wide list of conferences (used by Picospan only).
(*secret)
The current conference's password.
(*settings)
The current conference's settings file. (Backtalk only).
(*ulist)
The current conference's ulist file. For open conference, this is a list of user logins who have joined the conference. For closed conferences, it is a list of user logins who are allowed to join the conferences.
(*welcome)
The current conference's welcome file.
A few files are associated with separate default files. If the user doesn't have a .cflist file, and you attempt to read from it, then the dflt.cflist file will be read instead. Thus, all users who don't define their own conference lists, get the system default conference list. The defaulting mechanism is never used on writes. If a user who doesn't have a .cflist writes to his .cflist, the file is created.

The user's .backtalk file also has a default file, the system dflt.backtalk file, but defaulting works a bit differently for tag files. If you attempt to load a tag which is not defined in the .backtalk file, the system will then search for it in the dflt.backtalk file. A similar defaulting mechanism is planned for conference settings files, but has not been implemented yet. The following file commands are known to backtalk:

read
filename read string

The entire contents of the named file are pushed onto the stack as a single string. The filename may be a path or a file-handle. If the file doesn't exist, but the handle has a default file, the default file is loaded instead. If no file exists, a null string is returned.

write
string filehandle write -

The given file is first created or emptied, and then the given string is written into it. The filename must be designated with a file handle. It is a fatal error if the file is not writable.

savevar
filehandle varlist savevar -

Save one or more variables into the named tag file, which must be designated by a file handle. The variable list argument may be either a single variable name, or an array of variable names. All variables must be defined, and must have an integer or string value. If the tagfile does not exist, it will be created. If it does exist, the new fields will be added to the ones already there, replacing any with the same name. Attempts to change the value of protected tags are silently ignored.

loadvar
filename varlist loadvar error

Load one or more variables from the named tag file, whose name may be given as either a path or a file-handle. The variable list argument may be either a a single variable name, or an array of variable names. Each variable will be set to the value defined for it in the file, using a store operation to set it. A variable name ending in a dot will load all variables with that prefix. If there is no definition for a variable in the tag file, that variable will be silently ignored. If the file does not exist, a boolean false is pushed, otherwise it returns true. Any fields not defined in the file itself will be loaded from the default file, if one is defined for the handle. Any variable with is not defined will simply not be changed.

line
filename n line string

Read the nth line of a file and push it on the stack. Lines are numbered from zero. A null string is pushed if the file or the line doesn't exist.

readable
filename readable bool

Test if the named file can be read. The name may either be a path or a file-handle. If file handle has a default, it will return true even if the named file doesn't exist, but the default file does.

writable
filename writable bool

Test if the named file can be written. Only file-handles are writable, so if a path is given it will always fail. Files that do not exist may be writable if they are in a writable directory.

exists
filename exists bool

Test if the named file exists. If file handle has a default, it will return true even if the named file doesn't exist, but the default file does.

filedate
filename filedate time

If the file exists, push the time at which it was last modified (the mtime). If it doesn't exist, push zero.

User Database Operators

The following commands query or edit the Backtalk user database. The user database may be configured in many different ways. Normally Backtalk accounts are completely disconnected from Unix accounts on the host system, however for systems where Backtalk is to coexist with Yapp or Picospan, it may be desirable to use real Unix accounts for Backtalk accounts. In this case, the routines to create accounts and groups, change passwords, change fullnames, and validate or delete accounts will not work (all these operations would require root access, which Backtalk does not have). Users will have to log onto their Unix accounts to perform these operations.

Backtalk has a notion of user groups similar to the unix notion of user groups. Users have a primary group ID, and can also be in several secondary groups. Three groups are special. The 'user' group is the default user group, in which accounts are normally created. Any user in the 'cfadm' group is a conference administrator, and can create, destroy and edit user accounts and conferences, and functions as a fairwitness in all conferences. Any user in the 'gradm' group can also create accounts, even if the system is configured so that regular users can't. Furthermore, users in the 'gradm' group can create accounts not only in the 'user' group but in any other group (except 'gradm') of which the user is a member. Other groups may be created, and conferences may be configured so that only members of some group may join them.

userinfo
login userinfo uid gid fullname directory laston status

Fetch information about a user from the user database. Given a login name, this returns the user id number, the group id number, the fullname, the home directory name, the time of the last login, and the user's status. Status is 0 for valid accounts, 1 for unvalidated accounts, and 2 for invalidated accounts. If the user does not exist, directory and fullname will be (), and uid, gid, laston time and status will be 0. If mayseefname is false and we our not looking up ourselves, then the fullname will be ().

firstuser
- firstuser login

Return the login name of the first user in the user database. The notion of "first" here man be nearly meaningless. The intent is that this be used to initialize a walk through the user database done with nextuser.

seekuser
login seekuser -

Like firstuser, this initializes a walk through the user database, but instead of starting from the beginning, it starts from the named user. The next call to nextuser will return the name of the successor of the user passed to this function.

nextuser
- nextuser login

Return the login name of the next user in the user database. firstuser or seekuser must have been called previously to initialize the loop.

ingroup
group login ingroup boolean

Check if the named user is in the given group. If the login ID is given as (), check the currently logged in user. The group may be given either as a string group name or an integer gid number.

groups
- groups groupname1 groupname2 ...

Push the names of all known user groups onto the stack.

dfltgroup
- dfltgroup groupname

Push the name of the group in which users are created by default.

groupid
groupname groupid groupid

Given a group name, find the corresponding group id number. If no group by that name exists, return -1. If the input string is numeric, like (23), it simply converts that to an integer type.

groupname
groupid groupname groupname

Given a group id number, find the corresponding group name string. If no group by that name exists, return ().

newuser
login fullname password group varlist newuser error

Create a new user account. Depending on your system configuration, this may work for all users, or only for those in the 'cfadm' and 'gradm' groups. Users in the 'gradm' group may create accounts in any group that they are members of, except the 'gradm' group. Users in the 'cfadm' group may create accounts in any group. Other users, if they are allowed to create accounts at all, can create them only in the default user group.

The login is the desired login id, and password is an unencrypted password to use. The group may be given either as a string group name, or an integer gid number.

The varlist is a array of literal names (or a single literal name) to save to the user's .backtalk file, just as in the savevar command. In addition to the variables listed, a variable named 'regdate' is saved with the current time.

On success, an empty string is returned. Otherwise, a string of error messages (separated by \n) is returned.

changegroup
login newgroup changegroup error

Set the given user's primary group id to the given value. The group can be given either as a numeric gid, or as a string group name. If the login or groupname does not exist, or the group number is negative, an error string is returned. If they are OK, a null string is returned. Only conference administrators have the power to execute this command. This function will not work on installations where the nopwedit constant is true (i.e., those that use the unix password file as the user database).

changename
newname changename error

Set the user's full name to the given new name. User must be authenticated. If the new name is illegal, an error message is return. If it is OK, a null string is returned. Note that the fullname is not the user's current alias in the current conference (that is changed by the conf_alias function). The fullname is the default value for the alias when he joins a new conference for the first time, and it is the name printed when someone asks for a bio of the user. Conference administrators may apply this command to another user's account by doing a selectuser command. This function will not work on installations where the nopwedit constant is true (i.e., those that use the unix password file as the user database).

changepass
newpassword changepass error

Set the user's password to the given string. If the password isn't reasonably good, an error message is return. If it is OK, a null string is returned. Conference administrators may apply this command to another user's account by doing a selectuser command. Note that this validates previously unvalidate or invalidated accounts as a side effect. This function will not work on installations where the nopwedit constant is true (i.e., those that use the unix password file as the user database).

selectuser
loginname selectuser -

Users in conference administrator group may execute this command for any user login, and user in the gradm group may execute it for user logins which have the same primary group as they do. It changes the account that changepass, changename and removeuser operate on from the user's own account to the named account. It also makes file handles for user files refer to the selected user's files, so that the conference administrator may write to them. Giving a login name of () reverts to selecting the conference administrator's own account.

removeuser
- removeuser -

Permanently delete the user's account. Conference administrators may apply this command to another user's account by doing a selectuser command. This function will not work on installations where the nopwedit constant is true (i.e., those that use the unix password file as the user database).

validate
loginname flag validate -

This validates (if the flag is true) or invalidates (if the flag is false) a user account. Invalidated accounts still exist, but cannot be logged into. Users in conference administrator group may execute this command for any user login, and user in the gradm group may execute it for user logins which have the same primary group as they do. This function will not work on installations where the nopwedit constant is true (i.e., those that use the unix password file as the user database).

newgroup
groupname newgroup flag

Create a new group with the given group name. Returns 1 if the group already exists, 0 on success. Only conference administrators can execute this command.

newgroupmem
groupname username newgroupmem flag

Add the given group to a user's list of secondary groups. Returns 1 if the group does not exist, 0 on success. Only conference administrators can execute this command.

delgroup
groupname delgroup flag

Delete a group. Returns 1 if the group did not exist, 0 on success. Only conference administrators can execute this command.

delgroupmem
groupname username delgroupmem flag

Remove the given user from the given group. Returns 1 if the group does not exist or the user was not in it, 0 on success. Only conference administrators can execute this command.

Miscellaneous Operators

browser
- browser code

This returns an integer code classifying the user's browser into one of four rough groups according to its capabilities.

code=0:
Non-graphical browsers, like Lynx. No tables.

code=1:
Basic HTML 2.0 browsers, with no tables or frames. Often &nbsp isn't work.

code=2:
Enhanced browsers, with tables, but not frames. Netscape 1.x browsers.

code=3:
Browsers that support frames. Netscape 2.0 and Internet Explorer.
Further codes may be added in the future (maybe 4 means Java). The database this is generated from is currently very incomplete. The complete description of the browser can be found in the environment variable HTTP_USER_AGENT.

time
- time seconds

Push the current time, as a Backtalk time object.

ctime
seconds ctime string

Convert a Backtalk time to a text string representing the time. The string has the usual Unix format (except without a terminal newline), and the substr command may be used to pick out your favorite segment. If the timezone variable is defined to something other than a null string, ctime converts using that timezone.

ztime
seconds ztime string

Convert a Backtalk time to text string representing the time. The string has the same format as the ctime string, except that it includes a three-letter timezone abbrevition. If the timezone variable is defined to something other than a null string, ztime converts using that timezone.

dtime
string future start dtime seconds

Convert a date/time described by a string to a Backtalk time The input string can be very flexibly formatted. Things that work include exact times, like ``7:30pm January 18, 1994'' or ``1/18/94 19:30:00,'' and less completely specified times like ``March,'' ``June 17,'' ``7pm,'' or ``Tuesday''.

For incompletely specified dates, it will return either the next occurrence of that date (if future is true), or the most recent occurrence of that date (if future is false). For strings that actually describe a period of time (like ``Feb 1996''), it returns the beginning of the time period (if start is true), or the end (if start is false). This can be overridden if the input string is explicit about which interpretation we want, like ``the beginning of next March''.

You can also use relative times in the string, like ``-3 months'' or ``3 months ago'' or ``+1 year, 6 hours, 8 seconds.'' If no sign is given, as in ``3 days,'' the future flag determines whether the returned date will be 3 days in the future or 3 days in the past.

Absolute dates are presumed to be in the time zone specified by the timezone variable.

Minimum and maximum time values can be obtained by asking for ``the beginning of time'' or ``the end of time'' or just ``start'' or ``end''.

If a string that cannot be interpreted is given, dtime returns zero. (Note that ``the beginning of time'' returns one not zero.)

rand
range rand number

Generate a random integer between zero and range-1.

srand
seed srand -

Seed the random number generator with the given seed. If do not explicitly seed the random number generator, it is automatically seeded with the current time (Essentially a "time srand" is done). Thus, the srand call is only needed if you want repeatable runs while debugging.

timeout
seconds timeout -

Terminate the program with a crash after the given number of seconds has elapsed. This is meant to be used during development of new scripts to control infinite loops, since the script developer may not have the access to kill a runaway process. Successive timeout calls reset the clock. An argument of zero cancels any pending timeouts.

showopt
flag showopt version-description

This function outputs a long, multiple-line description of the version and configuration of the Backtalk interpretor. If the flag is true, the description will be formatted with HTML line breaks, otherwise it is just plain text.

Conferencing Operators

The commands described in this section constitute the interface to the conference database. Many of their inputs and outputs are passed through system variables instead of the stack. These variables are individually described in the next section. This manually currently describes the Picospan-compatible implementation. Other future implementations may differ.

next_conf
csel next_conf csel conf

This gets the next conference name from the given conference selector, and pushs an updated conference selector, and the new conference name. It does not check that the named conference exists. The conference selector may be either a comma-separated list of conference names, or a string like (@0), consisting of an at-sign and a number. In the latter case the number refers to a line of the user's .cflist (or the default .cflist if the user is unauthenticated or doesn't have a .cflist).

open_conf
- open_conf err

This opens a conference (specified by the conf system variable). Most of the other commands will only work after a conference has been opened. Any previously open conference is automatically closed by open_conf. If you attempt to open a conference named '?' then you get the default conference. If the conference is already open, this command is a no-op. For Picospan-format conferences, it loads information from the conference "config" and "sum" files and from the user's participation file. It sets the variables maxitem, amfw, fwlist, maypost, mayread, alias, confdir, fishbowl, userlist, secret, conftitle, and particip. It pushes an error code which is 0 if the conference exists, and 1 otherwise. Note that you can open conferences to which you do not have access (due to not being on the ulist/glist or not having the right cpass), but in those cases mayread and maypost will be false.

close_conf
- close_conf -

This command closes the currently open conference. It writes out the participation file and generally cleans up and closes down, but there is really no reason to ever call it. Each open_conf command automatically closes any previously open conference, and Backtalk automatically executes a close_conf upon the termination of your script.

conf_dir
confname conf_dir confdir

Given a conference name, return its directory path. Note that open_conf does the same thing and more, so this is only useful if you want to know the directory path of a conference you probably don't intend to open. Since the same conference can have multiple names, the only way to test if two names refer to the same conference is to look up their conference directory names and compare those.

cache_conflist
boolean cache_conflist -

This turns on and off in-memory cacheing of the conference list. If you are planning to do a lot of calls to open_conf or conf_dir, then turning this on will improve performance. Turning it off when you are done will reduce memory use. It is off by default.

resign_conf
- resign_conf -

This command closes the currently open conference and resigns from it, discarding all record that the user has ever been in it.

conf_new
- conf_new total brandnew newresp unseen

Find the total number of items, the number of brand new items, the number items with new responses, and the number of new but unseen items in the current conference. Forgotten and retired items are included in the total count, but not in the brandnew and newresp count.

conf_alias
newname conf_alias -

Set the user's name within the current conference to the given value. This will continue to be his default alias in this conference on all future sessions. See also the changename function.

conf_bull
- conf_bull text

Push the text of conference bulletin on the stack. Open_conf must have been called. Equivalent to '(*bull) read'.

conf_index
- conf_index text

Push the text of conference index on the stack. Open_conf must have been called. Equivalent to '(*index) read'.

conf_login
- conf_login text

Push the text of conference login message on the stack. Open_conf must have been called. Equivalent to '(*login) read'.

conf_logout
- conf_logout text

Push the text of conference logout message on the stack. Open_conf must have been called. Equivalent to '(*logout) read'.

last_in_conf
- last_in_conf time

Return the date and time when we last modified the conference's participation file. If we weren't members of the conference before now, return a time of zero. Open_conf must have been called.

next_item
is next_item is nrs item 0
is next_item err

Next_item identifies the next item number from the item selector given on the stack. The item will be the next one named in the item selector which has responses selected by the system variable rsel. The rsel variable may be set to (all), (new), (unseen), (since) or to a numeric range. If rsel is (new), only items with new responses will be found. If rsel is (unseen), unseen items and items with new responses will be found. If rsel is (since), only items with responses since the date given in the since will be selected. Next_item will also skips forgotten or retired items if showforgotten is not set. If the variable noskip is true, however, items will not be skipped, even if no responses are selected.

When it finally finds an qualifying item, it pushes the remainder of the item-selector on the stack, followed by a numeric version of the response selector, the number of the new item, and a zero code indicating success. Often this_item will then be called to make the item found by next_item into the current item. An error code of 1 is pushed if there is no next item, or an error code of 2 is pushed if the item selector has bad syntax.

this_item
rsel item this_item nrs 0
rsel item this_item err

This_item is given a response range and an item number, and makes that item in the currently open item the current item. If the response range was not numeric, converts it to numeric form. It reads the sum and participation file information for the item, stores that information in system variables, and prepares to read the item.

If successful, this_item pushs a numeric response-selector and a 0. On error it pushes a non-error code on the stack: 1 if the items does not exist, 2 if we lack read access to it. If the input response selector was numeric, it is the selector output, but values of (new), (since) and (all) are converted into the corresponding numeric string. The Picospan implementation also sets the following system variables: item, maxresp, maxread, linkdate, lastdate, readdate, forgotten, frozen, maypost, retired, and linked. In future implementations, some of these variables may not be set until you do a read_item command. Even in the current implementation, some may be "corrected" at that point, since the item itself is considered a more accurate source of information than the sum file.

An error code of 1 is pushed if the item does not exist. An error code of 2 is pushed if the user does not have read access to the conference.

read_item
nrs read_item nrs 0
nrs read_item err

The read_item command can be called after a this_item call. It loads information from the item file header and prepares for a scan of the responses.

To prepare for the scan it takes a numeric response-selector off the stack and adjusts it. If it started with a 0, indicating that the item text (response 0) is to be read, it removes that element from the response selector and sets the resp system variable to 0, indicating that we are at response zero. If the numeric response-selector starts with anything else, it leaves it unchanged and sets resp to -1, indicating that there is no current response.

In addition, it sets the title, date, date, authorname (to null if mayseealias is false), authorid, authoruid, texttype, hidden, erased , mayedit, mayerase, mayhide, mayfreeze, mayretire, mayretitle and maykill system variables to the values for the item (or item text).

It will also replace the frozen, linked, and retired values which were taken from the sum file by this_item with more authorative values taken from the item file itself, possibly also changing maypost. This only makes a difference if the sum file is munged.

If the item file does not exist, an error code of 1 is pushed. If the numeric response selector has bad syntax, an error code of 2 is pushed.

next_resp
nrs next_resp nrs resp 0
nrs next_resp err

The next_resp picks the next response number out of a numeric response selector, deleting that response from the selector. It pushs an error code of 1 if the selector was empty, or 2 if the response selector was syntactically incorrect. It doesn't check if the response really exists, or access the conferencing system in any other way. It is really just a different version of the next_int command.

read_resp
resp read_resp err

Read_resp reads the header for a response. It is usually run right after a next_resp. It takes the response number from the stack, and the item number from the item system variable. The this_item and read_item commands should previously have been called on the item. It sets the resp, date, date, authorname, authorid, authoruid, texttype, hidden, erased , and parentresp system variables to the values for the response. If the response does not exist, an error code of 1 is pushed, otherwise a 0 is pushed.

Read_resp calls may be done in any order, so that the responses may be read in any order, but the implementation is optimized for processing responses in sequence.

read_text
format read_text text

The read_text command may be called after a read_item or read_resp to fetch the corresponding item or response text, which is pushed onto the stack as a single string. If format is 0, it returns a plain text response (possibly converting an HTML response to plain text, if that is all that is stored). If format is 1, it returns an HTML response (if the response is stored as plain text, it runs it through expand and then encloses it in a <PRE> environment). If format is 2, it returns the raw text - that is it returns HTML for HTML responses and plaintext for plaintext responses, and does no postprocessing on them.

Read_text also marks the response as "seen" in the user's participation file, unless the blindfold variable is set to a non-zero value. It works just fine on hidden responses, though on erased responses it will return a lot of scribbling.

post_item
- post_item -

This creates a new item in the current conference. Input is taken from the system variables title, text, texttype, alias, id, uid, allowgraphics, hidden, and erased (although posting erased items would be strange). If texttype is "text/html", then the cleanhtml function is automatically called on the item text. On success, the variable item is set to the number of the new item.

post_resp
- post_resp resp_number

This appends a new response to the end if the item specified by the item system variable in the current conference. Input is taken from the system variables text, texttype, alias, id, uid, allowgraphics, parentresp, hidden, and erased. If texttype is "text/html", then the cleanhtml function is automatically called on the response text. If the item does not exist, an error code of 0 is pushed. If the expect_resp variable is set to a positive value which is less than the next response number, then -1 is returned and nothing is posted. Otherwise the number of the newly posted response is pushed.

mark_unseen
resp item mark_unseen err

This marks the given response of the given item to be the first unseen response of the item. It pushs a 0 on success, a 1 if there is no such item, and a 2 if there is no such response.

forget_item
item forget_item err

This marks the given item number as being forgotten in the user's participation file. With Picospan, if the item has never been read, it has the odd side effect of marking the item text seen. It pushs an error code of 1 if there is no such item, or 0 if we succeed.

remember_item
item remember_item err

This unforgets the given item number. It pushs an error code of 1 if there is no such item, or 0 if we succeed.

hide_resp
flag hide_resp err

If the flag is true, this marks response resp of item item in the currently open conference as being hidden. If the flag is false, it unhides the selected response. Authors of responses can hide or unhide responses if the author_hide variable is true. Fairwitnesses can hide or unhide responses if the fw_hide variable is true. System administrators can always hide responses. The hide_resp command pushs a zero on success, a 1 if the response was erased or already set as designated, and a 2 if there is no such response. Responses in frozen items may only be hidden or unhidden if editfrozen is enabled.

erase_resp
- erase_resp err

This erases response resp of item item in the currently open conference. Only the author of the response, the fairwitness of the conference, or the system administrator can ever erase responses. Authors can only do so if the author_erase variable is true. Fairwitnesses can only do so if the fw_erase variable is true. The command pushs a zero on success, a 1 if the response was already erased, and a 2 if there is no such response. If a censored log file exists, a copy of the erased text will be saved there, together with information about who censored it. Responses in frozen items may only be erased if editfrozen is enabled.

edit_resp
- edit_resp err

This replaces the text of resp of item item in the currently open conference with new text given by the text and texttype system variables. The author's alias is reset to the value given by the alias system variable. Editting an erased item unerases it. The previous text is logged to the censor log, if censor logging is enabled. Only the author of the response, the fairwitness of the conference, or the system administrator can ever edit responses. Authors can only do so if the author_edit variable is true. Fairwitnesses can only do so if the fw_edit variable is true. The command pushs a zero on success, and a 2 if there is no such response or if the item is frozen, and 3 if you lack the proper access to edit the response. Responses in frozen items may only be edited if editfrozen is enabled.

freeze_item
flag freeze_item err

If the flag is true, this marks item item in the currently open conference as being frozen. If the flag is false, it thaws the selected item. You must be the author of the item or a fairwitness to be able to do this, and the item author can do it only if the variable author_freeze is true. The command pushs a zero on success, a 1 if the item was already frozen (or thawed), a 2 if there is no such item, or a 3 if you are not the fairwitness or item author.

kill_item
- kill_item err

This kills item item in the current conference. Items may be killed by the fairwitness, or by the item's author if it has not been responded to and author_kill is true. It pushs a zero on success, a 2 if there is no such item, or a 3 if you do not have permission to kill the item.

link_item
conf item link_item newitem 0
conf item link_item err

This creates a new item in the current conference which is a link to the named item in the named conference. Only fairwitnesses may link items. Items may not be linked from private conferences except by conference administrators. It pushs the new item number and a zero error code on success, a 1 if there is no such conference, or the conference is private, a 2 if there is no such item in the source conference, or a 3 if you do not have permission to link the item.

retire_item
flag retire_item err

If the flag is true, this marks item item in the currently open conference as being retired. If the flag is false, it unretires the selected item. You must be the author of the item or a fairwitness to be able to do this, and the item author can do it only if the variable author_retire is true. The command pushs a zero on success, a 1 if the item was already retired (or unretired), a 2 if there is no such item, or a 3 if you are not the fairwitness or item author.

retitle_item
newtitle retitle_item err

This changes the title of item item to the given string. You must be the author of the item, a fairwitness of the conference, or and administrator to be able to do this, but the item author can do it only if the variable author_retitle is true, and the fairwitness can do it only if the variable fw_retitle is true. The command pushs a zero on success, a 1 if the given title is blank, a 2 if there is no such item, or a 3 if you do not have the proper access to perform this operation. Frozen items may only be retitled if editfrozen is enabled.

first_partic
user first_partic lastaccess user 0
user first_partic 1

Start a scan through the list of participants in the current conference. To start from the beginning of the list, pass in the empty string. Otherwise, the first argument off the stack is the login name of a participant to start scanning after (so that the participant returned will be the successor of that participant). On success, a user name and the time that that user last read a new response in the conference is returned. If there are no particpants or if mayread is not true, then a code of 1 is pushed.

Note: Scanning participants can be extremely slow.

next_partic
- next_partic lastaccess user 0
- next_partic 1

Continue a scan of the participants of the current conference. first_partic must have been called before the first call to next_partic. There after, successive calls to next_partic return successive particpant's and the last time they read a response in the conference. When the last particpant has been read or if mayread is not true, an error code of 1 is returned.

Note: Scanning participants can be extremely slow.

new_conf
confname parentdir listit new_conf error

Create a new conference. Only conference administrators can use this command. Confname is the internal name of the conference, which must be all lower case, and which must be different from any existing conference. The conference will be stored in the directory whose full path name is given by parentdir. If parentdir is given as (), then it defaults to bbsdir. If listit is true, an conflist entry will be made in the same name, so that it can be joined by that name. This does not add the conference to the menu of conferences. On error, an error message string is pushed. On success, a null string is pushed.

del_conf
confname del_conf -

Delete a conference, referenced by its internal name. This deletes the conference directory and all of its conflist entries. It also deletes all user's participation files for the conference (except if unix accounts are being used). It does not delete any conference menu entries.

Built-in Variables

Backtalk has a large number of built-in variables that perform predefined roles, or whose values are set by the Backtalk interpreter.

Some variables are protected, so the user cannot change their values except in the config.bt script. Furthermore, some protected variables are tagged as constants, which means that they not only cannot be changed outside of the config.bt script, but they will have the same value everytime Backtalk is run. The Backtalk compiler will hard-code references to all built-in variables so that the system dictionary never has to be searched at run time, and it will hard-code values of all constants.

Conferencing Variables

There are a number of built-in variables that are used to pass information in and out of the conferencing commands.

alias
(string) The full name to be attached to your posts in the currently open conference. This is loaded from your participation file by the open_conf command and is an input to the post_resp, post_item and edit_resp commands.

allowgraphics
(boolean) If set true, the HTML <IMG> is allowed in HTML responses. This allows images to be inserted in-line in items and responses. If set false, all <IMG> tags are automatically stripped out by the post_item, and cleanhtml commands.

anonymity
(integer) This controls the visibility users names to other names. There are two kinds of names involved. First, it controls the visibility of the aliases attached to each posting and response, second it controls the visibility of the "real" full name field in the user database. Possible values are:
anonymity aliases can be seen by: real full names can be seen by:
0everyone.everyone.
1authenticated users only. authenticated users only.
2fairwitnesses of the current conference only. admins and members of the gradm group only.
3admins only.admins only.
The mayseealias and mayseefname variables will automatically be set to indicate the access available to the current user.

amadm
(boolean) True if you are a conference administrator. This implies amfw in all conferences, and gives you the power to use the selectuser command.

author_edit
(boolean) If this is true, users may edit responses they entered. This is a system constant, set in config.bt.

author_erase
(boolean) If this is true, users may erase responses they entered. This is a system constant, set in config.bt.

author_hide
(boolean) If this is true, users may hide or unhide responses they entered. This is a system constant, set in config.bt.

authorid
(string) This is the login id (or equivalent) of the author of an item or response. It is set by read_item and read_resp.

author_freeze
(boolean) If this is true, users may freeze or thaw items they originally entered. Fairwitnesses can always do this. This is a system constant, set in config.bt.

author_kill
(boolean) If this is true, item authors may kill their own items, at least until someone responds to it. Fairwitnesses can always kill items in their conferences. This is a system constant, set in config.bt.

authorname
(string) This is the full name of the author of an item or response. It is set by read_item and read_resp.

author_retire
(boolean) If this is true, users may retire or unretire items they originally entered. Fairwitnesses may always retire or unretire items. This is a system constant, set in config.bt.

author_retitle
(boolean) If this is true, users may retitle items they originally entered. Fairwitnesses can do this if fw_retitle is set, and conference administrators can always do so. This is a system constant, set in config.bt.

authoruid
(integer) This is the uid number (or equivalent) of the author of an item or response. It is set by read_item and read_resp.

bbsdir
(string) Full pathname of the bbs directory. It is defaulted to a sensible value. This is only used to expand any percent-signs in the conflist, so it is used by open_conf.

blindfold
(integer) If non-zero, then read_text won't mark responses seen when it reads them.

conf
(string) The name of the current conference. This can be set directly by the user, or by the next_conf operator. This is an input to the open_conf operator.

confdir
(string) The full path name of the directory where the current conference is stored. This is set by the open_conf command. You can also find the directory path of a conference by calling conf_dir, but that does not change this variable.

conflist
(string) Full pathname of the conflist directory of conference. This has a default value set at compile time, but can be overridden from the config.bt file. This is used by the open_conf operator.

conftitlelist
(string) Title of the conference. This is usually a few words that fit into "The _______ Conference". This is output by the open_conf operator which gets it from the conference config file if it is there, or uses the conf variable if it isn't.

cpass
(string) This is the conference password supplied by the user. It is an input to open_conf, but is only used if the conference is password protected.

csel
(string) This used to be an input to the next_conf function but isn't any more, so it should probably be deleted.

date
(time) This is the entry date of an item or response. It is set by read_item and read_resp.

dbtype
(string) This may be set to (yapp) or (picospan) to indicate that the conferences are stored in a format consistent with Yapp or Picospan. It is usually set in the config.bt file.

editdate
(time) This is the date an item or response response was last edited. If it has not been edited, it is zero. It is set by read_item and read_resp.

editfrozen
(boolean) If this is enabled in the config.bt file, then it is legal to hide, show, erase, retitle, or edit responses in frozen items. Traditionally this is not possible in Picospan, so this defaults off.

erased
(boolean) This is true if the current item or response text is erased. It is set by read_item and read_resp and it is an input to post_item and post_resp.

expect_resp
(integer) If this is set to a positive, non-zero value before running the post_resp command, then the value is taken as the expected response number. If the post_resp command determines that, if posted, the new response would have a larger response number, it will abort and return a -1 error code. This allows the posting script to warn the user than another response has slipped in, so the user can be given an opportunity to edit the item before posting it.

favicon
(string) Certain browsers (IE and Konquerer) like requesting something called 'favicon.ico' from every site they hit. Normally Backtalk ignores any requests for templates called 'favicon.ico' but if you'd actually like to set an icon for your Backtalk site, generate an appropriate 16x16 .ico image file, and set the favicon variable to the full pathname of your file in the config.bt file. It isn't useful to set this in any other script, since it will be too late by the time any other script is run.

fishbowl
(boolean) The current conference is a fishbowl conference, and only users in the ulist or glist (if userlist is true) or who can give the password (if secret is true) will be able to post, though all may join with read-only access. This is set by the open_conf function.

forgotten
(boolean) This is true if the current item has been forgotten by the user. This is set by this_item.

frozen
(boolean) This is true if the current item is frozen. This is set by this_item.

fw_edit
(boolean) If this is true, fairwitnesses may edit individual responses to items in their conferences. They cannot edit responses in linked items. This is a system constant, set in config.bt.

fw_erase
(boolean) If this is true, fairwitnesses may erase individual responses to items in their conferences. They cannot erase responses in linked items. This is a system constant, set in config.bt.

fw_hide
(boolean) If this is true, fairwitnesses may hide or show individual responses to items in their conferences. They cannot erase responses in linked items. This is a system constant, set in config.bt.

fwlist
(string) A comma-separated list of the fairwitnesses for the current conference. This is set by the open_conf command.

fw_retitle
(boolean) If this is true, fairwitnesses may change the titles of items in their conferences. Conference administrators may always retitle items. This is a system constant, set in config.bt.

gid
(integer) This is the current user's group id number. It is set by Backtalk before the execution of the script. It may be used to decide which files are readable to a user on some installations. If there is no identifiable user or group ids are not used, it is set to -1.

hidden
(boolean) This is true if the current item or response text is hidden. It is set by read_item and read_resp and it is an input to post_item and post_resp.

homedir
(string) The user's home directory. This is initialized before executing the script. It is set to null if no there is no validated user. It is used to find participation files.

id
(string) The login id (or equivalent) of the current user. This is automatically set by Backtalk before the execution of any script. It is an input the to post_item and post_resp commands. If there is no identifiable user, id is set to a null string.

item
(integer) Current item number. This can be set by this_item or by the programmer and is an input to read_item, read_resp, post_resp, kill_item, hide_resp, edit_resp, erase_resp, mark_unseen, and probably a lot of others that slipped my mind.

lastdate
(time) This is the date upon which the latest response was entered into the current item. This is set by this_item.

linkdate
(time) This is the date upon which the current item was linked into the current conference. For unlinked items, this is the creation date. This is set by this_item.

linked
(boolean) This is true if the current item is a linked item. This is set by this_item.

maxitem
(integer) The number of the last item in the current conference. This is set by the open_conf command.

maxread
(integer) The number of the last response which the user has read in the current item. This is set by this_item.

maxresp
(integer) The number of the last response in the current item. This is set by this_item.

mayedit
(integer) A flag indicating whether the user has the power to edit the text of the current response. It is 0 if he can not, 1 if he can do so because he is the author, and 2 if he can do so because he is the fairwitness or conference administrator. This is set by read_item and read_resp.

mayerase
(integer) A flag indicating whether the user has the power to erase the text of the current response. It is 0 if he can not, 1 if he can do so because he is the author, and 2 if he can do so because he is the fairwitness or conference administrator. This is set by read_item and read_resp.

mayfreeze
(integer) A flag indicating whether the user has the power to freeze or thaw the current item. It is 0 if he can not, 1 if he can do so because he is the author, and 2 if he can do so because he is the fairwitness or conference administrator. This is set by read_item

mayhide
(integer) A flag indicating whether the user has the power to hide or show the text of the current response. It is 0 if he can not, 1 if he can do so because he is the author, and 2 if he can do so because he is the fairwitness or conference administrator. This is set by read_item and read_resp.

maykill
(integer) A flag indicating whether the user has the power to kill the current item. It is 0 if he cannot kill it, 1 if he can kill it because he is the author, and 2 if he can kill it because he is the fairwitness or conference administrator. This is set by read_item

maypost
(boolean) A flag indicating if you have write access to the current conference or item. You have write access if you are not anonymous, if the conference is writable for you, and if the item is not frozen. This is set by the open_conf, and this_item commands. If it is false, then post_item and post_resp will not work in this conference.

mayread
(boolean) A flag indicating if you have read access to this conference. This is set by the open_conf command. If it is false, none of the commands to read items and responses from a conference will work.

mayretire
(integer) A flag indicating whether the user has the power to retire or unretire the current item. It is 0 if he can not, 1 if he can do so because he is the author, and 2 if he can do so because he is the fairwitness or conference administrator. This is set by read_item.

mayretitle
(integer) A flag indicating whether the user has the power to retitle the It is 0 if he can not, 1 if he can do so because he is the author, and 2 if he can do so because he is the fairwitness or conference administrator. This is set by read_item

mayseealias
(integer) A flag indicating whether the user has the power to see the full names attached to responses. If false, the read_item command will always a null string in the authorname variable. It is set by the open_conf command based on the anonymity configuration variable.

mayseefname
(integer) A flag indicating whether the user has the power to see user biographic information. If false, the command returns a null string for the name of other users. It's setting is based on the anonymity configuration variable and the user's authentication status.

noskip
(boolean) A flag indicating whether the next_item command should skip items which have been retired or forgotten. It defaults to false.

parentresp
(string) This is used with Yapp-style response threading, where each response can be tagged as being a response to some other previous response. It is the number of the previous response that this item is to be considered a response to. It is an input to post_resp and edit_resp, and is returned by read_resp. In Picospan-compatible installations, this will always be zero.

particip
(string) This is the name of the current conference's participation file.

readdate
(time) This is the date upon which the user last read a response in the current item. This is set by this_item.

resp
(integer) This is the current response number. It is set by read_item and read_resp.

retired
(boolean) This is true if the current item is retired. This is set by this_item.

rsel
(string) This is the current response selector, indicating which responses of the current item are to be read. It can be (all), (new), (since) or a numeric selector. See the section on selector manipulation for details on the syntax.

secret
(integer) This is non-zero if the current conference has a secret password. It is one if the password has been given correctly, or two if it has not. If it has not mayread will be false. If the conference has no secret password, then it will always be zero. This is set by open_conf.

showforgotten
(integer) If this is zero, forgotten and retired items will be skipped by the next_item command. If it is one, forgotten and retired items will not be skipped. If it is two, unforgotten items will be skipped.

since
(time) When rsel is (since), this gives the date after which responses are to be displayed.

text
(string) This is the text of a response or item. It is an input to post_item, post_resp and edit_resp.

texttype
(string) This is the type of the current response or item text. Currently the only possible types are "text/plain" and "text/html". It is an input to post_resp, post_item and edit_resp. It is set by read_item and read_resp.

title
(string) This is the title of an item. It is set by read_item and is an input to post_item

uid
(integer) This is the current user's uid number (or an equivalent unique identifier). It is set by Backtalk before the execution of the script. It is an input the to post_item and post_resp commands. If there is no identifiable user, it is set to -1.

userlist
(boolean) The current conference has a user list restricting who may join. This is set by open_conf.

Miscellaneous Variables

There are several other built-in system variables that effect the system's behavior, but aren't directly related to conferencing.

allowanon
(boolean) True if Backtalk is configured to allow anonymous reading. If false, then the only script that can be run by unauthenticated users is the `welcome' script. This is a protected variable, set at compile time.

auto_recompile
(integer) Whenever you run a script, and the binary is missing, or was compiled with an older version of Backtalk, Backtalk will attempt to recompile it automatically. The auto_recompile variable controls some additional recompilation checks. If auto_recompile is set to zero, no additional checks are done. This is suitable for a very stable production installation, where we don't want to slow down script execution by making extra tests. If auto_recompile is set to one, a script will be recompiled if its binary is older than the config.bt file. This is suitable for systems where configuration changes are likely, but the scripts themselves will not be changed. Finally, if auto_recompile is set to two, a script will be recompiled if its binary is older than the config.bt file or any of the source files that were used in compiling it previously. This is suitable for systems where new scripts are actively being worked on.

Note that if auto_recompile was previously set to zero, changing it's value in the config.bt won't cause anything to recompile, because the change in config.bt won't be noticed. Just manually recompile any one script. This will recompile config.bt as a side effect, so the new value of auto_recompile will then be set.

canspell
(boolean) This constant is true the spellcheck command works in this installation. If it's false, the spellcheck will never find any misspelled words.

cgiquery
(string) The query string passed to backtalk. It's a sequence of "name=value" pairs separated by ampersands, with each name and value cgi-quoted. It's the same as the QUERY_STRING environment variable, except that it is even defined when the POST method was used.

copyright
(string) This is a string giving the copyright message for Backtalk.

exec_limit
(integer) This is similar to stack_limit, but limits the size of the execution stack instead of the operand stack. It also defaults to zero, which is to say, "no limit".

flavor
(string) This constant is set to the name of the subdirectory under scriptdir which contains the script currently being executed. The name always has a "/" slash character at the end of it. Normally the different subdirectories under the main Backtalk directory are for different versions of the interface. Thus flavor is useful for constructing url's of other scripts in same interface version without actually imbedding the name into the script, which would make it harder to link a single script into several different interfaces.

http_content_type
(string) This is the MIME type for the document which will be included in the HTTP headers that Backtalk automatically generates before your first output statement. Its default value, (text/html) can be changed to any other MIME type. To have any effect, this must be done before the first print, pr, or dumpstack command.

http_expires
(time) This is the expiration time that Backtalk will put in the HTTP headers that it automatically generates before your first output statement. The expiration time sets an upper limit on how long the user's browser may keep a copy of your output in cache. If it is zero, no expiration time is set (this is the default). Otherwise, it should be a time type, such as the one returned by the time command. If it is in the past, the browser will not cache this document. To have any effect, this must be done before the first print, pr, or dumpstack command. It cannot be combined with the http_no_cache command, which always forces an expiration date in the past.

http_headers
(boolean) This is a boolean that controls whether Backtalk generates HTTP headers before the first output from your script. If true (the default), it does so, using the information from the http_content_type, http_expires and http_location variables, and including all cookies set with the setcookie command. If it is false, no headers are generated. This is desirable if your script is not running as a CGI, or if you want to generate your own HTTP headers. To have any effect, this must be set before the first print, pr, or dumpstack command.

http_location
(string) If this is not an empty string (the default), then it gives a URL to redirect to. This will be included in the HTTP headers that Backtalk automatically generates with the first output statement. If this header is given, then instead of showing the rest of the output you generate, the browser should fetch the page whose URL is given. To have any effect, this must be set before the first print, pr, or dumpstack command.

http_no_cache
(boolean) This is a boolean that controls whether Backtalk generates HTTP headers intended to prevent the page from being cached in the browser. If true these will be included in the HTTP headers that Backtalk automatically generates with the first output statement. It defaults false, allowing caching. To have any effect, this must be set before the first print, pr, or dumpstack command.

loginlen
(integer) The maximum number of characters that may appear in a login ID.

loglevel
(integer) This determines the amount of logging the system does. Well, actually there are only two levels right now -- if loglevel is set to zero, no logging is done, if loglevel is set to anything higher, short two-line log entries are written for each transaction.

newuseropen
(integer) This system constant tells whether unauthenticated users can create user accounts. If it is 0, only users in the 'cfadm' and 'gradm' groups can create user accounts. If it is 1, anyone, even unauthenticated users, can create new user accounts, but those accounts will be created in an unvalidated state, so they can't be used until an administrator validates them. If it is 2, then all users can create accounts, and the accounts will be instantly ready to use.

nopwedit
(integer) This constant is set to be true in installations where the changename, changepass, changegroup, removeuser and validate do not work because the system is set up to use the Unix passwd file as the user database. You could change the value of this constant with a defconstant command, but doing so wouldn't change the behavior of those functions.

progname
(string) The name Backtalk was invoked under. This is only the final element of the full path name. If you have multiple versions of Backtalk installed, this lets you be sure to direct future queries to the same version. The environment variable SCRIPT_NAME gives the full path from the URL.

scriptdir
(boolean) The full path of the directory where Backtalk scripts are kept. Backtalk will change directories to the compiled-in value of this variable before attempting to run the config.bt script, which should be in that directory. The config.bt script can change the value of this, in which case Backtalk will change to the new directory before trying to execute the user script, which should live someplace under that directory. Thus all path names given to include, stopped, or chain commands are relative path names from this directory.

sessions
(boolean) Was this Backtalk installation built to use on-page login forms, cookies and sessions to track users? If false, the system is set up to use basic authentication. This constant can only be changed by recompiling backtalk.

spell_lang
(string) This selects the dictionary to use for spell checking. If Backtalk was configured to use international ispell, then it is the name of the dictionary, just as would be given with the "-d" option. If this is defined as (), then the default language will be used.

stack_limit
(integer) Normally, the size of the operand stack may grow until the system runs out of memory and crashes ignominiously with a core dump (I guess we should start checking all mallocs). But if stack_limit is set to a positive integer value, the system will die cleanly when the stack size exceeds that value. By default, it is set to zero, which means there is no limit.

timezone
(string) If this string is set to a null string, the ctime command reports times and dtime interprets times using the host machine's default time zone. (This is the default.) However, if it is set to a standard unix timezone string, such as the ones used in the TZ environment variable, like "US/Eastern" or "EST5EDT", then that time zone will be used instead.

urlarg
(string) If there is a colon (:) in the extra path info part of a Backtalk URL, Backtalk interprets the part before the colon as the path name of the script file to execute, and puts the part after the colon into the urlarg variable. This is meant as an alternative to the standard cgi argument passing for applications where a good-looking url is desirable, but you can do both.

version
(string) This is a string giving the name and version number of the Backtalk interpretor.

Regular-Expression Syntax

Backtalk's regular expressions mostly comply with POSIX 1003.2. They are normally entered in double angle brackets, with optional flag characters after the closing bracket, that is: "<<expression>>flags.

The rules for regular expressions are as follows:

  1. It consists of one or more branches separated by vertical bars ("|"). It matches anything that matches one of the branches.
  2. A branch is a concatination of one or more pieces. It matches a match for the first, followed by a match for the second, etc.
  3. A piece is an atom possibly followed by a star ("*"), a plus ("+"), a question mark ("?"), or a bound.
    • An atom followed by a star ("*") matches 0 or more consecutive matches of the atom.
    • An atom followed by a plus ("+") matches 1 or more consecutive matches of the atom.
    • An atom followed by a question mark ("?") matches 0 or 1 consecutive matches of the atom.
    • A bound may consist of a decimal integer, i, between 0 and 255 in curly braces ("{" and "{"). An atom followed by this type of bound matches a sequence of exactly i matches of the atom.
    • A bound may consist of a decimal integer, i, between 0 and 255 followed by a comma and enclosed in curly braces. An atom followed by this type of bound matches a sequence of i or more matches of the atom.
    • A bound may consist of two decimal integers, i and j, between 0 and 255 separated by a comma and enclosed in curly braces. The first may not exceed the second. An atom followed by this type of bound matches a sequence of between i and j matches (inclusive) of the atom.
  4. An atom is either
    • a regular expression enclosed in parentheses ("(" and ")") which matches the regular expression.
    • empty parenthesis like "()", which matches the null string.
    • a caret ("^") which matches the null string at the begining of the line.
    • a dollar sign ("$") which matches the null string at the end of the line.
    • a backslash ("\") followed by one of the following characters, which matches as described:
           \a     a control-G bell character
      \ba control-H backspace
      \fa control-L formfeed character
      \na control-J newline character
      \ra control-R carriage return character
      \ta control-I tab character
      \va control-K vertical tab character
      \\a backslash
    • a backslash ("\") followed by any other character, which matches that character.
    • a bracket expression, as described below.
  5. a bracket expression is a list of characters enclosed in square brackets ("[" and "]") which normally matches any single character from the list. If the list begins with a caret ("^") it matches any single character not in the rest of the list.

    If two characters in the list are separated by a dash ("-") this is shorthand for the full range of characters between those two (inclusive) in ASCII.

    A backslash followed by one of the character in the table list above are treated as the corresponding characters. Otherwise backslashes are ignored inside brackets. Backslashs do not escape characters like "[", "[" and "-" - they still have their special meanings even if preceded by a backslash. To include a bracket inside brackets, make it the first element (after the caret if there is one). To include a dash inside brackets, make it the first or last element.

    If "[." and ".]" appear inside a bracket expression, the the enclosing sequence is treated as a single letter. Thus "[ [.&nbsp;.]\t]*" would match any sequence of spaces, tabs and "&nbsp;" and sequences.

    If "[:" and ":]" appear inside a bracket expression, they enclose the name of a character class. Character classes are:
         alnum     letters and numbers
    alphaletters
    blankspace or tab
    cntrlcontrol characters
    digitdigits
    graphprintable, non-space characters
    lowerlower case letters
    printprintable characters including spaces
    punctprintable characters which are not spaces, letters or numbers
    spacespaces, vertical and horizontal tabs, formfeeds, newlines, and carriage returns
    upperupper case letters
    xdigithexidecimal digits
    In addition "[:<:]" and "[:>:]" match the null strings immediately before or after words.

If a regular expression could match at more than one place, it matches the one that starts first. If it could match different lengths, it matches the longest.

The following flags may be given:

i
Ignore case. Upper and lower case letters are treated as identical.
m
Multiline. Let "^" and "$" match against newlines internal to a pattern, not just the beginning and ending of the pattern.

Alphabetical Index

! command
' command
* command
+ math command
+ string command
- command
/ command
[ command
] command
` command
~ command
- A -
abs command
alias variable
allowanon variable
allowgraphics variable
aload command
amadm variable
amfw variable
and command
anonymity variable
asort command
author_edit variable
author_erase variable
author_freeze variable
author_hide variable
author_kill variable
author_retire variable
authorid variable
authorname variable
authoruid variable
- B -
band command
bbsdir variable
begin command
blindfold variable
bor command
break command
browser command
- C -
cache_conflist command
call command
cap command
caps command
cgiquery variable
cgiquote command
chain command
changegroup command
changename command
changepass command
chomp command
cleanhtml command
clear command
cleartomark command
clip command
close_conf command
conf_alias command
conf_bull command
conf_dir command
conf_index command
conf_login command
conf_logout command
conf_new command
conf variable
confdir variable
conflist variable
conftitle variable
constant command
continue command
copy command
copyright variable
count command
count_sel command
counttomark command
cpass variable
csel variable
ctime command
cvi command
cvn command
cvs command
cvt command
cvscol command
- D -
date variable
dbtype variable
dec command
def command
default command
defconstant command
defined command
del_conf command
newgroup command
newgroupmem command
dfltgroup command
dtime command
dumpstack command
dup command
- E -
editdate variable
editfrozen variable
edit_resp command
end command
eq command
erase_resp command
erased variable
exch command
exec command
exec_limit variable
exists command
expand command
expect_resp variable
- F -
favicon command
filedate command
firstuser command
fishbowl variable
flavor variable
for command
forall command
forget_item command
forgotten variable
freeze_item command
frozen variable
fw_edit variable
fw_erase variable
fw_hide variable
fw_retitle variable
fwlist variable
- G -
ge command
get command
getcookie command
gid variable
grep command
groupid command
groupname command
groups command
gt command
- H -
halt command
hidden variable
hide_resp command
homedir variable
http_content_type variable
http_expires variable
http_headers variable
http_location variable
http_no_cache variable
- I -
id variable
if command
ifelse command
in command
inc command
include command
index command
ingroup command
inlist command
in_sel command
item variable
- J -
jump command
- K -
kill_item command
- L -
lastdate variable
last_in_conf command
le command
length array command
length string command
line command
link_item command
linkdate variable
linked variable
loadvar command
loginlen variable
loglevel variable
loop command
lt command
- M -
mark command
mark_unseen command
maxitem variable
maxread variable
maxresp variable
mayedit variable
mayerase variable
mayfreeze variable
mayhide variable
maykill variable
maypost variable
mayread variable
mayretire variable
mayretitle variable
mayseealias variable
mayseefname variable
mod command
- N -
ne command
neg command
new_conf command
newgroup command
newgroupmem command
newuser command
newuseropen variable
next_conf command
next_int command
next_item command
next_resp command
nextuser command
nopwedit variable
noskip variable
- O -
open_conf command
or command
- P -
parentresp variable
parse command
particip variable
pop command
post_item command
post_resp command
pr command
print command
progname variable
put command
- Q -
quote command
- R -
rand command
read command
read_item command
read_resp command
read_text command
readable command
readdate variable
remember_item command
removeuser command
repeat command
replace command
resign_conf command
resp variable
retire_item command
retired variable
retitle_item command
rev_sel command
roll command
rsel variable
- S -
savevar command
scriptdir variable
search command
secret variable
select command
selectuser command
sessions command
setcookie command
showforgotten variable
showopt command
since variable
spellcheck command
spell_lang variable
split command
srand command
stack_limit variable
stop command
stopped command
store command
substr command
- T -
text variable
texttype variable
this_item command
time command
timeout command
timezone variable
title variable
- U -
uid variable
undef command
unhtml command
urlarg variable
userinfo command
userlist variable
- V -
validate command
version variable
- W -
while command
wrap command
writable command
write command
- X -
xdef command
xdefconstant command
- Z -
ztime command

backtalk@hvcn.org Mon Jul 23 14:36:14 EDT 2001