tadsgen.hfile | source file |
Classes Summary | Functions Summary Details | Macros Summary Details | Enums Summary Details | Templates Summary Details |
This header defines the tads-gen intrinsic function set. This function set provides some miscellaneous functions, including data conversions, object iteration, regular expressions, and state persistence operations.
dataType
firstObj
getArg
getFuncParams
getTime
makeString
max
min
nextObj
rand
randomize
restartGame
restoreGame
rexGroup
rexMatch
rexReplace
rexSearch
saveGame
savepoint
sprintf
toInteger
toNumber
toString
undo
GetTimeDateAndTime
GetTimeTicks
ObjAll
ObjClasses
ObjInstances
ReplaceAll
ReplaceFollowCase
ReplaceIgnoreCase
ReplaceOnce
ReplaceSerial
TADSGEN_H
dataType (val) | tadsgen.h[28] |
firstObj (cls?, flags?) | tadsgen.h[45] |
getArg (idx) | tadsgen.h[34] |
getFuncParams (func) | tadsgen.h[411] |
getTime (timeType?) | tadsgen.h[203] |
If timeType is GetTimeDateAndTime (or is omitted), this returns the calendar date and wall-clock time, as a list: [year, month, dayOfMonth, dayOfWeek, dayOfYear, hour, minute, second, timer]. Year is the year AD (for example, 2006); month is the current month, from 1 (January) to 12 (December); dayOfMonth is the calendar day of the month, from 1 to 31; dayOfWeek is the day of the week, from 1 (Sunday) to 7 (Saturday); dayOfYear is the current day of the year, from 1 (January 1) to 366 (December 31 in a leap year); hour is the hour on a 24-hour clock, ranging from 0 (midnight) to 23 (11pm); minute is the minute of the hour, from 0 to 59; second is the second of the minute, from 0 to 59; and timer is the number of seconds elapsed since the "epoch," defined arbitrarily as midnight, January 1, 1970.
If timeType is GetTimeTicks, this return the number of milliseconds since an arbitrary starting time. The first call to get this information sets the starting time, so it will return zero; subsequent calls will return the amount of time elapsed from that starting time. Note that because a signed 32-bit integer can only hold values up to about 2 billion, the maximum elapsed time that this value can represent is about 24.8 days; so, if your program runs continuously for more than this, the timer value will roll around to zero at each 24.8 day multiple. So, it's possible for this function to return a smaller value than on a previous invocation, if the two invocations straddle a 24.8-day boundary.
makeString (val, repeatCount?) | tadsgen.h[400] |
max (val1, ...) | tadsgen.h[376] |
min (val1, ...) | tadsgen.h[385] |
nextObj (obj, cls?, flags?) | tadsgen.h[53] |
rand (x, ...) | tadsgen.h[112] |
If exactly one argument is supplied, the result depends on the type of the argument:
- Integer: the function returns an integer from 0 to one less than the argument value. For example, rand(10) returns a number from 0 to 9 inclusive.
- List: the function randomly selects one of the values from the list and returns it.
- String: the function generates a random string by replacing each character of the argument string with a randomly chosen character, selected from a specific range specified by the argument character. For example, each 'a' in the input string is replaced by a random lower-case letter from a to z, each 'A' is replaced by a capital letter, and each 'd' is replaced by a random digit 0 to 9. See the System Manual for the full list of the character codes.
If more than one argument is supplied, the function randomly selects one of the arguments and returns it. Note that this is an ordinary function call, so all of the arguments are evaluated, triggering any side effects of those evaluations.
In all cases, the random numbers are uniformly distributed, meaning that each possible return value has equal probability.
randomize ( ) | tadsgen.h[81] |
Note that if randomize() is never called, the system will use a fixed initial seed, so rand() will return the same sequence each time the program is run. This is intentional, because it makes the program's behavior exactly repeatable, even if the program calls rand() to select random numbers. This type of repeatable, deterministic behavior is especially useful for testing purposes, since it allows you to run the program through a fixed set of input and compare the results against a fixed set of output, knowing the the random number sequence will be the same on each run. Typically, what you'd want to do is check at start-up to see if you're in "testing" mode (however you wish to define that), and call randomize() only if you're not in testing mode. This will create apparently random behavior on normal runs, but produce repeatable behavior during testing.
restartGame ( ) | tadsgen.h[367] |
restoreGame (filename) | tadsgen.h[360] |
rexGroup (groupNum) | tadsgen.h[247] |
rexMatch (pat, str, index?) | tadsgen.h[217] |
rexReplace (pat, str, replacement, flags?, index?) | tadsgen.h[313] |
The search pattern can also be given as a *list* of search patterns. In this case, we'll search for each of the patterns and replace each one with the corresponding replacement text. If the replacement is itself given a list in this case, each element of the pattern list is replaced by the corresponding element of the replacement list. If there are more patterns than replacements, the extra patterns are replaced by empty strings; any extra replacements are simply ignored. If the replacement is a single value rather than a list, each pattern is replaced by that single replacement value.
'flags' is a combination of the ReplaceXxx bit flags, using '|'. If the flags include ReplaceAll, all occurrences of the pattern are replaced; otherwise only the first occurrence is replaced.
If ReplaceIgnoreCase is included, the capitalization of the match pattern is ignored, so letters in the pattern match both their upper- and lower-case equivalents. Otherwise the case will be matched exactly. If ReplaceFollowCase AND ReplaceIgnoreCase are included, lower-case letters in the replacement text are capitalized as needed to follow the capitalization pattern of the actual text matched: if all the letters in the match are lower-case, the replacement is lower case; if all are upper-case, the replacement is changed to all upper-case; if there's a mix of cases in the match, the first letter of the replacement is capitalized and the rest are left in lower-case.
The ReplaceSerial flag controls how the search proceeds when multiple patterns are specified. By default, we search for each one of the patterns, and replace the leftmost match. If ReplaceOnce is specified, we're done; otherwise we continue by searching again for all of the patterns, this time in the remainder of the string (after that first replacement), and again we replace the leftmost match. This proceeds until we can't find any more matches for any of the patterns. If ReplaceSerial is included in the flags, we start by searching only for the first pattern, replacing one or all occurrences depending on the ReplaceOnce or ReplaceAll flag. Next, if ReplaceAll is specified OR we didn't find any matches for the first pattern, we start over with the result and search for the second pattern, replacing one or all occurrences of it. We repeat this for each pattern.
If the flags are omitted entirely, the default is ReplaceAll (replace all occurrences, exact case, parallel searching).
'index', if provided, is the starting character index of the search; instances of the pattern before this index will be ignored. Returns the result string with all of the desired replacements. When an instance of the pattern is found and then replaced, the replacement string is not rescanned for further occurrences of the text, so there's no danger of infinite recursion; instead, scanning proceeds from the next character after the replacement text.
The replacement text can use "%n" sequences to substitute group matches from the input into the output. %1 is replaced by the match to the first group, %2 the second, and so on. %* is replaced by the entire matched input. (Because of the special meaning of "%", you must use "%%" to include a percent sign in the replacement text.)
rexSearch (pat, str, index?) | tadsgen.h[229] |
saveGame (filename, metatab?) | tadsgen.h[352] |
'metatab' is an optional LookupTable containing string key/value pairs to be saved with the file as descriptive metadata. The interpreter and other tools can display this information to the user when browsing a collection of saved game files, to help the user remember the details of each saved position. It's up to the game to determine what to include; the list can include any information relevant to the game that would be helpful when reviewing saved position files, such as the room name, score, turn count, chapter name, etc.
savepoint ( ) | tadsgen.h[319] |
sprintf (format, ...) | tadsgen.h[468] |
'format' is the format string. Most characters of the format string are simply copied verbatim to the result. However, each '%' in the format string begins a substitution parameter; the '%' is followed by one or more optional qualifiers, then by a type code letter. The corresponding value from the argument list is formatted into a string according to the type code, and then replaces the entire '%' sequence in the result string. By default, the first '%' parameter corresponds to the first additional argument after 'format', the second '%' corresponds to the second additional argument, and so on. You can override the default argument position of a '%' using the '$' qualifier - see below.
The arguments following 'format' are the values to be substituted for the '%' parameters in the format string.
The return value is a string containing the formatted result.
See the System Manual for the list of '%' codes.
toInteger (val, radix?) | tadsgen.h[172] |
If 'val' is a string, the function parses the string's contents as an integer in the numeric base given by 'radix, which can be any integer from 2 to 36. If 'radix' is omitted or nil, the default is base 10 (decimal). The value is returned as an integer. If the number represented by the string is too large for a 32-bit integer, a numeric overflow error occurs.
If 'val' is true, or the string 'true', the return value is 1. If 'val' is nil, or the string 'nil', the return value is 0. Leading and trailing spaces are ignored for these strings.
If 'val' is a BigNumber value, the value is rounded to the whole number, and returned as an integer value. A numeric overflow error occurs if the number is out of range for a 32-bit integer. (If you want to round a BigNumber to the nearest integer and get the result as another BigNumber value, use the getWhole() method of the BigNumber.)
See also toNumber(), which can also parse floating point values and whole numbers too large for the ordinary integer type.
toNumber (val, radix?) | tadsgen.h[440] |
If 'val' is an integer or BigNumber value, the return value is simply 'val'.
If 'val' is a string, the function parses the string's contents as a number in the given 'radix', which can be any integer from 2 to 36. If 'radix' is omitted, the default is 10 for decimal. If the radix is decimal, and the number contains a decimal point (a period, '.') or an exponent (which consists of the letter 'e' or 'E', an optional '+' or '-' sign, and one or more digits), the value is parsed as a floating point number, and a BigNumber value is returned. For any other radix, decimal points and exponents are considered non-number characters. For an integral value, the result will be an integer if the number is within the range that fits in an integer, otherwise the result is a BigNumber. The routine will simply stop parsing at the first non-number character it encounters, so no error will occur if the string contains text following the number. If the text doesn't contain any number characters at all, the result is zero.
If val is true or the string 'true', return 1; if nil or the string 'nil', returns 0. Leading and trailing spaces are ignored in the string versions of these values.
toString (val, radix?, isSigned?) | tadsgen.h[146] |
'radix' is only meaningful with numeric values, namely integers and BigNumbers. For BigNumbers, only whole integer values can be displayed in a non-decimal radix; if the number has a fractional part, the radix will be ignored and the number will be shown in decimal.
'isSigned' indicates whether or not the value should be treated as "signed", meaning that negative values are represented with a "-" sign followed by the absolute value. If 'isSigned' is nil, a negative value won't be converted to its absolute value before being displayed, but will instead be re-interpreted within its type system as an unsigned value. For regular integers, this means that the result depends on the native hardware storage format for negative integers. Most modern hardware uses two's complement notation, which represents -1 as 0xFFFFFFFF, -2 as 0xFFFFFFFE, etc. Most types other than integer don't have distinct signed and unsigned interpretations, so 'isSigned' isn't meaningful with most other types. With BigNumber in particular, the only effect is to omit the "-" sign for negative values.
undo ( ) | tadsgen.h[334] |
GetTimeDateAndTime | tadsgen.h[490] |
1
GetTimeTicks | tadsgen.h[491] |
2
ObjAll | tadsgen.h[476] |
(ObjInstances | ObjClasses)
ObjClasses | tadsgen.h[475] |
0x0002
ObjInstances | tadsgen.h[474] |
0x0001
ReplaceAll | tadsgen.h[481] |
0x0001
ReplaceFollowCase | tadsgen.h[483] |
0x0004
ReplaceIgnoreCase | tadsgen.h[482] |
0x0002
ReplaceOnce | tadsgen.h[485] |
0x0010
ReplaceSerial | tadsgen.h[484] |
0x0008
TADSGEN_H | tadsgen.h[18] |
(none)