Values in SenseTalk
Computers deal with a wide variety of data values, including numbers, text, sound, and pictures. The values you will work with the most in SenseTalk are numbers and text. The ability to combine and organize these values in various ways is also important. SenseTalk’s lists and property lists let you do this.
Numbers
Numbers in SenseTalk can be written using numerals:
1
634
12.908
-3
.5
18.75
or as words:
one
six hundred thirty-four
twelve point nine zero eight
negative three
one half
eighteen and three quarters
You can't use commas in numbers to separate groups of digits, because commas have other meanings in SenseTalk, such as separating the items in a list. However, you can use underscores (_) within a number to make a large number more readable (the underscores are simply ignored by SenseTalk). So, the number “one million three hundred thousand” can be written out in words or as 1_300_000 but can’t be written as 1,300,000. (For more information about lists, see lists, below.)
For technical applications, the following notation is also accepted:
- Scientific notation (containing "e+" or "e-" followed by the power of 10)
- Hexadecimal, octal, and binary notation (beginning with "0x", "0o", and "0b").
4.58e+6
0x8ce3
0o377
0b10011010
You can also use unit designations with numbers, such as for length or distance, weight, or angles:
100 yards
5 pounds
12 minutes
For a full discussion of units, see Using Numbers with Units.
Ordinal Numbers
An ordinal number refers to the order or position of something in a sequence. In SenseTalk, ordinal numbers may be used in chunk expressions to refer to a specific chunk of a value.
Ordinal numbers can be expressed as a number followed by an ordinal suffix (st, nd, rd, or th):
1st, 2nd, 3rd, 4th, 5th, … , 10th, … , 31st, … , 99th, 100th, 101st, 102nd, … , 2023rd, …
Ordinal numbers can also be expressed in words:
first, second, third, … , twelfth, thirteenth, … , twenty-first, twenty-second, … , ninety-ninth, hundredth, one hundred first, ... , two hundredth, … , nine hundred ninety-ninth, one thousandth, one thousand first, … , millionth
In chunk expressions, ordinals can also be used for counting back from the end of a sequence (note that the dashes are required in these expressions):
second-to-last, fourth-from-end, 16th-to-final
Syntax:
{the} ordinal { - [to | from] - [last | end | ultimate | final] }
Text
Text in SenseTalk is usually enclosed in straight double quotation marks:
"abc"
"The Lord of the Rings"
"Greetings, and welcome to the world of computing!"
Full international (Unicode) text is supported. There are a few characters which are hard to represent in quoted text strings, though. In particular, the double quotation mark character itself can’t be used between quotation marks, or the computer would get confused. So SenseTalk provides a special word – quote – which represents that character. You can use it like this:
"John said " & quote & "Hello!" & quote
The ampersand (&) concatenates text, joining it together into a single longer string of characters, so the expression shown above would result in the following text:
John said "Hello!"
Another common character which can’t be included directly in quoted text is the return character, used to separate one line of text from the next. The word return represents the return character in SenseTalk:
"This is line 1." & return & "This is line 2."
Another way of including these characters in text is to use the special double angle bracket pairs << and >>. By using these pairs of characters instead of the double quotation mark, you can include quotation marks and return characters directly:
<<John said "Hello!"
This is line 2. >>
You can also use “curly” quotation marks, if you know how to produce them on your keyboard. They must always be paired with the left quotation mark at the beginning of the text and the right quotation mark at the end:
“John said "Hello!"”
Multi-line Blocks of Text
When you need to incorporate a large block of text spanning many lines into a script, a special mechanism is available using double curly braces {\{ }}.
This type of block quoting differs from double angle brackets << >>. The quoted content doesn’t begin until the line following the opening double brace {\{, and ends with the line preceding the closing double brace }} which must be the first non-whitespace characters on a line.
put {{
This is my "quoted" text.
}} into statement
-- Statement now contains 'This is my "quoted" text.'
Neither the return following the opening double brace nor the return preceding the closing double brace are treated as part of the quoted content, so if you need to include a return character at the beginning or end of the quoted content, a blank line must be inserted.
These curly brace quotes are intended to make it easy to include a large quoted block of text within a script. Because the closing braces are only recognized at the beginning of a line, double braces may appear at other places within the quoted content. To allow an even greater range of content to be quoted, the opening braces may be followed by an identifier. The exact same identifier (case-sensitive) must then come immediately before the closing braces to terminate the quoted content. The identifier may include any non-whitespace characters other than curly braces. By using different identifiers, this makes it possible to nest one quoted text block within another.
set the script of Talker to {{TalkerScript
on speakUp
put {{InnerQuote
This is my "quoted" text, and I am prepared to use it.
InnerQuote}} into my statement
put statement
end speakUp
TalkerScript}}
Logical (Boolean) Values
Logical values (sometimes called Boolean values) express whether something is true or false, yes or no, on or off. In SenseTalk these logical values are represented by the constants true and false.
There are also a number of operators and expressions which evaluate to true or false (see Expressions). Logical values are used to make choices about whether or not to perform certain commands contained in an if...then...else construct (see Conditional Statements ).
When testing a condition in an if statement, SenseTalk will accept any expression which evaluates not only to the constant values true or false but also to "yes", "no", "on", "off", or "" (empty). The values "true", "yes", and "on" are all treated as true, and "false", "no", "off", and "" are treated as false (none of these are case-sensitive – they are valid in upper, lower, or mixed case). Any other value will cause an exception to be thrown if it is used in a context where a logical value is required.
Constants and Predefined Variables
Words such as true and return, which have predefined values that cannot be changed, are called constants. SenseTalk has only five true constants (empty, return, true, false, and end). In addition, there are a large number of predefined variables. These are words that have a predefined value, but can also be used as variables (and have their value changed in a script). See Restricted Words in SenseTalk for more details.
Some of the SenseTalk words that have predefined values are:
| Word | Predefined Value |
|---|---|
empty | An empty string. This is the same as the text literal "". |
return | A "newline" character. This is the same character that is entered in a multiline field when you press the "Return" key on the keyboard. |
carriageReturn creturn cr | A "carriage return" character. The same as numToChar(13). |
linefeed lf newline | A linefeed character. The same as return, or numToChar(10). |
crlf | A carriage return followed by a linefeed. The same as numToChar(13) & numToChar(10). |
lineSeparator | A Unicode line separator character, equal to numToChar(0x2028). |
paragraphSeparator | A Unicode paragraph separator character, equal to numToChar(0x2029). |
quote | A straight double-quote character ("). |
tab | A tab character. This is the same character that is entered into a field when you press the "Tab" key. Tab is the same as numToChar(9). |
space | A single space character (" "). |
comma | A comma (","). |
slash | A forward slash ("/"). |
backslash | A backward-leaning slash ("\"). |
colon | A colon (":"). |
formfeed | A formfeed character. The same as numToChar(12). |
nullChar | A null character. The same as numToChar(0). |
nil null | Equivalent to a missing value; for example, the value used in SenseTalk to represent a null value in a database. |
pi | The mathematical value pi, used in calculations related to circles. In SenseTalk, pi has the value 3.14159265358979323846. |
LightSpeed | The speed of light, equal to 299,792,458 meters per second. |
googol | Equivalent to 10 raised to the power of 100. |
true | The word "True", which has the logical value TRUE in SenseTalk. |
false | The word "False", which has the logical value FALSE in SenseTalk. |
yes | The word "Yes", which has the logical value TRUE in SenseTalk. |
no | The word "No", which has the logical value FALSE in SenseTalk. |
on | The word "On", which has the logical value TRUE in SenseTalk. |
off | The word "Off", which has the logical value FALSE in SenseTalk. |
end | The value of the endValue global property, returned by iterators when no more values are available (default value is " ⓔ ⓝ ⓓ "). |
zero, one, two, ... | The words zero, one, two, three, etc. are predefined as the corresponding numeric values (see Numbers, above). |
today | The current date, in international date format. |
now | The current time, in abbreviated international time format. |
date | The current date, in the same format as the date function. |
time | The current time, in the same format as the time function. |
The words above that are true constants include empty, return, true, false, and end. The other words are predefined variables, which can have other values stored into them by your script.
Because text in SenseTalk is based on the standards used by Cocoa and Unix, the return constant is actually a linefeed character, not a carriage return character, and is equivalent to numToChar(10). In situations where you need an actual carriage return character (such as when writing text to a device attached to a serial port) you should use carriageReturn, creturn, or cr, which is equivalent to numToChar(13).
Custom Predefined Variables
In addition to the predefined variables listed above, SenseTalk automatically loads other variable definitions on startup, which can be customized to your needs. These definitions are contained in files with a ".predef" extension located in the Resources folder within the SenseTalkEngine framework or other bundle loaded by the host application.
Any files with this extension should be plain text files containing an archived property list. The SenseTalk value() function will be used to read each property list and register its keys and values with the SenseTalk engine as predefined variables.
If two resources provide values for the same predefined variable name, the last value loaded will be the one that is used for that variable. Since the value being loaded is a SenseTalk expression, it is possible to include an expression to check for an already defined value and use it instead, or incorporate it into the new value.
Predefined Variables Provided
SenseTalk comes with several sets of additional predefined variables installed, which provide convenient names for a number of useful characters and symbols. Not all of these symbols are available in all fonts, but they are all standard Unicode characters that may be useful. For example:
put copyrightSign && "2008"-- © 2008
The symbols provided include:
Common Symbol
period (.), fullStop (.), semicolon (;), questionMark (?), exclamationMark (!), numberSign (#), ellipsis (…), circumflexAccent (^), ampersand (&), asterisk (*), leftParenthesis ((), rightParenthesis ()), leftSquareBracket ([), rightSquareBracket (]), leftCurlyBracket ({), rightCurlyBracket (}), underscore (_), apostrophe ('), singleQuote ('), tilde (~), graveAccent (`), hyphen (‐), nonBreakingHyphen (-), figureDash (‒), enDash (–), emDash (—), dagger (†), doubleDagger (‡), bullet (•), triangularBullet (‣), nonBreakingSpace ( ), atSign (@), careOfSign (℅), serviceMarkSign (℠), telephoneSign (℡), tradeMarkSign (™), facsimileSign (℻), numeroSign (№), invertedExclamationMark (¡), invertedQuestionMark (¿), verticalBar (|), brokenBar (¦), sectionSign (§), copyrightSign (©), registeredSign (®), pilcrowSign or paragraphSign (¶), middleDot (·), cedilla (¸), leftDoubleAngleQuotationMark («), rightDoubleAngleQuotationMark (»), checkMark (✓), blackDiamond (◆), lowerLeftPencil (), helmSymbol (⎈), caretSign (‸), referenceMark (※), doubleExclamationMark (‼), doubleQuestionMark (⁇), heavyCheckMark(✔), xMark(✗), heavyXMark(✘)
Currency Symbols
centSign (¢), poundSign (£), currencySign (¤), yenSign (¥), euroSign (€), dollarSign ($), australSign (₳), cediSign (₵), colonSign (₡), cruzeiroSign (₢), dongSign (₫), drachmaSign (₯), euroCurrencySign (₠), frenchFrancSign (₣), germanPennySign (₰), guaraniSign (₲), hryvniaSign (₴), indianRupeeSign (₹), kipSign (₭), lariSign (₾), liraSign (₤), livreTournoisSign (₶), manatSign (₼), millSign (₥), nairaSign (₦), newSheqelSign (₪), nordicMarkSign (₻), pesetaSign (₧), pesoSign (₱), rupeeSign (₨), russianRubleSign (₽), spesmiloSign (₷), tengeSign (₸), tugrikSign (₮), turkishLiraSign (₺), wonSign (₩)
Numeric and Mathematical Symbols
lessThanSign (<), greaterThanSign (>), equalsSign (=), percentSign (%), perMilleSign (‰), perTenThousandSign (‱), degreeSign (°), superscriptOne (¹), superscriptTwo (²), superscriptThree (³), microSign (µ), plusSign (+), minusSign (−), multiplicationSign (×), divisionSign (÷), plusOrMinusSign (±), minusOrPlusSign (∓), squareRootSign (√), cubeRootSign (∛), infinitySign (∞), notSign (¬), equalSign (=), almostEqualSign (≈), approximatelyEqualSign (≅), notEqualSign (≠), lessThanOrEqualSign (≤), greaterThanOrEqualSign (≥), fractionOneQuarter (¼), fractionOneHalf (½), fractionThreeQuarters (¾), fractionFiveEighths (⅝), fractionFiveSixths (⅚), fractionFourFifths (⅘), fractionOneEighth (⅛), fractionOneFifth (⅕), fractionOneFourth (¼), fractionOneNinth (⅑), fractionOneSeventh (⅐), fractionOneSixth (⅙), fractionOneTenth (⅒), fractionOneThird (⅓), fractionSevenEighths (⅞), fractionThreeEighths (⅜), fractionThreeFifths (⅗), fractionThreeFourths (¾), fractionTwoFifths (⅖), fractionTwoThirds (⅔), fractionZeroThirds (↉)
Keyboard Symbols
commandKeySymbol (⌘), optionKeySymbol (⌥), controlKeySymbol (⌃), shiftKeySymbol (⇧), eraseRightKeySymbol (⌦), eraseLeftKeySymbol (⌫), escapeKeySymbol (⎋), returnKeySymbol (⏎), ejectKeySymbol (⏏), appleLogo (), alternativeKeySymbol (⎇), blankKeySymbol ( ␣ ), capsLockKeySymbol (⇪), clearKeySymbol (⌧), pageUpKeySymbol (⇞), pageDownKeySymbol (⇟), tabKeySymbol (⇥), tabLeftKeySymbol (⇤), returnLeftKeySymbol (↩), returnRightKeySymbol (↪), leftArrowSymbol (←), rightArrowSymbol (→), upArrowSymbol (↑), downArrowSymbol (↓), contextualMenuKeySymbol ()
Miscellaneous Symbols
whiteDiamond (◇), fisheye (◉), blackCircle (●), whiteCircle (○), largeCircle (◯), dottedCircle (◌), bullseye (◎), whiteBullet (◦), blackSun (☀), whiteSun (☼), cloud (☁), umbrella (☂), umbrellaWithRainDrops (☔), snowman (☃), cometSymbol (☄), blackStar (★), whiteStar (☆), lightningSymbol (☇), thunderstormSymbol (☈), sunSymbol (☉), blackTelephone (☎), whiteTelephone (☏), hotBeverage (☕), shamrock (☘), skullAndCrossbones (☠), cautionSign (☡), radioactiveSign (☢), biohazardSign (☣), caduceus (☤), ankh (☥), peaceSymbol (☮), yinYang (☯), firstQuarterMoon (☽), lastQuarterMoon (☾), femaleSign (♀), maleSign (♂), snowflake (❄), hotSprings (♨), whiteFlag (⚐), blackFlag (⚑), heavyBlackHeart (❤), blackSpadeSuit (♠), blackHeartSuit (♥), blackDiamondSuit (♦), blackClubSuit (♣), whiteSpadeSuit (♤), whiteHeartSuit (♡), whiteDiamondSuit (♢), whiteClubSuit (♧), recyclingSymbol (♲), blackRecyclingSymbol (♻), whiteSmilingFace (☺), blackSmilingFace (☻), whiteFrowningFace (☹), adiShakti (☬), AprilFoolsDay ("April 1"), blackChessBishop (♝), blackChessKing (♚), blackChessKnight (♞), blackChessPawn (♟), blackChessQueen (♛), blackChessRook (♜), blackHandPointingLeft (☚), blackHandPointingRight (☛), boxListFormat {prefix:"【", quotes:"None", separator:"】 【", suffix:"】"}, chiRho (☧), Christmas ("December 25"), ChristmasEve ("December 24"), crossOfJerusalem (☩), crossOfLorraine (☨), digramForGreaterYang (⚌), digramForGreaterYin (⚏), digramForLesserYang (⚎), digramForLesserYin (⚍), earthSymbol (♁), farsiSymbol (☫), Halloween ("October 31"), hammerAndSickle (☭), handPointingDown (☟), handPointingLeft (☜), handPointingRight (☞), handPointingUp (☝), jsonListFormat {indent:" ", prefix:"[", quotes:"Auto", separator:",", suffix:"]"}, jsonPropertyListFormat {asTextEnabled:"Yes", emptyRepresentation:"{}", entrySeparator:", ", indent:" ", keySeparator:":", prefix:"{", quotes:"Auto", suffix:"}"}, jupiterSymbol (♃), LightSpeed (299792458 meters per second), marsSymbol (♂), mercurySymbol (☿), monogramForYang (⚊), monogramForYin (⚋), neptuneSymbol (♆), NewYearsDay ("January 1"), NewYearsEve ("December 31"), oldListFormat {prefix:"(", quotes:"None", separator:",", suffix:")"}, oldPropertyListFormat {asTextEnabled:"Yes", emptyRepresentation:"(:)", entrySeparator:", ", keySeparator:":", prefix:"(", quotes:"Standard", suffix:")"}, orthodoxCross (☦), plutoSymbol (♇), powerOnOffSymbol (⏼), powerOnSymbol (⏽), powerSleepSymbol (⏾), powerSymbol (⏻), saturnSymbol (♄), standardListFormat {prefix:"[", quotes:"Auto", separator:",", suffix:"]"}, standardPropertyListFormat {asTextEnabled:"Yes", emptyRepresentation:"{:}", entrySeparator:", ", keySeparator:":", prefix:"{", quotes:"Auto", suffix:"}"}, starAndCrescent (☪), trigramForEarth (☷), trigramForFire (☲), trigramForHeaven (☰), trigramForLake (☱), trigramForMountain (☶), trigramForThunder (☳), trigramForWater (☵), trigramForWind (☴), uranusSymbol (♅), ValentinesDay ("February 14"), venusSymbol (♀), wheelOfDharma (☸), whiteChessBishop (♗), whiteChessKing (♔), whiteChessKnight (♘), whiteChessPawn (♙), whiteChessQueen (♕), whiteChessRook (♖)
The predefinedVariables Global Property
the PredefinedVariables global property is a property list containing the definitions of all of the predefined variables. See the predefinedVariables for information about using the global property.
Lists
SenseTalk understands lists of values, which are enclosed in square brackets and separated by commas:
[1,2,3]
["a","b","c"]
Lists can include any kind of values, including other lists:
[12.4,"green", <<John said "Hello!">>, [44,6], [55,2] ]
Items in a list are accessed by their position number. The first item is number 1:
item 1 of ["red", "green", "blue"] -- "red"
the third item of ["c","d","e","f","g"] -- "e"
Lists are very useful for organizing values. SenseTalk provides a number of commands and operators for creating and working with lists (see Lists).
Property Lists
A property list is similar to a list, but instead of containing an ordered list of values, its values are each identified by name:
{size:12, color:blue}
{name:"Jason", age:"67", phone:"555-1234", city:"Denver"}
Properties in a property list are accessed by name:
property "width" of {shape:"oval",height:"12",width:16} -- 16
Property lists are actually a simple form of object. Property lists viewed as simple data containers are described in Property Lists. Objects are described in detail in Objects.
Ranges
A range uses a beginning and ending value to specify a range of numbers, dates, times, or characters:
1..200
"May 1" to "June 30"
"A" .. "Z"
Ranges can be ascending or descending, and a step value can be given:
500 to 200 down by 10
start to finish by step
A range value can be used directly as a range, or to generate a list of values. Or it can be accessed like a list itself:
put item 12 of "May 1" to "June 30" -- "May 12"
Ranges and their uses are described in detail in Ranges, Iterators, and Each Expressions.
Special Values
Time Intervals
In some situations it is useful to work with an interval of time, also referred to as a duration. When a command, function, or other operation expects a value to be a time interval, SenseTalk assumes the duration is measured in seconds if no specific unit is given. However, a time interval can also be expressed precisely using many different units, including weeks, days, hours, milliseconds, etc.:
wait 5.2 -- No unit given, so SenseTalk assumes 5.2 seconds
wait 2 minutes 12.6 seconds
if the time - startTime < 150 milliseconds then logSuccess
put the date plus one week into nextWeek
put 1 into mtimeout -- number of minutes
put 15 into stimeout-- number of seconds
wait mtimeout minutes and stimeout seconds
To see the full list of time units and abbreviations that are available, use this command:
put (each item of the unitNames whose unitType is duration) sorted
For a full discussion of units, see Using Numbers with Units.
Calendar Durations
In addition to time interval durations that can be precisely measured in seconds, SenseTalk also supports calendar durations measured in months, quarters, calendar years, decades, and centuries from a date. Note that calendar duration units are not the same as time intervals, and thus are not interchangeable with time intervals, although either type of duration may be added to or subtracted from a value that represents a date.
Calculations that use calendar duration units maintain the day number of the month when possible. For example, adding two months to January 31 results in March 31. Adding one month to January 31 results in February 28 (most years) or February 29 (leap years), because January 31 is the last day of the month and February has either 28 or 29 days.
In this case, the lastDayOfMonthCalculation global property (which defaults to true) controls whether the calculation is done in this way. Setting that global property to false would make that addition result in March 3 or March 2 instead (equivalent to the non-existent date February 31).
Calendar duration units can be expressed in multiple ways:
month,months,calendarMonth,calendarMonths,calMonth,calMonthscalendarQuarter,calendarQuarters,calendarQtr,calendarQtrs,calQuarter,calQuarters,calQtr,calQtrsyear, calendarYear,calendarYears,calYear,calYearsdecade, calendarDecade,calendarDecades,calDecade,calDecadescentury, calendarCentury,calendarCenturies,calCentury,calCenturies
For a full discussion of units, see Using Numbers with Units.
Example:
// Subtract four months from a date
set startDate to "January 31, 2018"
put startDate - 4 months into subtract4Months
put subtract4Months -- "October 1, 2017"
Example:
// Add non-leap years and leap years
set startDate to "January 31, 2018"
put startDate + 1 month into nonLeapYear
put nonLeapYear -- "Feb 28, 2018"
set leapYearDate to "January 31, 2016"
put leapYearDate + 1 month into leapYear
put leapYear -- "Feb 29, 2016"
Tests written in older versions of Eggplant Functional might include workarounds for calculations involving months and quarters. The addition of calendar duration values means that those older tests might produce different results.
Byte Sizes
Files and blocks of data are usually measured in bytes, and often get quite large. To simplify working with these data sizes, SenseTalk allows you to express them in a natural way, using the terms bytes, kilobytes (or KB), megabytes (or MB), gigabytes (or GB), or terabytes (or TB) as shown in these examples:
if the diskspace is less than 5 megabytes then put "5 MB warning"
if the size of file logFile > 256 KB then trimLogFile
put (the size of file movie) / 1 MB into movieSizeInMegabytes
Binary Data
Some applications, such as those that manipulate sounds or images at a low level, may need to deal directly with binary data. For situations where you need to create or compare binary data of any size, SenseTalk provides binary data literals. Data literals are written as any even number of hexadecimal digits enclosed in angle brackets < >. Spaces and new lines in the data literal are ignored:
put <AF326B47 0058D91C> into value64