# 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

Note: 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.

## 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 seven true constants (empty, return, true, false, up, down, 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. carriageReturncreturncr A "carriage return" character. The same as numToChar(13). linefeedlfnewline 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. up The word "up". down The word "down". 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, up, down, and end. The other words are predefined variables, which can have other values stored into them by your script.

Note: 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:

The symbols provided include:

Common Symbols

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 (\$)

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 (¾)

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 (☹)

### 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 and Property 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 (see Lists and 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.

Note: 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, calMonths
• calendarQuarter, calendarQuarters, calendarQtr, calendarQtrs, calQuarter, calQuarters, calQtr, calQtrs
• year, calendarYear, calendarYears, calYear, calYears
• century, 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"

Important: 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

Note: In SenseTalk, you can use numbers, either as numerals or text, for many types of operations and comparisons. Read Using Numbers with Units to find out how.

This topic was last updated on January 19, 2022, at 05:39:44 PM.

Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant