Game Courier Developer's Guide

Arrays

An array is a collection of values that are grouped together. Typically, they have the same root address, but each has its own subaddress. Here's an example:

set ra (This is an array of words);
printr ra;

This produces the following output:

Array
(
    [0] => This
    [1] => is
    [2] => an
    [3] => array
    [4] => of
    [5] => words
)

You'll see that each element of the array has a key and a value. The key appears in brackets, and the keys in this array are all integers in increasing order from zero. This is the default behavior when you don't explicitly specify the keys. You may generally use any positive integer or alphanumeric string as a key. For example,

set ra.9 Queen;
setelem ra piece Knight;
set ra.3 Bishop;
printr ra; 

This produces the following output:

Array
(
    [9] => Queen
    [piece] => Knight
    [3] => Bishop
)

It is best to not use such disorganized arrays, though. It is better to use one of two types of arrays. One is the sequentially, numerically indexed array. This kind of array keeps things in a specific order that is visible in the names of the keys. The other is an associative array. This uses alphanumeric strings for keys. To give one example, the $originalpieces array for Chess looks like this:

Array
(
    [r] => 2
    [n] => 2
    [b] => 2
    [q] => 1
    [k] => 1
    [p] => 8
    [P] => 8
    [R] => 2
    [N] => 2
    [B] => 2
    [Q] => 1
    [K] => 1
)

The following commands are specifically for arrays:

Note that setelem is no longer needed, but it is retained to not break old code. It is now possible to refer to an array element with a single variable. Just use a period to separate the array's name from the name of the array element. For deeper arrays, just add more element names with a period between each one and its parent array. In each case, the array's name goes to the left of the array element's name. Unlike variable names, which must start with an alphabetic character, array elements may be entirely numeric. Here is an example that uses the set command instead of the setelem command:

set ra (This is an array of words);
print list #ra; // prints "This is an array of words"
echo #ra.5; // prints "words"
set ra.2 a;
set ra.3 series;
print list #ra; // prints "This is a series of words"

Variable Scope

For the sake of being able to reuse variable names in different subroutines, the same variable name can be used for different variables within different scopes. Even if you were careful to give all variables unique names, recursive subroutines would still require the use of scoping. Scope can differ in width, and it can differ over whether it is made narrower dynamically or lexically.

The widest scope belongs to global variables. These last until the end of the program, and as long as they have no competition for the same name, they are visible to all parts of the program. When two variables with overlapping scopes have the same name, the one with narrower scope will be chosen over the one with wider scope. Local scopes are strict subsets of the global scope. So, when you have a local variable and a global variable with the same name, the global one will be invisible. But when the local scope is closed, the global variable will become visible again. Here's an example:

set v 5; // Creates a global variable.
set x 7; // Creates another global variable.
echo #v; // Prints 5.
echo #x; // Prints 7.
do: // The do loop raises the scope
  local v; // Creates a local variable called v
  set v 8; // Assigns 8 to this local variable.
  set x 9; // Assigns 9 to the global variable x.
  echo #v; // prints 8
  echo #x; // prints 9
loop never; // Closes local scope
echo #v; // prints 5
echo #x; // prints 9

Besides dynamic scope, there is lexical scope, which depends on the name of the subroutine. Static scope differs from global scope by being connected to a subroutine rather than to the main program. Like global scope, it has a dynamic scope of 0, which means it never closes. Consider the following example:

set sv 55;
echo #sv;
sub stat lv:
  static sv 0;

  echo "Initial value of sv:" #sv;
  set sv + #lv #sv;
  echo "Modified value of sv:" #sv;
endsub;
gosub stat 6;
echo #sv;
gosub stat 6;
echo #sv;

If sv were a local variable, its value would be reset each time the subroutine was run. But a static variable keeps its value between subroutine calls. So, the first call to stat prints 0 and 6, but the second call prints 6 and 12. Before, in between, and after the subroutine calls, the value 55 is printed for sv.

Note that in GAME Code, two different subroutines never share lexical scope. If you create one subroutine within another subroutine, it has no significance, and the two subroutines have no special relationship with each other. In GAME Code, lexical scope behaves as if you created all your subroutines at the global scope.

Static and local scope each differ from global scope in one respect, but each is like global scope in one respect. While static scope is limited to a specific subroutine, it shares with global scope the feature of never closing. While local scope can close, it shares with global scope visibility in higher dynamic scopes. There is one more type of scope, which combines the two respects in which local and static scopes differ from global scopes. A my scope is tied to a specific subroutine, and it closes when the subroutine closes. This is the narrowest of scopes. It has greater precedence than other scopes, and it is useful when a variable will not be needed outside the subroutine, and calls to the same subroutine do not need to remember its value.

When different variables have the same name, GAME Code recognizes my variables first, static variables second, local variables third, with precedence given to more local variables, and global variables last. By default, any variable passed as a parameter of a subroutine is local to the subroutine, and any new variable is global. To use static, my, or other local variables within a subroutine, they must first be defined by the appropriate command:

Commands for Variables

Here are the commands for reading, setting, and creating variables.

Nullary operators

args

Returns an array of the remaining arguments passed to the function. This will not include any arguments whose values have already been passed to named parameters. If you're passing arguments to numeric placeholders instead of named parameters, its behavior may be screwy, and you should not rely on it. This is probably most useful when you're not using parameters or placeholders, and you want to allow a function to process any number of arguments.

baseurl

Returns the baseurl of the Game Courier script

best2drop

Searches a player's inhand area for the best piece to drop, based on values given to pieces in the pieceval global array. It favors higher valued pieces. This was designed for use with Hostage Chess, though it may have other applications, since it searches the starpath, which is used in any game with drops.

best2free

Searches the opponent's prison for the most valuable hostage that may be freed. The prison is defined in the prison global array. This was designed for use with Hostage Chess and may have little application to other games, since most games do not include a prison.

boardflags

Returns a comma-separated sorted list of all spaces with a flag set. Useful for recording the position of each move to enforce 3-times repetition rule.

capture

This indicates whether the last move was a capture. Equivalent to "nor == old @ == old void". Nota Bene: This operator is useful only for code that evaluates a move after the move has been made. If you need your code to evaluate potential moves, you should use the empty operator to test whether your destination is empty. If you need your code to evaluate both past and potential moves, you need to use something like this: cond empty #0 capture (not empty #1), where #0 is the origin and #1 is the destination. If the piece has just moved, its origin will be empty, and capture should be used. If the piece hasn't moved, no capture has been made, and your code will need to check for potential capture by checking the contents of the destination.

captured

Returns the last piece captured. Returns @ when the last move was to an empty space. Returns - when it was to a non-space.

capturedpieces

Calculates and returns an associative array of the pieces currently on the board. Each piece label is a key, and the value is an integer indicating how many of that piece have been captured. It does not include any keys for uncaptured pieces.

capturedpieces

Calculates and returns an associative array of the currently captured pieces by subtracting the pieces on the board from the original pieces. Each piece label is a key, and the value is an integer indicating how many of that piece are on the board. It does not include any keys for pieces not on the board.

destination

Returns value of dest at the time the expression is evaluated. This is what you want in a function that needs this value, since dest would return its value at the time of function definition, not at the time the function is called.

excode

Returns the value of the expanded FEN code, which is sort of useless, because it is an array, and it is of the original position, not the current position.

false

Returns the boolean false value.

fencode

Returns FEN code for the current position.

flags

Returns an array of all flags.

hyphen

Returns a hyphen character.

lastfile

Returns the numeric index of the last file. This would be 7 for Chess, since 0 is the first file.

lastmoved

Returns the last piece to move. Same as the substitution keyword moved, but returns the up-to-date value each time the expression is evaluated. Useful in functions, where this distinction is important.

lastrank

Returns the numeric index of the last rank. This would be 7 for Chess, since 0 is the first rank.

mln

Returns value of $mln. This value gets updated by moveindex between each move, and it serves as the index value for the array of moves. It keeps track of how far along the game is and may stand for move line. Internally, this index value is used to return the values for thismove and turn.

movenum

Returns the value of the $movenum variable, used to keep track of the number of the latest move in the game. This is not useful except in the Pre-Game or Post-Game code, since it does not increase from 0 to the latest move as the moves get processed. Instead, it starts out as the latest move number even at the beginning of processing the moves.

nil

Returns the @ symbol, used internally to identify the contents of an empty space.

nolower

Returns an array of all spaces whose piece labels are not entirely lowercase, retaining key values from original array. Useful for generating array of spaces with no Black pieces on them.

noupper

Returns an array of all spaces whose piece labels are not entirely uppercase, retaining key values from original array. Useful for generating array of spaces with no White pieces on them.

null

Returns a null string.

onlylower

Returns an array of all spaces whose piece labels are entirely lowercase, retaining key values from original array. Useful for generating an array of all spaces occupied by Black pieces.

onlyupper

Returns an array of all spaces whose piece labels are entirely uppercase, retaining key values from original array. Useful for generating an array of all spaces occupied by White pieces.

opponent

Returns the userid of the opponent.

piececount

Returns a two-dimensional array where each key is the label for a type of piece in the game, and each value is how many there are of that piece on the board. When a game is programmed to change the pieces before the game actually begins, it is useful to set the system variable originalpieces to this at the end of the pre-game section. This will allow for accurate calculations of captured pieces without requiring the GAME Code program to handle this detail itself.

piecekeys

Returns an array of all piece labels recognized by Game Courier for this particular game. It should generally be the pieces on the board when the game began.

pieces

Returns an array of all spaces on the board with pieces.

pieceset

Returns the basename of the currently selected piece set.

screen

Returns the value of $screen, which holds the coordinate of the last piece used as a screen when the last hopping move was checked. A screen is the piece a hopping piece hops over to capture another piece.

spaces

Returns an array of all board coordinates. These are the keys of the $space array.

status

Returns the value of $status, a string describing the status of the game.

thismove

Returns the move entered by the player. This value changes from move to move within the same script, and it counts a move as the entire series of move primitives made by one player on a single turn. It is useful when you need to parse a move and handle each part separately for a multi-move variant. Checking whether it is null is useful for checking whether it is the beginning of the game. This value is determined by returning the move indexed to the current value of mln. It is set after the pre-move code and before the post-move code. So it cannot be used in the pre-move code to identify the current move.

time

Returns the current time, as in integer value of how many seconds haved passed since since January 1, 1970.

true

Returns the boolean true value.

turn

Returns the number of the current turn. Turn numbering begins with 1, and a whole turn contains one move by each player. The turn number is determined by returning the turn number indexed to the current value of mln. This value changes after running the pre-move code for the first player and before running the post-move code. So, to identify the current move, you should test it against the value for the previous turn in the pre-move code for the first player but against the value for the current turn in the pre-move code for the second player and in the post-move code.

user

Returns the userid of the user who is signed in.

void

Returns a -, which is used in the Forsythe code and the $space array to represent a space that is part of the representation of the board but does not officially belong to the board. This is needed to avoid writing the - in commands, since this character is also used as the operator for making moves, and its presence in a move indicates that it should not be evaluated as a command.

whitespace

ws

Outputs a space character.

Unary operators

abs

Returns the absolute value of the operand.

alias

Returns the alias of a piece or coordinate if there is one, or just the piece or coordinate if there isn't.

asort

Returns a sorted version of an associative array. The array will be sorted by values, but it will retain the same key for each value.

bitnot

Returns the bitwise not of the operand.

bits

Returns the minimum number of bits required to represent the operand.

chars

Returns an array of all the characters in a string.

check

Used in combination with target. Checks whether the operand matches the value previously set by target. If there is a match, it exits the expression with a value of true. It otherwise allows evaluation of the expression to continue but pushes nothing onto the output stack. Target and check are somewhat analogous to switch and case, but they work in an opposite way. While case allows execution of code to begin, check stops further execution of code. Target and check were designed for the purpose of optimizing the code required for checking for the presence of certain pieces at certain locations, most typically pieces that might be checking the King, giving a double entendre significance to the operator name.

chr

Returns ASCII character whose ordinal value is given. chr 45 is useful for putting a hyphen in a string that may be printed in messages.

color

Returns the color index of a given coordinate. The color index of a space is initially given in the Board field of a preset. It is an integer between zero and the total number of colors minus one, as defined in the Colors or Patterns field. The color index of a space may be changed with the recolor command.

const

Returns the value of the named constant.

count

Returns how many elements are in an array.

count_values

Returns an array keyed to the values of an array, with each element set to how many times its key appeared as a value in the original array.

dec

Returns the operand minus one.

dechex

Converts a decimal (base 10) numeral to a hexadecimal (base 16) numeral.

empty

Returns boolean value indicating whether space indicated by operand is empty. Interprets off-board spaces as not empty.

eval

When its operand is an array, it recursively calls the Polish notation calculator to evaluate it as a Polish notation expression. This is useful when you use parentheses to limit the arguments passed to an operator with variable arity.

even

Returns true if the number following it is even, false if it's not.

findinhand

Returns the location of the first piece it finds in-hand that matches the wildcard pattern or false if none found. Searches the inhand area, as defined by starpath, for a piece that matches the wildcard pattern passed to it.

file

Parses coordinate and returns number used to represent the file internally. These would 0 to 7 for Chess.

filename

If passed a coordinate, parses it and returns id used for the file. These would be a to h for Chess or 1 to 9 for Shogi. If passed an integer, it will return the file id with that integer as an index. For example, 0 would return a in Chess or 1 in Shogi.

flag

Returns the boolean value of the flag named by the operand.

flipcase

Flips the case of op1 from lower to upper or vice versa. Uses the same function as the flip command

flipimg

Returns the name of the image value used for the flipped version of a piece in the currently loaded piece set.

global

system

Returns the value of the named system variable. These are selected PHP variables used by Game Courier that GAME Code is allowed access to. This function will not work for $password.

hasalnum

Returns whether the string op1 has any alphanumeric characters.

hasalpha

Returns whether the string op1 has any alphabetic characters.

hasdigit

Returns whether the string op1 has any digit characters.

haslower

Indicates whether the string op1 has any lowercase letters.

hasupper

Indicates whether the string op1 has any uppercase letters.

hexdec

Converts a hexadecimal (base 16) numeral to a decimal (base 10) numeral.

inc

Returns the operand plus one.

int

Returns the integer value of the value passed to it. This is useful for converting binary, octal, decimal, and hexidecimal string literals to integers. When you normally enter a number, GAME Code treats it as a string literal. While decimal literals automatically get treated as numbers when needed, binary, octal, and hexidecimal literals do not. You can identify these with the appropriate prefix. Use 0b for binary, 0 for octal, and 0x for hexidecimal. Like the BASIC function by the same name, this will also convert floating point values to integers by chopping off anything past the decimal point. If you want to use it for rounding a value, you should add .5 to it first.

isalnum

Returns whether op1 is entirely alphanumeric.

isalpha

Returns whether op1 is made up entirely of alphabetic characters.

isconst

Returns true when the name that follows belongs to a constant, false otherwise. Used to test for the existence of a constant, even when the constant has a value of false, which just returning the value of the constant, as const does, would not catch.

isarray

Returns whether the argument is an array.

isconst

Returns whether the argument is the name of a defined constant.

isdigit

Returns whether op1 is made up entirely of digits.

isfunc

Indicates whether op1 is a function name

islower

Indicates whether string in operand is entirely lowercase.

isset

Indicates whether the name belongs to a set variable.

issub

Indicates whether op1 is a subroutine name.

isupper

Indicates whether string in operand is entirely uppercase.

invisible

Indicates whether a space is invisible. An invisible space starts with !. Other spaces are considered visible.

isvisible

Indicates whether a space is visible. An invisible space starts with !. Other spaces are considered visible.

keys

Returns an array of the keys to an array.

ksort

Returns a sorted version of an associative array that has been sorted by its keys.

lambda

Returns a lambda function given an array, string, or function.

literal

Returns an array literal if passed an array, or a function literal if passed a function name.

markedlegal

Indicates whether a move, described as a string, has been marked as legal with setlegal.

move

Returns the move with the provided index number.

neg

Returns negative of numeric operand.

natsort

Returns a sorted version of an array that has been sorted in natural order. Alphanumeric strings will be sorted in numeric order instead of in stricly alphabetic order. It will still be case sensitive, though.

neg

Returns the negative of a number. The same as - 0 number.

not

Reverses the boolean value of the expression.

odd

Returns true if the number following it is odd, false if it's not.

onboard

Indicates whether the indicated space is on the board. "onboard ##" is equivalent to "not equal space ## void".

ord

Returns ordinal value of given ASCII character.

onebits

Returns number of one bits in operand.

pieceimg

Returns the filename used for the image of a specific piece, as identified by its label.

rank

Parses coordinate and returns number used to represent the rank internally. These would be 0 to 7 for Chess.

rankname

If passed a coordinate, parses it and returns id used for the rank. These would be 1 to 8 for Chess, but they would be a to i for Shogi. If passed an integer, it will return the rank id with that integer as an index. For example, 0 would return 1 in Chess or a in Shogi.

realname alias

If the value passed to it is an alias, it returns the value that got assigned that alias. Otherwise, it returns the same value that got passed to it.

remove

Removes the piece at the specified location, replacing it with an empty space, the @ character. Returns the result of this operation, which is normally true.

reverse

Returns reversed array or string. Reverses order of elements in array or order of characters in string.

sign

Returns 1 if op1 is positive, 0 if it is zero, and -1 if it is negative.

space

Returns the value of the space whose coordinate is given. This may be a piece, @ for an empty space, or - for a non existant space.

string

When given an array, it concatenates all elements of the array into a single string. When given other input, it returns its string value.

strlen

Returns the length of a string.

target

Specifies which pieces to search for with check. To specify more than one piece, the pieces should be placed together in an array. This can be done with the array operator or by placing parentheses around them. Since the target variable is static, it can be set once, then used with recursively called user-defined functions. Since expressions are evaluated back-to-front, the target operator should appear after the check operators it is used with.

tolower

Converts string in operand to entirely lowercase.

toupper

Converts string in operand to entirely uppercase.

twinonfile

Given a coordinate, it checks whether the file occupied by the piece on that coordinate is occupied by another piece of the same type and color. Designed for enforcing the Shogi rule against dropping a Pawn on a file already occupied by a friendly Pawn.

type

Returns a string indicating the data type of the value passed to it. This uses the gettype function in PHP and will return the same values. The most common values will be boolean, integer, string, and array. Except for the keywords true and false, most literals will be strings, even if they look like numbers.

unique

Given an array, it returns an array where each value is represented only once.

urlencode

Returns an urlencoded version of a string.

var

Returns current value of user-defined variable. In your function definitions, it is important to use this for variables whose value may change after the function is defined. Prepending a variable name with # works only when a line is executed. So, if you do that in a function definition, the function will contain the value of the variable at the time the function was defined, which may not be its current value when the function is called later. Use this operator before the variable name when you want to guarantee that it will use the current value of the variable on each function call.

var_export

Returns the value of the PHP function val_export for a value.

Dual Unary/Binary operators

These can handle either one or two operands. For some logical operations, it takes only one operand to know whether it will be true or false. For example, x and y is false if x is false, no matter what y is. Likewise, x or y is true if x is true, no matter what y is. In contrast to these, xor, the exclusive or, always depends on the value of both operands and so cannot work with just one argument.

When the value of the sole operand is not enough to settle the value of the operation, it lets the expression continue without adding any new values to the stack. Behaving this way does not change the truth value of and or or, but it would sometimes change the truth value of nand or nor. Accordingly, nand and nor, which were once both included here, are now made to require two arguments.

When two operands are available, each logical operator just evaluates the logical expression with both values and adds the value to the stack. The expression breaking behavior of these operators is useful for avoiding unnecessary calculation and for breaking out of recursive functions. The unless and onlyif functions also work with one or two operands.

and

&&

With two operands, this returns true if both operands are true, false otherwise. When the operands are arrays, it evaluates op1 first, then evaluates op2 only if op1 turned out true. With only one value, exits the expression with a value of false when op1 is false; otherwise continuing to evaluate the expression when op1 is true. Because of this, the expressions and op1 op2 and op1 and op2 will give the same result. The latter is more efficient, because it will exit the expression early if op2 is false.

merge

Merges two arrays into a single array. This is here just in case it gets one array from a function that returns nothing (instead of an empty string) for its particular input.

or

||

With two operands, this returns true when either operand is true, false otherwise. When the operands are arrays, it evaluates op1 first, then evaluates op2 only if op1 turned out false. With only one value, it exits the expression with a value of true when op1 is true, otherwise continuing to evaluate the expression when op1 is false. Because of this, the expressions or op1 op2 and op1 or op2 will give the same result. The latter is more efficient, because it will exit the expression early if op2 is true.

onlyif

Allows evaluation of an expression to continue onlyif op1 is true. Breaks from an expression and returns the value of op2 (or op1 if no second operand is available) when op1 is false. Useful for recursion in user defined functions or for flow control in lambda functions.

unless

Allows evaluation of the expression to continue unless op1 is true. Breaks from an expression and returns the value of op2 (or false if no second operand is available) when op1 is true. Useful for recursion in user defined functions or for flow control in lambda functions.

trim

Trims whitespace off both ends of a string, or if given a second argument, trims a specific character off the ends of a string.

The following table lists the truth value returned for each pair of op1 and op2:

Binary operators

!==

Evaluate strict non-identity, which is true if either the value or the variable type is different.

<=

Less than or equal to comparison

>=

Greater than or equal to comparison.

<<

Left shifts op1 by the number of bits specified in op2. Equivalent to op1 times 2 to the power of op2.

>>

Right shifts op1 by the number of bits specified in op2. Equivalent to dividing op1 by 2 the number of times specified by op2, discarding the remainder each time.

base

Converts a base ten number to the specified base. The new base is given first as op1, then the number to convert as op2.

bitand

&

Returns the bitwise AND of the two operands. Every bit that is on in both operands is turned on in the result.

bitor

|

Returns the bitwise OR of the two operands. Every bit that is on in one or both operands is turned on in the result.

bitxor

Returns the bitwise XOR of the two operands. Every bit that is on in one operand and off in the other is turned on in the result.

char

Returns character number op2 from the string op1. The first character is number 0.

checkrhombus

Checks the legality of some kind of rhombus-shaped move, I guess. I don't remember writing this or for what kind of piece I wrote it for.

cmp

Returns 1 is op1 is greater than op2, -1 if op2 is greater than op1, and 0 if both are equal.

diff

Returns the array difference between two arrays using the PHP function array_diff().

direction C1 C2

Returns the direction of movement from coordinate C1 to coordinate C2. The direction is given in terms of north, south, east, and west. Technically, north is the direction of increasing rank values, and east is the direction of increasing file values. Generally, north is the forward movement for White, and east is movement to White's right. South is the opposite of north, and west is the opposite of east. The returned value is a string made up of one or more of the letters n, s, e, and w. Diagonal and angular directions are given with combinations of letters. Each diagonal or angular direction begins with either s or n. An angular direction may repeat the s or n one or more times. Then comes e or w. An angular direction may repeat this one or more times. Here are some examples: direction a1 h1 is n; direction a1 a8 is ne; and direction g1 d7 is nnw.

distance

Returns distance between two coordinates, measured as the least number of one-space moves it would take to reach one square from the other. Returned value will match the perimeter of op1 that op2 is found in, and vice versa.

div

/

Returns integer result of op1 / op2.

elem

Returns element op1 of array op2. If op2 is just the name of an array, it is assumed to be a root-level array. But op1 may also be a whole array. In this manner, elem may be used for finding values in multidimensional arrays. For example "elem elementone elem arrayone myarrayofarrays" would find $myarrayofarrays[$arrayone][$elementone].

equal

==

Returns boolean value of op1 == op2.

explode

Normally returns explode(op1, op2), using the PHP explode function. When op1 is empty, it returns an array of all the characters in a string.

fnmatch

Returns whether the wildcard pattern in op1 matches the string in op2.

gcd N1 N2

Returns the greatest common denominator of two numbers. This is the highest number that will evenly divide into both.

greater

>

Returns boolean value of op1 > op2.

hamming

Returns the hamming distance between two strings of the same length. This is the number of positions at which two strings are different. A string has a hamming distance of zero from itself. A coordinate normally has a hamming distance of 1 from any space in the same rank or file.

htmllink

Returns an HTML link with op1 as the URL and op2 as the text.

identical

===

Returns boolean value of op1 === op2, meaning they are equal and of the same type.

join

.

If op1 and op2 are both strings, it returns the concatenation of op1 and op2, with op1 first. If op1 and op2 are both arrays, it returns an array of every combination of each element in op1 concatanated with each element of op2 on its right. These are grouped by the element in op2. To switch this, just sort the array afterwards. If one operand is a string and the other is an array, it returns an array of all concatanations between the string and each element of the array that are joined in the same order as the two operands are given.

leftstr

Returns the first n characters of a string.

less

<

Returns boolean value of op1 < op2.

levenshtein

Returns the Levenshtein distance, a.k.a. edit distance, between two strings. This is the minimum number of insertions, deletions, and substitutions it takes to transform one string into the other.

max

Returns max(op1, op2), which is the value of whichever has the greater value.

min

Returns min(op1, op2), which is the value of whichever has the lesser value.

minus

-

Returns op1 - op2.

mod

%

Returns op1 % op2, which is the integer remainder of op1 / op2. More precisely, x mod y = x - floor(x / y)*y. When y is zero, PHP's % operator will return a division by zero error. But the same operator in GAME Code will return the value of x. Although the value of x/y may be undefined when y iz zero, the product of anything times 0 is 0, making the value of floor(x/y) irrelevant to the calculation. So, when op2 is zero, the division gets skipped, the value of floor(x / y)*y is taken to be zero, and when that is subtracted from x, the value is still x.

mult

*

Returns the product of op1 times op2, op1 * op2.

nand

This returns true if either operand is false, false if both are true. This is a shortcut for not and op1 op2, which by De Morgan's Law is equivalent to or not op1 not op2. When the operands are arrays, it evaluates op1 first, then evaluates op2 only if op1 turned out true. This previously worked with only one argument, but since "nand op1 op2" would not always equal "op1 nand op2", I dropped this usage after confirming that no one was using it this way.

nor

This returns true if neither operand is true, false if either is true. This is a shortcut for not or op1 op2, which by De Morgans Law is equivalent to and not op1 not op2. When the operands are arrays, it evaluates op1 first, then evaluates op2 only if op1 turned out false. This previously worked with only one argument, but since "nor op1 op2" would not always equal "op1 nor op2", I dropped this usage after confirming that no one was using it this way.

onfile

Returns whether there is a piece of type op2 on the file op1. Useful for evaluating potential Pawn drops in Shogi.

path

Returns an array of all coordinates for the shortest path of the smallest leaps in the same direction from op1 to op2, exclusive. The smallest leap will be calculated by dividing both the distance in ranks and the distance in files by their lowest common denominator. The number of leaps along the path from op1 to op2 will be equal to the lowest common denominator of their rankwise and filewise distances. The origin and destination spaces are not included in the path. When the shortest path is a single leap, the returned array will be empty.

plus

+

Returns the sum of op1 plus op2, op1 + op2.

pow

Returns the result of op1 to the power of op2.

rand

Returns a random number between op1 and op2.

range

Returns an array of all values from op1 to op2.

regmatch

Returns whether the regular expression in op1 matches the string in op2. The underlying function is preg_match in PHP.

revealed

Given two coordinates, this moves along the line between them from op1 until it reaches an occupied space or goes off the board. When it reaches an occupied space, it returns the coordinate of the space. When it does not reach an occupied space, it returns false. It is useful for finding a space from which there may be a revealed check by giving it the King's coordinate and the coordinate of a recently vacated space.

rightstr

Returns the last n characters of a string.

same

Does a case insensitive comparison of two strings, returning true if they are equivalent, false if they are not.

samecase

Returns true is both op1 and op2 are strings of the same case. Two strings are the same case when all alphabetic characters in both are all lowercase or all uppercase, or when both have alphabetic characters in both upper and lowercase, or when neither has any alphabetic characters. Some examples of strings in the same case include "k" and "e1", "P" and "Q", "aP" and "Ap", and "5" and "@".

search

Searches for op1 in array op2, returning the key for op1 in op2 if found. Otherwise returns false.

slope

Returns the slope between two coordinates, using the formula m = (x1-x2)/(y1-y2).

strstr

Searches for op2 in op1, returning position, starting with 0. Returns false if not found.

unequal

!=

Returns boolean value of op1 != op2.

union

Returns the union of two arrays, which is an array containing all the elements of both arrays. It appears to do the same thing as merge but with different code. When either value is not an array, it gets pushed onto the one that is an array, or if neither is an array, it returns an array of the two values.

xor

Returns the boolean value of op1 xor op2, which is true when they have different truth values, false when they are the same.

Binary/Ternary Operators

what

Given a coordinate and two numbers, returns the contents of the space that is op2 files and op3 ranks away from the space whose coordinate is given in op1. Instead of two numbers, it may be given a single logical direction, such as what a1 n. A logical path may also be used if placed in parentheses, such as what a1 (n n).

where

Given a coordinate and two numbers, returns the coordinate of the space that is op2 files and op3 ranks away from the space whose coordinate is given in op1. Instead of two numbers, it may be given a single logical direction, such as where a1 n. A logical path may also be used if placed in parentheses, such as where a1 (n n).

Ternary Operators

behindscreen

Given a coordinate and the dimensions of a single step away from the space, given in x y form, it rides away from the space one step at a time, hopping over the first piece found, then returning the label for the next piece found. Used to check whether a King is in check from a piece that captures by hopping, such as a Cannon.

checkmaxsteps

Checks whether a move made up of up to op3 steps from one adjacent space to another can go from op1 to op2.

checknsteps

Checks whether a move made up of exactly op3 steps from one adjacent space to another can go from op1 to op2.

cond

Returns op2 when op1 is true, op3 when op1 is false. Note that it will evaluate op3 and op2 before op1 unless they are encapsulated in parentheses. This is important to know if you intend to use cond in a recursive function. When both op2 and op3 are in parentheses, it will conditionally evaluate one or the other, depending upon the truth value of op1. Note that the expression that evaluates to op1 should not be in parentheses unless you want it to evaluate to true for anything but the empty set.

insight

Returns the id of the first piece that would be reached by riding from space op1 at op2 files and op3 ranks per step. When no piece is in sight, false is returned.

leaps

Given a coordinate and a distance given in x y form, it returns an array of every space that distance away from the space whose coordinate was given. For example, leaps h1 1 0 would return the array (g1 h2). The array may have as few as one space, leaps a1 1 1 or as many as eight, leaps e4 1 2. Used for generating an array of all spaces a piece may legally step one space to. Useful when generating possible moves while checking for stalemate.

near

The three arguments are coordinate, piece, and distance. Determines whether there is a certain type of piece within the distance from the coordinate. It will return the coordinate of one piece if there is one, and it will return false otherwise.

ray

Given a coordinate and a step given in x y form, it returns an array of every space that can be reached by one or more instances of that step. The step here is in a single direction.For example, ray e4 1 1 would return f5, g6, and h7 on a Chess board. Used for generating an array of all spaces a piece may legally ride to. Useful when generating possible moves while checking for stalemate and the game includes hopping pieces, such as the Cannon.

rays

Given a coordinate and a distance given in x y form, it returns an array of every space that distance away, or any multiple of that distance away, from the space whose coordinate was given. For example, rays e4 1 0 would return the array of spaces in the e file or 4th rank besides e4. The spaces in the array may come from as few as one direction of movement, as in rays a1 1 1, or from as many as eight directions of movement, as in rays e4 1 2. Used for generating an array of all spaces a piece may legally ride to. Useful when generating possible moves while checking for stalemate and the game includes hopping pieces, such as the Cannon.

ride

Given a coordinate and a direction away from it given in x y form, it returns an array of all empty spaces and the first occupied space found while moving away from op1 in the direction defined by op2 and op3.

str_replace

Returns the result of calling the PHP function str_replace on the three arguments provided. The first should be the string to search for, the second should be what to replace it with, and the third should be the string to search through.

substr

Returns the result of the PHP function substr. The first operand is he original string, the second is the start of the substring, and the third is the length of the substring. String normally start at 0. If the starting position is negative, it will count from the end. If the length is negative, it will cut off that many characters from the end of the string. If the length is 0, the rest of the string will be returned.

Tetrary Operators

checkahop

Checks whether the move from op1 to op2 was a legitimate hopping move, consisting of leaps of op3 files and op4 ranks. A hopping move must hop over one screen. This operation checks only in the direction described. Negative numbers may be used for op3 and op4 to reverse directions. Positive directions go from a1 to h8 in Chess.

checkaleap

Checks whether the move from op1 to op2 was a legitimate leap of op3 files and op4 ranks. This operation checks only in the direction described. Negative numbers may be used for op3 and op4 to reverse directions. For example, "or checkaleap 2a 3c -1 2 checkaleap 2a 3c 1 2" would check whether the move from 2a to 3c was one a White Shogi Knight could make.

checkaride

Checks whether the move from op1 to op2 was a legitimate riding move, consisting of leaps of op3 files and op4 ranks. This operation checks only in the direction described. Negative numbers may be used for op3 and op4 to reverse directions. For example, "checkaride 9a 9d 0 -1" would check whether the move from 9a to 9d was one a Black Shogi Lance could make.

checkgrasshop

Checks the legality of a Grasshopper move. The Grasshopper is a fairy piece that moves and captures by jumping to the space immediately after an occupied space.

checkhop

Checks whether the move from op1 to op2, or vice versa, was a legitimate hopping move, consisting of leaps of op3 files and op4 ranks, or of op4 ranks and op3 files. A hopping move must hop over one screen. This operation checks symmetrically in all directions. Negative values for op3 and op4 have no special meaning, because only their absolute values are used. For example, "checkhop a4 g4 0 1" would check whether this move was a legitimate move for a Cannon in Korean Chess.

checkleap

Checks whether the move from op1 to op2, or vice versa, was a legitimate leap of op3 files and op4 ranks, or of op4 ranks and op3 files. This operation checks symmetrically in all directions. Negative values for op3 and op4 have no special meaning, because only their absolute values are used. For example, "checkleap b8 c6 1 2" would check whether this move was a legitimate Knight move.

checklongleap

Checks the legality of a Longleaper move, a piece found in Ultima that can capture multiple pieces by leaping over them.

checkride

Checks whether the move from op1 to op2, or vice versa, was a legitimate riding move, consisting of leaps of op3 files and op4 ranks, or of op4 ranks and op3 files. This operation checks symmetrically in all directions. Negative values for op3 and op4 have no special meaning, because only their absolute values are used. For example, "or checkride d1 g4 0 1 checkride d1 g4 1 1" would check whether this move was one a Queen could make.

inrange

Returns the first piece that can be found by making up to op4 leaps away from op1, each leap defined as op2 files and op3 ranks away. Returns false if no piece was found. Similar to insight but for short-range pieces. Used to indicate whether the King is in check from a short-range rider. See the cwda include file, used for Chess with Different Armies, for an example of its usage.

voidleap

Checks the legality of a voidleap from op1 to op2 in a direction defined by op3 and op4. This is a one space move that may pass over void, i.e. nonspace, identified in Game Courier with a hyphen, -, for the piece value. This is for the Voidrider from Voidrider Chess.

voidride

Checks the legality of a voidride from op1 to op2 in a direction defined by op3 and op4. This is a move that may carry the piece's space across void to a void location or leap across void. This is for the Voidrider from Voidrider Chess.

Hexary Operators

checkatwostep

Checks whether a two step move from op1 to op2 could be made with the first step of op3 files and op4 ranks, and the second step of op5 files and op6 ranks. The first step should be to an empty space. This operation checks only in the direction described. Negative numbers may be used for op3 and op4 to reverse directions. For example, "checkatwostep e2 e4 0 1 0 1" would check whether a piece stepped foward two spaces, as a Pawn can on its first move in Chess.

checktwostep

Checks whether a two step move from op1 to op2 could be made with a first step of op3 files and op4 ranks, and a second step of op5 files and op6 ranks, or if it could be made with a first step of op4 files and op3 ranks and a second of op6 files and op5 ranks. For example, "checktwostep b1 c3 0 1 1 1" checks whether the move from b1 to c3 could be made by a Knight in Chinese Chess.

Multiple Arity Operators

These operators pop off a multiple number of arguments. When the first element on the stack is an array, some of them will pop off the array, base its calculations on the elements of the array, then push the result onto the stack. Otherwise, most of them use the entire stack for their calculations. Some use only the stack, and one, fn, pops off only as many as it needs.

aggregate

Runs a lambda function for each value of an array, or each following value if an array does not follow the lambda function. Builds and returns a sequential array of every non-empty result of running the lambda function. Unlike the filter function, this fills the new array with new values, and it does not preserve keys.

allequal

allfalse

alltrue

anyfalse (or nonetrue)

anytrue

If the value on top of the stack is an array, it is popped off, and the operation is performed on its elements. But if it is not an array, the operation is performed on every element in the stack, and the result replaces the old stack. allequal checks whether all elements of an array or stack are equal to each other. allfalse or nonetrue checks whether all elements are false. alltrue checks whether all elements are true. anyfalse checks whether any element is false. anytrue checks whether any element is true. Note that allfalse and anytrue always give opposite results for the same data, as do alltrue and anyfalse. Unlike the logical operators, these functions do not evaluate parenthesized expressions.

andsum

Does a binary AND on a set of integers and returns the result. They may be specified in an array or as a series of arguments.

array

Makes an array of all elements in the stack, empties the stack, then pushes the array onto the stack. Returns an empty array if no elements follow it. If the first value is a lambda function, it runs this on each element of the array or stack following it and returns an array of the values calculated from doing this.

assoc

Makes an associative array out of all the elements in the stack, empties the stack, then pushes the array onto the stack. Instead of using all elements as values, it alternates between using an element as a key and as a value. For example, "set qq assoc b B r R" should set qq equal to the array ("b" => "B", "r" => "R").

checkapath

Checks whether a piece may go along a specific unobstructed path from op1 to op2 according to a path given in an array as op3 or given as the remaining arguments. The path should be described as a series of paired numbers, the first number giving the number of files to move, and the second giving the number of ranks to move.

checkpath

Checks whether a piece may go along a symmetrically defined unobstructed path from op1 to op2 according to a path given in an array as op3 or given as the remaining arguments. The path should be described as a series of paired numbers, the first number giving the number of files to move, and the second giving the number of ranks to move.

filter

Filters an array by running a lambda function on every element and returning a new array of the elements that got a non-empty result from the lambda function. Unlike the aggregate function, this returns the original values of the array, and it preserves keys. If an array is not provided, it turns the remaining arguments into an array.

findpiece pattern [first|last] C1 ... Cn

Searches for the first or last piece in the given list of coordinates that matches the given wildcard pattern. The coordinates may be given as a list or as an array. Returns coordinate of found piece or false if piece is not found. If the first or last keyword is not specified, the default behavior is to find the first piece.

fn name arguments

The fn function calls a user defined function, specified by its name. The contents of the function determine how many arguments it requires. It pops off as many arguments as needed and pushes the result onto the stack. The function may be any Polish notation expression, even including other user defined functions. Recursive functions are possible with the onlyif or unless operators, but not with the cond operator.

fn (expression) arguments

When given an unnamed lambda function, it will run it just as it would a named function, though without a name, recursion will not be possible. For example fn lambda (+ * #0 #1 #2) 7 8 9 will multiply 7 and 8, add 9 to the product, and return the result, which is 65. It will also interpret an expression in an array as an unnamed lambda function. For example fn (* #0 #1) 5 7 will return 35. This allows you to create a function you will use in only one place without naming it. It also allows you to have the program construct functions before using them.

intersection

Returns the intersection of two arrays. The first array must be represented as an array. If the second argument is not an array, an array is made from the remaining arguments. So intersection (a b c d e f g h) (a e i o u) gives the same result as intersection (a b c d e f g h) a e i o u

isort

Does a case insensitive, natural sort on an array and returns the result. A natural sort lists numbers and alphanumerics in numeric order rather than strict alphabetical order. So, 9 comes before 10, for example. If an array is not provided, it turns the remaining arguments into an array and sorts them.

list

If given an array, it returns a space-separated string containing the elements of the array. Otherwise, it join all elements of the stack into a space-separated string, empties the stack, and pushes the new string onto the stack.

logleap from to ...

Determines whether a piece at from can leap to a space at to by moving in one of the logical directions that follow. Logical directions are defined by the map and link commands. This function can work for both simple leapers and lame leapers. A simple leaper requires a simple direction, while a lame leaper requires a series of directions inside a pair of parentheses. This series of directions gives a path the lame leaper must follow to get to its destination. Its path must be unblocked, but it cannot stop anyplace on its path before its destination. For the sake of efficiency, this function can take multiple directions or multiple sets of directions, and test them in turn until a legal move to to is found.

logleaps from directions

Using a coordinate of a space and a list of logical directions, this returns an array of the spaces that can be reached by moving in those directions. This is useful for finding the moves a piece may possibly take when checking the effects of possible moves in a subroutine for checkmate or stalemate. It is like the leaps function but works with logical coordinates.

lograys from directions

Using a coordinate of a space and a list of logical directions, this returns an array of all spaces that can be reached by moving in straight lines from that space in the directions indicated. Like logride, it may also take a series of directions inside parentheses. It then follows these directions sequentially, pushing each space it finds into an array. It will repeat the last direction indefinitely, which is good for calculating the possible moves of winding pieces. To calculate the moves of limited-range riders, the last direction in a sequence should be a non-direction. Any alphabetic string should do, so long as it is not used for a direction. I recommend using stop to make your code more readable. This function is useful for finding the spaces straight riders, winding riders, and short-range riders may move to when using logical coordinates, which is useful in subroutines checking for checkmate or stalemate.

logride from to ...

Determines whether a piece at from can ride to a space at to by means of a sequence of leaps in logical directions. Logical directions are defined by the map and link commands. This function is good for simple riders, winding riders, short-range riders, winding short-range riders, and turning riders. A simple rider just needs a simple direction, which gets repeated until the destination is reached. A winding rider uses a series of directions given inside a pair of parentheses. A short-range rider uses a series of directions that end with a non-direction. The same direction can be repeated for a simple short-range rider, while different directions may be used for a winding short-range rider. A turning rider needs directions in a nested pair of parentheses. The directions before the second pair of parentheses indicate the beginning of a turning rider's move, and what comes in the inner pair of parentheses indicates how the turning rider continues to repeat its move.

match op1 op2 ...

When op2 is an array, indicates whether op1 matches any element in op2. Otherwise, it indicates whether op1 matches any following argument.

mates

Makes a reciprocal associative array out of all the elements in the stack, empties the stack, then pushes the array onto the stack. For each pair of elements, each element is made a key in the array for the other. For example, "set qq mates b B r R" should set qq equal to the array ("b" => "B", "B" => "b", "r" => "R", "R" => "r").

mergeall

Merges the elements of any number of arrays, as well as lone elements, into a single array without any duplicates. This function takes the rest of the line as input, discarding empty values, and adding lone values into an array before merging all the arrays into one.

orsum

Does a binary OR on a set of integers and returns the result. They may be specified in an array or as a series of arguments.

poleride

Intended for spherical chess variants, this handles a riding move through a pole. It takes six arguments, though it may take 3 if the last argument is an array. The first argument is the space moved from, the second is the space moved to, and the last four are logical directions, which describe the series of directions a piece goes through to make a complete circuit around the board while moving in the "same" direction. These will usually include a direction for approaching a pole, the direction for crossing it, the direction for moving away from that pole toward the opposite pole, and the direction for crossing the opposite pole.

sort

Returns a case-sensitive, alphabetically sorted version of array. This will sort uppercase before lowercase and even alphabetize numbers, such as putting 10 before 2. If an array is not provided, it turns the remaining arguments into an array and sorts them.

sub name arguments

Calls the named subroutine and sends the rest of the stack as the subroutine's arguments. Returns the value of the subroutine.

sum

Adds up all elements in the stack or in a given array, then pushes the result onto the stack.

windingrays

Returns an array of the spaces that might be reached by moving along a winding path. The path is described by pairs of integers describing the number of files and ranks to move each step.

windingride

Checks the legality of a move along a winding path. The first two arguments are the space moved from and the space moved to. The path is described by pairs of integers describing the number of files and ranks to move each step. For example, the Rhino, which make alternate orthogonal and diagonal moves in the same general direction could be described with windingride #0 #1 1 0 1 1 or windingride #0 #1 0 1 1 1.

Conditionals

Conditionals evaluate expressions for truth or falsehood, and they execute certain code depending upon the value of the expression. Zero and empty values are taken to be false, while non-empty and non-zero values are taken to be true. All expressions should be written in recursive Polish notation.

if condition:
  code;
elseif condition:
  code;
elseif condition:
  code;
else:
  if condition:
    code;
  else:
    code;
  endif;
endif;

verify condition;

Switch and Case

switch expression:
  case label:
    code;
    break;
  case label:
  case label:
    code;
    break;
  case label label:
    code;
    break;
  default:
    code;
endswitch;

For and Do Loops

The for and foreach commands are used with the next command to create finite loops that iterate over the elements of an array. The do and loop commands are used to create potentially infinite loops that repeat while or until a condition is true. The break, continue, and redo commands interrupt the usual execution of for and do loops.

for (key val) array:
  if condition:
    continue;
  endif;
  foreach val array:
    if condition:
      redo;
    endif;
    if condition:
      break;
    endif;
    code;
  next;
next;

for x range 1 10:
  echo x;
next;

do while condition:
  code;
loop;

do:
  code;
loop until condition;

do:
  code;
  if condition:
    break;
  endif;
loop;

do until condition:
  if condition:
    redo;
  elseif condition:
    continue;
  endif;
loop while condition;

do:
  code;
loop never;

set i 0;
do while < i 10:
  code;
  inc i;
loop;

Subroutines

The sub and endsub commands are used for defining a subroutine. The gosub command is used for executing a subroutine, and the return command may be used for exiting a subroutine and returning a value. The verify command will also exit a subroutine. A subroutine is like a function, but, with the exception of arguments, it uses global variables by default, and it can be treated as nothing more than a body of code that can be reused.

Nevertheless, a subroutine can behave as a function, and subroutines can be made recursive. The local and my commands can create local variables, and the static command can create static variables, like what are commonly used in the functions of other programming languages. The arguments passed to the subroutine are available in two ways. First, the arguments are copied to the variables listed as parameters of the subroutine. These variables all have local scope, which means they are visible to child subroutines but not to any parent subroutine. But this works only for arguments matching named parameters. In case more arguments are passed to a subroutine than it has named parameters for, all arguments passed to a subroutine are also available in an array called subargs. These have my scope, which makes them visible only to that particular subroutine call. Unlike local variables, these are not visible to child subroutines.

sub name parameters

Begins the definition of a subroutine and lists a set of parameters for argument values. A subroutine is the code from the sub command to the closing endsub command. A subroutine name may not match any command name. All arguments passed to a subroutine are treated as local. All code in a subroutine is skipped over unless it is called with a gosub. When a subroutine uses the same label as a previous subroutine, the label gets transferred to the new subroutine.

endsub

Ends the definition of a subroutine. If the subroutine was being executed because of a gosub, execution gets returned to the line immediately following the gosub.

return

Exits from an active subroutine, returning to the line immediately following the gosub, and optionally returning a value. It is not required for exiting a subroutine, since endsub will do that when no return is present, but it may be used for exiting a subroutine early or for passing a value from the subroutine.

verify

Verifies that the expression following it is true. If it is, it allows the subroutine to continue. If it is not true, it exits the subroutine, returning a value of false.

gosub label arguments

Goes to a subroutine at a different location. The subroutine must have been defined before the gosub line. The arguments are passed to the parameter list of the sub command. Any value returned by the subroutine will be placed in the variable RESULT. The gosub command is not always necessary. When a subroutine name appears as the first word in a line of code, the subroutine will be called so long as the name is unused for pieces and spaces. But since it is useful to name subroutines after pieces, the gosub command remains useful. The Polish notation calculator has a sub operator that behaves like gosub except that it directly returns the value of the subroutine and may be used in expressions. It may be used in conditionals, loops, and the setting of variable values.

User Defined Functions

copyfn existing_function new_function

Creates a clone of a function with a new name.

def name expression

The def command lets you create a one-line function that can be accessed with the fn operator of the Polish notation calculator. The first argument is the name of the function, and the remaining arguments define the function. The function's name should not match any built-in function name used by the Polish notation calculator. Otherwise, you will get unwanted results. The function should be defined as a Polish notation expression. It may also include placeholders or variable names for passed arguments.

The original way is to use placeholders. Each placeholder should begin with the number sign and be followed only by digits, such as #0, #2, etc. The number following the number sign indicates which argument it is a placeholder for. #0 is a placeholder for the first argument, #1 for the second argument, etc. The highest numbered placeholder should not exceed the number of different placeholders that you use. So, for example, if you use #4 as a placeholder, you should also include #3, #2, and #1.

The new way is to pass arguments to variables. These will be my scope variables, and they may be named whatever you like. To pass an argument to a variable, you should the = prefix with the variable name before you use the variable. There should be no space between the prefix and the variable name. This allows you to use varible names that otherwise match operator names. Using name as an example name, =name stores in name the value immediately after it, or if there is no value after it, it pops off the next argument in the substitutions stack. This stack contains the values passed as arguments. The right-most argument passed will be the first one to be popped off. Here is an example:

def subtract - #first #second =first =second;
set diff fn subtract 10 3;
echo #diff; // 7

Using this technique, it is possible to give default values to variables. To do this, use =name twice in a row with the default value immediately to the right. This will first assign the default value to the variable. It will then pop off the next value in the substitutions stack. If that stack is empty, though, it will not alter the value of the variable. With the default already assigned to it, it will use the default. Here is an example:

def madlib list The #noun in #place #verb #adverb on the #noun2 =noun =noun rain =place =place Spain =verb =verb falls =adverb =adverb mainly =noun2 =noun2 plain;
set m fn madlib;
set n fn madlib cars Detroit go quickly street;
set o fn madlib "New York" eats slowly dessert;
dump;

This produces the output:

Array
(
    [0] => Array
        (
            [main] => Array
                (
                    [m] => The rain in Spain falls mainly on the plain
                    [n] => The cars in Detroit go quickly on the street
                    [o] => The rain in New York eats slowly on the dessert
                )

        )

)

Since arguments are passed to parameters in right to left order, only the leftmost ones will get the default values. In the example above, the variable o was defined with a function call that had only four arguments, and it got the default value for noun, which was the first from the left. So, any optional parameters should be placed on the left side when defining a function. Parameters more to the left are considered more optional than those to their right, since the rightmost parameters will get assigned first, and the remaining parameters will get default values only if the arguments run out.

An alternative to using defining defaults for parameters is to assign values to variables that will not be included in the function call. Here's an example based on the one above. It assigns the same values to the variables m, n, and o.

set noun rain;
set place Spain;
set verb falls;
set adverb mainly;
set noun2 plain;

def madlib list The #noun in #place #verb #adverb on the #noun2 =noun =place =verb =adverb =noun2;
set m fn madlib;
set n fn madlib cars Detroit go quickly street;
set o fn madlib "New York" eats slowly dessert;
dump;

Note that default values will always override external assignments to the same variable name. So, this will not work for any parameter you give a default value to.

fn name arguments

This is an operator that can be used in any Polish notation conditional expression. It lets you use a user defined function, specified by its name, or provided namelessly as an array. Which it does depends upon whether its first argument is a string or an array. The latter allows the use of nameless lambda functions. The contents of the function determine how many arguments it requires. It pops off as many arguments as needed and pushes the result onto the stack. The fn operator may be used within the function definition to call itself recursively.

and condition

or condition

Besides their usual behavior of evaluating a logical relation between two operands, these can also evaluate a logical relation with only one operand. If we look at the truth table showing the truth values for each of these logical operations, we can see that in some cases, the value of one operand is enough to determine the truth value:

#0 | #1 | and | or 
 T |  T |  T  | T  
 T |  F |  F  | T  
 F |  T |  F  | T  
 F |  F |  F  | F  
 

For and, a false value for either operand makes the whole expression false. For or, a value of true for either operand makes the whole expression true. Whenever one value is enough to determine the value of the logical expression, it breaks out of the whole expression it is evaluating, returning as its value the value of the logical expression. For example, == 77 * 4 9 and != 7 7 or != 8 9 would evaluate != 8 9 first and return true without evaluating the rest of the expression. So, for a false value, and breaks out with a value of false, and nand breaks out with a value of true, while for a true value, or breaks out with a value of true, and nor breaks out with a value of false. Otherwise, these operators simply allow the expression to continue without adding anything to the stack. For example, == 77 * 4 9 and != 7 7 or != 8 8 first evaluates != 8 8 to false, continues to != 7 7, which is evaluates as false, and then since the operator is and, it returns false without continuing with the rest of the expression. By returning nothing when it doesn't break, it allows multiple instances of variable arity operators in the same line. Consider an expression like or match insight #k 0 1 R Q match insight #k 1 0 R Q. Since match will use any arguments available, this would not work right. Instead of returning true if either match is true, or false otherwise, it would add the value of the right-most match to the list of operands for the left-most match, which would return true only if the left-most match is true. But by putting the or between the two match expressions, the expression match insight #k 0 1 R Q or match insight #k 1 0 R Q gives the correct results.

onlyif condition expression

unless condition expression

Originally designed to enable recursion, these functions are more efficient replacements for cond. While cond takes three arguments, each of these takes only two. For all three, the first argument will be a condition. Using the same three expressions, here are examples of all three:

print cond bitand 1 5 "Odd" "Even";
print "Odd" onlyif bitand 1 5 "Even";
print "Even" unless bitand 1 5 "Odd";

The condition bitand 1 #0 is a test for whether a number is odd, and all three expressions will print the word "Odd". The expressions using onlyif and unless should be read from left to right. The first of these will print "Odd" only if 5 is odd. Otherwise, it will print "Even". The second will print "Even" unless 5 is odd, in which case it will print "Even". Note that the word preceding the operator, "Odd" in the case of onlyif or "Even" in the case of unless, are not parts of the expression evaluated by the operator. Instead of simply returning values, these two control the flow of the function. The onlyif operator allows the function to continue only if the condition is true, breaking out if it is false, and the unless operator allows the function to continue unless the condition is true, in which case it breaks out. When it does allow the function to continue, it discards the values of both expressions following it. When it doesn't allow the function to continue, it breaks out, returning the value of the second expression following it, or, if there is no second value, the boolean value false. By having a function call itself to the left of one of these operators, you can create a recursive function that does not fall into an infinite loop.

Control Flow in Functions

A function normally evaluates its operators and operands from end to beginning. When it reads an operand, it immediately pushes it onto a stack. When it reads an operator, it pops off as many operators as it needs, then pushes the result of the operation onto the stack. Doing it this way allows operators to come before operands, and it allows for a fixed order of evaluation that does not have to be disambiguated with parentheses or rules of precedence. But there are times when you don't need to evaluate the whole expression, and you would like to either break out early or skip portions of an expression. You may do that with the operators and, or, nand, nor, onlyif, unless, and cond.

The first four are logical operators, the next two are mainly for recursive functions, and the last one is for selecting which of two expressions will be evaluated. Of these, the four logical operators and cond treat arrays as complete expressions rather than as arrays. Enclosing an expression in parentheses allows it to pass for an array until it reaches an operator that will conditionally trigger its evaluation. This keeps it from being evaluated too early. Let's look at an example:

def White_Charging_Knight cond < rank #0 rank #1 (checkleap #0 #1 1 2) (checkleap #0 #1 1 1 or checkleap #0 #1 1 0);

This reads in the two expressions enclosed in parentheses without doing anything with them. It then evaluates the highlighted condition, and depending on whether it is true or false, it evaluates the first expression for a true value or the second expression for a false value. If you wish the returned value to be an actual array, you should double up on parentheses, which will make the array the value of the expression.

The four logical operators can do the same thing. This comes in handy for short-circuiting from a logical operation when the first value is enough to determine the truth value of the operation. When given two operands, each of these evaluates the first one first, and if that is enough to determine the truth value, it will not evaluate the second. For and, a single false value is enough to determine that the final result will be false. For nand, which means not and, it is enough to determine that the final value will be true. For or, a single true value is enough to determine that the whole expression will be true. For nor, which is a negation of or, it is enough to determine that the expression will be false.

Besides being able to short-circuit when it has two expressions to evaluate, the logical operators may take a single operand. With a single operand, these will either return a value and exit early or allow an expression to continue without pushing a value to the stack. Compare these two expressions:

set a and (== 3 2) (== 5 5);
set b == 3 2 and == 5 5;

Both of these should evaluate to false. For the first one, it will evaluate == 3 2 as false and push the value of false to the stack without evaluating == 5 5. For the second one, it will evaluate == 5 5 as true, but it will not push a value of true to the stack. If it did, b would be set to the array (true, false). Instead of this, it just drops off and allows the expression remaining on the left side to determine the value of the expression as a whole. In determining that the expression to its right was true, it determined that the truth value of a complete and operation would be the same as the truth value of the expression on its left side.

For similar reasons, or will immediately return true if it receives a single true operand, but if it receives a single false operand, it will drop away and let the left side determine the truth value of the whole expression. While nand and nor have similar behavior, their use in this way can be confusing and misleading. In the following example, both a and c evaluate to false, but b evaluates to true:

set a nor (== 3 3) (== 2 3);
set b == 3 3 nor == 2 3;
set c not == 3 3 nor == 2 3;

Bear in mind here that when we use "nor" in speech, we say "neither-nor", because we are negating both parts. We don't normally use "nand" in speech at all, and the following example shows a similar problem with nand. Both a and c evaluate to false, but b evaluates to true.

set a nand (== 3 3) (== 2 2);
set b == 3 3 nand == 2 2;
set c not == 3 3 nand == 2 2;

Unless your aim is to write obfuscated code, I do not recommend using nor or nand with single arguments.

Like the logical operators, unless and onlyif can be used with one or two operators. Each of these should be read as allowing evaluation of the expression on the left unless or onlyif the first expression on the right is true. The second expression after unless or onlyif provides a return value if it determines that the left-side expression should not be evaluated. This makes the use of these like using cond. The following five statements return the same result:

set a cond < 1 2 "One is the Loneliest Number." "One is the best.";
set b "One is the best." unless < 1 2 "One is the Loneliest Number.";
set c "One is the Loneliest Number." onlyif < 1 2 "One is the best.";
set d "One is the Loneliest Number." unless >= 1 2 "One is the best.";
set e "One is the best." onlyif >= 1 2 "One is the Loneliest Number.";

Note that when switching between onlyif and unless, you have to either switch the two potential value, or you have to reverse the condition to its negation. But do only one or the other, not both.

With only one operand after the operator, unless and onlyif will return the value of the condition if it does not allow evaluation of the left side. This will normally be true for unless and false for onlyif. It could be something else, though, since non-Boolean values will be translated to Booleans for the sake of determining whether to allow evaluation of the left side. Here are some examples:

set a "The left Side" unless rand 0 3;
set b "The Left Side" onlyif rand 0 3;

In this example, a might get set to 1, 2, or 3, and b might get set to 0. These are not identical to true and false, but they are functional substitutes for them.

When these operators are followed by a single expression that does evaluate to a Boolean, unless works like or, and onlyif works like and. So, in this example, a is equivalent to b, and c is equivalent to d:

set a == 3 3 or == 8 9;
set b == 3 3 unless == 8 9;
set c == 3 3 and == 8 9;
set d == 3 3 onlyif == 8 9;

The first two evaluate to true. Each one evaluates == 8 9 first, and since it is false, it allows evaluation of the expression on the left, which is true. The last two evaluate to false. After each one evaluates == 8 9 to false, it immediately exits with a false value.

While these can be used interchangely in some circumstances, there is one in which they cannot. Unlike the logical operators, unless and onlyif do not trigger the evaluation of expressions enclosed in parentheses. Instead, they just treat them as arrays. So, in the following example, a and c have the same values as before, but b is set to the array (== 8 9), and d is set to true.

set a == 3 3 or (== 8 9);
set b == 3 3 unless (== 8 9);
set c == 3 3 and (== 8 9);
set d == 3 3 onlyif (== 8 9);

Because of this, I was led to think that unless and onlyif could be faster than or and and. But diagnostic testing shows they are actually slower. Perhaps it is because they are longer strings. In confirmation of this, diagnostics show that && is slightly faster than and. It's up to you whether you prefer to use unless and onlyif or the logical operators for flow control. I use the logical operators, because I have a solid grasp on their meaning and feel comfortable with them. But if unless and onlyif work better for you intuitively, go ahead and use them. For more on their use in control flow, I'll direct you to the Breaking Logic section of the Fairychess include file tutorial

Lambda Functions

A lambda function is a nameless function that is defined on the spot. A lambda function is written and stored as an array, but to tell arrays and lambda functions apart, I have created a separate type for them. To create a lambda function object, write your function inside parentheses, or inside quotation marks, and place the keyword lambda in front of it. For example:

set cube lambda (* * #0 #0 #0);
print fn #cube 5; // Prints 125
set square "* #0 #0";
print fn #square 6; // Prints 36

Some built-in functions are designed for doing advanced operations with lambda functions.

aggregate lambda_function array

For each element of the array, this runs the lambda function, using the array element as an argument, which is recognized within the lambda function as #0. If the array element is itself an array, its first element is #0, its second #1, and so on. Each time the lambda function produces a nonzero value, it pushes that value into an array. When it's finished, it returns this array. Note that this function ignores array keys, and the array it returns is an indexed array, not an associative array. It is most useful for creating arrays with different values than the original array.

filter lambda_function array

This runs the lambda function on each element of the array, and it returns back a subset of the original array, complete with the same keys and values, just in case the original array was an associative array whose keys need to be preserved. To determine which elements to include in this subset, it uses the lambda function to filter out elements. The lambda function normally takes two arguments, #0 for the key and #1 for the value. When the value is an array, its first element is #1, its second #2, and so on. Since the filter function will return the original key and value when the lambda function has a true value, there is no need to include the return value in the lambda function. This can be used, among many other things, for finding spaces with certain pieces on them. For example, set a filter lambda (islower #1) spaces; will return an associative array of all the spaces with Black pieces.

allfalse (or nonetrue) lambda_function array

alltrue lambda_function array

anyfalse lambda_function array

anytrue (or any) lambda_function array

Like aggregate above, these go through an array element by element, running the function on each element, but instead of returning an array, they return true or false, and instead of always going through the whole array, they break out early as soon as the return value can be known. allfalse (or nonetrue) will return false if any function call has a true result, otherwise returning false. alltrue returns false if any function call returns false, otherwise returning true. anyfalse returns true if any function call has a false result. anytrue (or any) returns the argument for the first function call with a nonzero result, which will be interpreted as true in any conditional expression, otherwise returning false. For example, set k any lambda (#0 onlyif == space #0 k) spaces will return the position of the Black King.

Since you can turn a string into a lambda function, it is possible to write code that creates specialized lambda functions.

def doublesquare fn lambda join "* #0 " #0 + #0 #0;
print fn doublesquare 5; Prints 50

In this example, the #0 inside quotation marks is a parameter of the lambda function, but outside parentheses, it is a parameter of the doublesquare function. What this does is add a number to itself, then passes the doubled number to a lambda function that multiplies it by the original number. Breaking it down, it looks like this with 5 as the argument:

lambda join "* #0 " #0 + #0 #0
lambda "* #0 5" + 5 5
(* #0 5) 10
(* 10 5)
50

Local Functions with Named Lambda Functions

While lambda functions are normally nameless, you can assign them to named variables. This is useful for creating local functions that you want to use in a certain subroutine. The def command is not good for this, because all the functions it creates have a global scope. Here's an example from the stalemated subroutine in the fairychess include file:

	local cspaces friend friends from piece to movetype;

	if isupper space #kingpos:
		set friends lambda (onlyupper);
		set friend lambda (not haslower #0 and hasupper #0);
		set cspaces var wcastle;
	else:
		set friends lambda (onlylower);
		set friend lambda (not hasupper #0 and haslower #0);
		set cspaces var bcastle;
	endif;

In this example, friend and friends are local functions defined for use in the subroutine. When used, they appear as fn #friend and fn #friends. While I could have omitted the lambda keyword in defining these functions, using it makes it run a little more quickly, and it makes it clearer that this variable is being used as a function. As you can see, the cspaces variable does not include it, and it is not being used as a function.

Recursion

A recursive function or subroutine is one that calls itself until a certain condition is met. When writing subroutines, it is more efficient to write your code in terms of loops, but that isn't an option for functions. So, when you need a function to repeat code multiple times, you can do that with recursion.

The most important thing to remember about recursion is that any recursive function needs to have the option to return a value without calling itself again. Otherwise, you will create an infinite loop. So, avoid creating functions like the following:

def loop fn loop + 1 #0;

This function would go on forever, which would get in the way of continuing with your game. A recursive function should only call itself conditionally. It should include a condition that calls itself for one value but doesn't call itself for another. When it doesn't call itself, it should have a value it can return without calling itself. There are multiple ways of testing a condition in a function. You may use cond, onlyif, unless, and, or, nand, or nor. To illustrate this, let's look at different ways of defining a factorial function.

The factorial of a postive integer is the product you get when you multiply it by each lower integer down to 1. For example, the factorial of 1 is 1, the factorial of 2 is 2, the factorial of 3 is 6, the factorial of 4 is 24, the factorial of 5 is 120, and so on. You may notice a certain pattern. Each factorial is the product of an integer and the factorial of the next lowest integer. For example, the factorial of 5, which is 120, is the product of 5 times 24, which is the factorial of 4. Likewise, 24 is 4 times 6, 6 is 3 times 2, 2 is 2 times 1, and 1 is 1 times 1. So, we can define a factorial recursively as the the product of the input with the factorial of the input minus 1. Putting that into code, it could look like this:

def fac * #0 cond <= #0 1 1 (fn fac dec #0);

This code multiples the input (#0) by 1 or by the factorial of the input minus 1. The dec operator decrements its input by one, making it equivalent to - #0 1. To better illustrate the logic of what is going on, this function is equivalent to this subroutine:

sub fac num:
  if <= #num 1:
    return 1;
  else:
    return * #num sub fac dec #num;
  endif;
endsub;

Recursive subroutines are not recommended, though, because subroutines use more resources, and looping is a lot more efficient than using a recursive subroutine. With that in mind, this same subroutine could be rewritten like this:

sub fac num:
  set product 1;
  do until <= #num 1:
    set product * #product #num;
    dec num;
  loop;
  return #product;
endsub;

Getting back to using recursive functions, note that the following code, which looks superficially similar to the recursive function shown earlier, will create an infinite loop:

def fac * #0 cond <= #0 1 1 fn fac dec #0;

The reason it creates an infinite loop is because it keeps calling the fac function before it does anything else. Putting the call to itself in parentheses stops it from being executed until cond triggers its evaluation. Another way to prevent an infinite loop is to put the code for the recursive call to itself to the left of the condition, which can be done with onlyif, unless, and the various logical operators. Here is another example using unless:

def fac * #0 fn fac dec #0 unless <= #0 1 1;

In this example, unless has been given two arguments. The first is the condition, and the second is the value to return if that condition is true. When unless returns a value, it stops execution of the function right away. So, when it determines that the input is less than or equal to 1, it returns 1 right away and does not call itself. When unless receives a false condition, it allows execution of the code to its left, and it discards itself and everything to its right without passing on a value to the code on its left. The way to read an unless statement is that it will allow execution of whatever is on its left side UNLESS the condition it is given is true.

It can also be used with a single argument. When given a single argument, it treats it as both the condition and the return value for being true. Since the true value produced by the <= operator is equal to 1, the following also works:

def fac * #0 fn fac dec #0 unless <= #0 1;

With that in mind, the or operator can be used in place of unless like so:

def fac * #0 fn fac dec #0 or <= #0 1;

Instead of using unless, we could also use onlyif. This works like unless, except that it exits with a false value when its condition is false. It should be read as allowing the execution of the code to its left ONLY IF the condition it is given is true. If we keep the condition the same, we will get this, which will create an infinite loop:

def fac 1 onlyif <= #0 1 * #0 fn fac dec #0;

To prevent an infinite loop, we need to reverse the condition and leave the recursive function call on the left side of onlyif, like so:

def fac * #0 fn fac dec #0 onlyif > #0 1 1;

With only one argument, onlyif returns the false value instead of the true value. Since the false value of the less than operator is equal to zero, the following incorrect version of the factorial function produces a value of 0 or false for any value:

def fac * #0 fn fac dec #0 onlyif > #0 1;

While maybe not as useful, the normal logical operators can also be used for recursion with two arguments. When given two expressions in parentheses, each will evaluate the first expression first, and it will evaluate the second only if that is needed for determing the truth value of the whole expression. Because of this, the following code is safe:

def and-test and (== 2 1) (fn and-test);
def nand-test nand (== 2 1) (fn nand-test);
def or-test or (== 1 1) (fn or-test);
def nor-test nor (== 1 1) (fn nor-test);
set a fn and-test;
set b fn nand-test;
set c fn or-test;
set d fn nor-test;

As you may tell by examining this code, and and nand will not evaluate the second expression if the first one is false, and or and nor will not evaluate the second expression if the first one is true. If you changed the truth value of the first expression in any of these test functions, though, you would freeze the page with endless recursion. The operator xor cannot be safely used in this way, because it would always have to evaluate both expressions. Because of this, it has not been designed to evaluate parenthesized expressions.

Programming Unusual Topologies with Logical Coodinates

When I decided to work on programming Circular Chess, the need for a new method arose. The previous methods, from early code in Anatomy of a Preset to the chess2 methods, all used the same built-in functions to evaluate piece movement. These functions all worked on the assumption that the board was a fixed plane of coordinates that extended outward from an origin point. This worked well enough for two-dimensional games whose positions can be plotted with Cartesian coordinates, but it doesn't work so well for three-dimensional games and other games with unusual topographies. In Circular Chess, the ranks are circular, looping back into themselves, so that the a and p files are adjacent. A King, for example, should be able to move directly from one of these files to the other. But in the usual mathematical way of representing boards, these files are at opposite ends, and the functions for checking piece movement would have to get more complicated, perhaps even being replaced by subroutines. Instead of doing that, I wrote some commands and built-in functions for using logical coordinates. If you have programmed games for Zillions-of-Games, then you will already be familiar with logical coordinates. Instead of being represented by their distance from an origin point, logical coordinates are abstractions whose relations to other coordinates are determined by defining directions from them and where those directions lead. In Circular Chess, for example, I might say that moving clockwise from a1 leads to b1, and moving counterclockwise from a1 leads to p1. I could actually call these directions by any names I choose, such as north and south, or forward and backward. The commands I wrote for defining the logical coordinates on a board are called map and link. The map command creates a large set of logical coordinates at once. It is useful for quickly creating logical coordinates whose relations match the usual mathematical coordinates. The link command defines directions between individual pairs of coordinates. Here is how I defined the cooordinates in Cicular Chess:

map n 0 1 s 0 -1 w -1 0 e 1 0; // Orthogonal directions
map nw -1 1 ne 1 1 sw -1 -1 se 1 -1; // Diagonal directions
map nne 1 2 nnw -1 2 sse 1 -2 ssw -1 -2; // Hippogonal directions
map nee 2 1 nww -2 1 sww -2 -1 see 2 -1; // Hippogonal directions

Note that I didn't use the link command. Instead, I extended the file labels (listed in the Files field) to start repeating themselves. For it to map the hippogonal directions for Knight moves, I ended it with the first two files it began with. If I hadn't extended it, these commands would have worked for defining the directions normally used in Chess. If you were programming a 3D game, you could add additional directions, such as u (for up), d (for down), un, us, ue, uw, dn, ds, de, dw, une, dne, etc. To do this, you would need to establish the distance between planes and factor that into your direction definitions. Assuming that planes are 8x8 with a distance of 9 ranks between them, here are some examples:

map u 0 9 d 0 -9; // Straight up and down
map un 0 10 us 0 -8 uw -1 9 ue 1 9; // Slanted up directions
map une 1 10 unw -1 10 use 1 -8 usw -1 -8; // Diagonal up directions

Having a distance of 9 between 8x8 planes allows you to place barriers between them of non-space, indicated by hyphens in the FEN code. If you place no barriers between them, then you can unlink planes with the unlink command.