You are here:

Local and Global Properties for Working with Values

The SenseTalk global and local properties described here affect the way a variety of values are formatted or converted from one type to another (e.g., converting data to text).

Setting or Changing Local and Global Property Values

You can set a global property value with the SenseTalk commands Set or Put. Note that when you reference one of these properties, you must use the word the before the property name to distinguish it from an ordinary variable.

Examples:

set the searchrectangle to [1,2,2,3]

put 2 into the remoteworkinterval

You can add or change specific named properties within a global property like this:

set the namedColors.pink to color("RGB,1.0,0.5,0.5") -- Adds pink to the namedColors global property and defines its RGB color value

set the listFormat's separator to " & " -- Sets the separator property of the listFormat global property

Properties can also be set or updated by using the setoption or setoptions commands. The setoption command lets you update a single property, and setoptions lets you update multiple properties.

Examples:

setoption searchrectangle, [1,2,2,3]

setoptions {searchrectangle: [1,2,2,3], scriptlogging: yes}

Note: Because setoption and setoptions are specific for use with global and local properties, you omit the word the from the property name in the command syntax for these commands.

For additional information about working with local and global properties, see Local and Global Properties in SenseTalk.

On this page:

the numberFormat Local Property, the defaultNumberFormat Global Property

the defaultQuoteFormat Global Property

the caseSensitive Local Property

the clockFormat Global Property

the timeFormat Global Property

the timeInputFormat Global Property

the centuryCutoff Local Property

the defaultCenturyCutoff GlobalProperty

the lastDayOfMonthCalculation Global Property

the colorFormat Global Property

the namedColors Global Property

the defaultDataFormat Global Property

the booleanComparison Global Property

the asTextLimit Global Property

the endValue Global Property

the matchesCanOverlap Global Property

the patternCharacterMode Global Property

the patternTimeout Global Property

the bitLength Global Property

the numberFormat Local Property, the defaultNumberFormat Global Property

Values: A string made up of a combination of 0s and/or #s, and optionally a decimal point. The 0s to the left of the decimal point indicate how many places will appear in the number, being filled with 0 if the place has no value in the number being formatted. Use #s to the right of the decimal point to have decimal places appear only if they have value. Use 0s to have decimal places appear whether they have value or not.

Default:

For the numberFormat: The current value of the defaultNumberFormat global property
For the the defaultNumberFormat: 0.######

Behavior: Use these properties to specify the number of decimal places to use, and number of leading and trailing zeros to show when a numeric value (such as the result of a mathematical operation) is converted to a textual representation.

the numberFormat property is local to each handler. Setting its value in one handler doesn't affect its value in other handlers called from that handler, or vice versa. When each handler begins running, the numberFormat in that handler is initially set to the value of the defaultNumberFormat global property. The global property, the defaultNumberFormat, is originally set to 0.######, but can be changed if desired.

You can also set the numberFormat to one of these special values:

hexadecimal or hex: Displays numbers in hexadecimal format.
octal: Displays numbers in octal format.
binary: Displays numbers in binary format.
words, Words, or WORDS: Displays numbers as words with the corresponding capitalization.

If you want to set the minimum number of digits to display, follow a special value with a number, such as "binary 16". Where necessary, leading zeros are added to make up the minimum length.

Example:

set the numberFormat to "#.###" -- Up to 3 decimal places

Example:

set the numberFormat to "0.00" -- 2 decimal places always

Example:

set the numberFormat to "00.##"

put 3.41 -- Displays 03.41

Example:

set the numberFormat to "00.###"

put 3.41 -- Displays 03.41

Example:

set the defaultNumberFormat to "0.000"

put 3.41 -- Displays 3.410

Example:

set the defaultNumberFormat to "0"

put 3.41 -- Displays 3

Example:

set formatExpression to "0.000"

get the numberFormat

log it // Displays '0.######'

set the numberFormat to formatExpression

get the numberFormat

log it // Displays '0.000'

Example:

set the numberFormat to "hex 4" // Displays numbers as four hexadecimal digits

put 13 —> 0x000D

set the numberFormat to "octal"

put 13 —> 0o15

set the numberFormat to "binary8"

put 13 —>0b00001101

set the numberFormat to "Words"

put 127 —>One Hundred Twenty-Seven

the defaultQuoteFormat Global Property

Values: None (or empty) for no quoting; Standard for standard quoting; or any other string or a list of two strings.

Default: None

Behavior: the listFormat and the propertyListFormat global properties both include an optional quotes value that specifies how values in those containers are quoted when converted to text. the defaultQuoteFormat global property provides the quoting behavior when either of these quotes values is not given (which is the default case for lists, but not for property lists).

The value of any of these quoting properties can be empty or None for no quoting, Standard for standard quoting, or can be any other string or a list of two strings. If you provide a list of two strings, they are used as the opening and closing quote (before and after the value) respectively. If you provide a single string, it is used as both the opening and closing quote.

Standard quoting automatically chooses either a straight double quote character (") or double angle brackets ("<<",">>"), depending on the value's content. Whenever values are quoted, any value containing the final quote string or a return character is automatically turned into a valid SenseTalk expression that yields the proper value.

Example:

set the defaultQuoteFormat to "#"

put (1,2,3,4) -- (#1#,#2#,#3#,#4#)

Example:

set the defaultQuoteFormat to "Standard"

put (<<"Hello">>,42,"GO"&return)-- (<<"Hello">>,"42","GO" & return)

Example:

set the defaultQuoteFormat to "None"

put (<<"Hello">>,42,"GO"&return) -- ("Hello",42,GO )

the caseSensitive Local Property

Values: True, False

Default: False (set at the beginning of each handler)

Behavior: This local property determines whether uppercase and lowercase letters are evaluated differently by text comparison operators. For instance, you could set this property to true if you want "Capital" and "capital" to evaluate as not the same, but leave it set to false if you want them to be equal.

Example:

put "Robin" into name

put "robin" into bird

put textdifference(name,bird) // Returns 0

set the caseSensitive to true

put textdifference(name,bird) // Returns 1

Example:

set ghost to "BOO"

set babyghost to "boo"

put babyghost is ghost // Returns 'True'

set the casesensitive to true

put babyghost is ghost // Returns 'False'

the clockFormat Global Property

Values: 12 (or 12 hour), 24 (or 24 hour)

Default: 12 hour

Behavior: Determines if time values are displayed in 24-hour or 12-hour format. For example, a 12-hour time would display 03:17 PM while the same time in 24-hour format displays 15:17. The 12-hour time format includes AM or PM as part of the value.

Example:

put the time // Displays '03:16 PM'

set the clockFormat to 24

put the time // Displays '15:16'

the timeFormat Global Property

Values: A property list holding all the standard date and time formats supported by the convert command and the various formatted date and time functions.

Default: As described above in Values. Use this command to see a list of all the formats included in the timeFormat:

put the keys of the timeFormat

Behavior: This global property is used to provide the appropriate formatting when you call a date/time value by its name. For example, if your code requests the international date, SenseTalk uses the timeFormat property to look up how that date/time value should be displayed. See the convert command in Date and Time Values in SenseTalk for a list of date/time values with default formatting examples.

Any of the formats can be examined or changed (as shown in the examples below). Use caution when making changes to avoid deleting formats that you need, or accidentally replacing the entire set of formats with one value.

For complete information about how date/time formats are defined in SenseTalk, see SenseTalk Date and Time Formats.

Example:

put the timeFormat.ShortDateItems // "[year],[mo],[da],[hr24],[mi],[se]"

Example:

set the timeformat's date to "[weekday], [monthName] [d]."

put the date into mydate

add 30 weeks to mydate

log mydate // Displays 'Friday, March 2.'

Example:

put the long date // "Wednesday, October 19, 2005"

delete the first word of the timeFormat's longDate

put the long date // October 19, 2005

the timeInputFormat Global Property

Values: You can set the value of the timeInputFormat to one of the following:

a single format value, Natural, iso8601, or empty
a list of format values
a property list containing format values (however, see note below)

Default: the timeFormat values

Behavior: the timeInputFormat global property is a list that specifies all of the date and time formats that are used in recognizing whether a text string is valid as a date/time value. By default, this property is dynamically linked to the values of the timeFormat global property so that date or time strings can be recognized in any format contained there.

For information about the Natural format see Natural Format below. SenseTalk also supports the ISO 8601 formats as described in iso8601 Format below.

When SenseTalk tries to interpret a value as a date/time value that isn't already in that format internally, it follows a three-step process:

If the value is a number, SenseTalk treats it as the number of seconds since the beginning of January 1, 2001.
If the value is in one of the dateItems formats (a list or comma-delimited text list of 5, 6, 7, or 8 numbers), it is interpreted accordingly.
If the value is text, SenseTalk goes through each item in the timeInputFormat in the order listed to see if the value matches that format. The first matching format is used to translate the value.

This process of interpreting dates and times is used by many operations, including such things as the is a date operator, the date() function and related functions, and operations such as addition that try to implicitly interpret a string as a date/time value.

For complete information about how date/time formats are defined in SenseTalk, see SenseTalk Date and Time Formats.

Example:

set the timeInputFormat to Natural // Most formats accepted

Example:

set the timeInputFormat to "" // Reset default behavior

Example:

set the timeInputFormat to iso8601 // Set the format to ISO 8601 supported formats

Example:

insert "[da]/[mo]/[yr]" before the timeInputFormat // Prefer European interpretation of dates

put "12/2/98" into subscription

add 30 days to subscription

log subscription // Displays '14/03/98'

Example:

put "%A, %B %e." into the timeInputFormat // Prevents values that are formatted differently, such as 05/25/80, from being recognized as dates

set mydate to "Wednesday, December 3."

subtract 1 week from mydate

log mydate // Logs 'Sunday, November 26.'

put "05/25/80" is a date // Displays 'False'

set the timeInputFormat to empty // Resets the timeInputFormat to the default behavior.

put "05/25/80" is a date // Displays 'True'

Note: If you set the value to a property list (or linked to the timeFormat), SenseTalk uses only the values from the property list. That is, you can set the global property to a proprety list, but the timeInputFormat doesn't store values as property lists. It removes the keys, and stores only the values as a list.

SenseTalk orders the formats in the sorted key order of the property list. The exception to this is when one format is a prefix of another. In this case, the format is always placed later in the list to allow the longer format to match first. Also, if any format allows two-digit years (using [yr]), the equivalent format for four-digit years ([year]) is automatically added to the list ahead of the two-digit version of that format.

Tip: Setting the value to empty dynamically links it to the timeFormat values again (its initial default state).

Tip: If you set the value to a list of formats, be sure to order them with longer formats first. SenseTalk interprets time values using the first matching format even if it matches only part of the text.

Natural Format

In addition to specific format strings, the value Natural can be used to allow SenseTalk to interpret some natural language phrases that have time implications as date/time values. This format option accepts phrases such as "yesterday," "afternoon," or "at lunch on Tuesday" and many others.

Be aware that this setting, while using sophisticated techniques to arrive at a "best guess" of the value, can in some cases be overly aggressive about treating values as dates/times. When used in a list, Natural should be the last item in the list to allow other specific formats to match in a controlled priority order first.

iso8601 Format

SenseTalk supports ISO 8601 standard date and time formats. For more information about the standard, see this article about the ISO 8601 format.

Date formats: Begin with four digits for the year, followed by two digits for the month, and two digits for the day. Dates must begin with the year, which must be four digits long, using leading zeros for years before 1000. The month and day are optional, but including the day without the month is not permitted. If the day is omitted, the first day of the month is assumed. If both the month and day are omitted, January 1 is assumed. If a date is given without a time, SenseTalk assigns a time of noon on the given date.
Date separators: The year, month, and day can be separated by a space, dash, or period as shown in the following examples.
Example:
2015-11-13 -- November 13, 2015
Example:
1959.05.11 -- May 11, 1959
Example:
2000 01 01 -- January 1, 2000
Time formats: Begin with two digits for the hour, followed by two digits for the minute, followed by two digits for the second. If a time is given, the time format must begin with the hour. The minute and second are optional. However, the second cannot be included if the minute is not also included. If omitted, SenseTalk assumes the minute and second are zero. The second may be followed by a decimal point (or comma) and a fraction of a second.
Time separators: The hour, minute, and second can be separated by a colon or space. If both date and time formats are included, the date format must come first, and can be separated from the time format by a space or a capital letter T. A date/time value can be followed by the capital letter Z to designate a zero offset from UTC (Coordinated Universal Time) or a + (plus) or a - (minus) followed by either two or four digits to indicate the number of hours, or hours and minutes offset from UTC.
Example:
12:15:20 -- 15 minutes and 20 second past noon
Example:
09 30 15 -- 30 minutes and 15 seconds past 9 am
Example:
11:00:00 -- 11 am, minutes and seconds were not specified

SenseTalk does not treat an all-numeric value (all digits and possibly a decimal point) as date/time. If you want SenseTalk to recognize a value as an ISO 8601 date/time, the value must include any of the following:

a separator between elements
the letter T after the date or before the time (or between the date and time if both are given)
the letter Z or a time zone offset at the end.

the centuryCutoff Local Property

Values: An integer from 0 to 99; a negative number, or empty

Default: the defaultCenturyCutoff global property, which is initialized to 10 years in the future

Behavior: This local property controls the interpretation of two-digit numbers into four-digit years when converting strings to dates. When a two-digit year is encountered, it is assumed to be in the present year or a future year up through the year indicated by the centuryCutoff. Otherwise, a two-digit year that is greater than the centuryCutoff value is taken to be in the past (either earlier in the present century or in the previous century).

To disable this functionality and allow two-digit years to represent years in the first century of the common era, set the centuryCutoff to a negative number or to empty.

Example:

set the centuryCutoff to 26

put international date of "3/16/26" -- 2026-03-16

set the centuryCutoff to 25

put international date of "3/16/26" -- 1926-03-16

set the centuryCutoff to empty

put international date of "3/16/26" -- 26-03-16 (the year 26 in the first century of the common era)

the defaultCenturyCutoff Global Property
the timeFormat Global Property

the defaultCenturyCutoff GlobalProperty

Values: An integer from 0 to 99; a negative number, or empty

Default: 10 years in the future

Behavior: If the centuryCutoff local property is not set, this global property is used for interpretation of two-digit numbers into four-digit years when converting strings to dates. This property works the same and has the same capabilities as the centuryCutoff local property. Adjust the defaultCenturyCutoff value if you want all handlers to interpret dates with a different cutoff date.

Example:

set the defaultCenturyCutoff to 26

put the abbreviated international date of "3/16/26" // Displays '2026-03'

set the defaultCenturyCutoff to 25

put the abbreviated international date of "3/16/26" // Displays '1926-03'

set the defaultCenturyCutoff to empty

put the abbreviated international date of "3/16/26" // Displays '0026-03' (the year 26 in the first century of the common era)

the centuryCutoff Global Property
the timeFormat Global Property

the lastDayOfMonthCalculation Global Property

Values: True or False.

Default: True

Behavior: Controls whether calendar date arithmetic favors the last day of a month. SenseTalk allows adding or subtracting a number of calendar months, quarters, or years from a starting date to calculate an ending date. For example, "November 13" + 6 months results in "May 13". Because months are different lengths, this sometimes presents a dilemma when the starting date is at or near the end of a month. When the lastDayOfMonthCalculation is set to the default (true), SenseTalk ensures that these calendar date calculations will always result in the correct month. If the starting date is the last day of the month, or is a day that would be beyond the end of the resulting month, the ending date calculated will be the last day of the resulting month:

Example:

set startDate to "January 31, 2018"

put startDate + 1 month into newDate

put newDate // "February 28, 2018"

Example:

put "September 30" + 1 calendarQtr -- "December 31"

put “August 31” + 1 month -- “September 30"

If the lastDayOfMonthCalculation is set to false, the resulting end date will be the same day of the month as the starting date if possible. If the resulting month has fewer days, then a day that is higher than the last day of that month will carry over into the first days of the following month:

Example:

set the lastDayOfMonthCalculation to false

set startDate to "January 31, 2018"

put startDate + 1 month into nextDate

put nextDate // "March 3, 2018"

Example:

put "September 30" + 1 calendarQtr -- "December 30"

put “August 31” + 1 month -- “October 1"

the colorFormat Global Property

Values: Basic, Alpha, HTML, W, WA, RGB, RGBA, HSB, HSBA, CMYK, or CMYKA

Default: Basic

Behavior: the colorFormat is a global property that specifies the format to use when a value represented internally as a color is converted to a textual representation. Basic is a list of three integers from 0 to 255 representing the levels of red, green, and blue in the color. The Alpha format adds a fourth integer from 0 to 255 representing the opacity of the color (with 0 being completely transparent).

The HTML format presents a color as a hexadecimal number preceded by “#” (such as “#FF0000” for red). The other formats are text lists beginning with the format identifier, followed by one or more component values from 0.0 to 1.0 indicating the level of each color component. The colorFormat is initially set to Basic.

Example:

set the colorFormat to "Basic"

put color("red") -- Displays "255,0,0"

Example:

set the colorFormat to "HSB"

put color("green")-- Displays "HSB, 0.333, 1.000, 1.000"

Example:

set the colorFormat to "HTML"

put coloratLocation("IndicatorLight") // Displays the returned color in HTML format (i.e. #E99820)

Example:

set the colorFormat to "HTML"

put colorAtLocation("IndicatorLight") into myColor // Stores the return into variable "myColor"

log color(myColor) is "#E99720" // Determines whether the color stored in myColor is equivalent to #E99720

Example:

if the keys of the namedcolors does not contain "gold" then Set the namedColors.Gold to (128,128,0) // Checks whether "Gold" is already a named color, and if not, adds it to the property list

log the keys of the namedcolors // Logs the names of all of the named colors

set the colorFormat to "Alpha" // Changes the color format from basic to alpha

log the namedColors.Gold // Logs the value of Gold (128,128,0)

log color("Gold") // Logs the color of Gold, represented in alpha (128,128,0,255)

the namedColors Global Property

Values: A property list whose keys are color names and whose values are colors defined based on the current value of the colorFormat global property.

Default: A property list with the following colors as keys: Aqua, Black, Blue, Brown, Clear, Cyan, DarkBlue, DarkGray, DarkGreen, DarkGrey, DarkRed, Fuchsia, Gray, Green, Grey, LightGray, LightGreen, LightGrey, Lime, Magenta, Maroon, Navy, Olive, Orange, Purple, Red, Silver, Teal, White, and Yellow. The values for each key (color name) are initially set to Basic (the default for the colorFormat).

Behavior: the namedColors property defines the colors that can be specified by name in a script. The default set includes many common colors you might use. You can add your own custom colors to the default set so that you can refer to a custom color by name instead of by color values.

Example:

put the namedColors // Displays the property list showing all available colors and their values in Basic color format

Example:

put the namedColors's red // Displays '(255,0,0)'

Example:

put the keys of the namedColors -- Lists all available color names

Example:

set the namedColors.pink to color("RGB,1.0,0.5,0.5") -- Defines pink

set the namedColors.dawn to color("pink")

put color of "dawn"-- Shows "255,128,128" (if the colorFormat is Basic)

Example:

put coloratlocation("ColorArea") into myColor // Stores the color of the pixel at the location of the hot spot of the ColorArea image

assert that mycolor is color(121,244,128)

set the namedcolors.kindagreen to color(121,244,128)

assert that mycolor is color("kindagreen")

the defaultDataFormat Global Property

Values: text, hex, base64, size, auto

Default: text

Behavior: When a value is converted from data to text, the current setting of the defaultDataFormat global property controls how it is represented.

With the text setting, the defaultStringEncoding global property is used to control how the binary data is interpreted as text. the defaultDataFormatcan also be set to text: <encodingName> to use a specific encoding, such as text: UTF-16. Depending on the encoding you use, and the particular characters that appear in the text, the resulting data can have exactly one byte for each character in the original text, or there could be two or more bytes for some or all of the characters.

The hex (or hexadecimal) format displays two hexadecimal digits for every byte of data, enclosed in angle brackets. This format is recognized by SenseTalk within a script for literal data values, so the value() function can be used to convert text in this format back to binary data.

The base64 format is a more compact representation of the bytes, using 64 different text characters to encode the data. The base64Decode() function can be used to read text in this format and convert it back to binary data.

The size format is the most abbreviated format, which simply indicates the size of the data (for example, <data: 42516 bytes>). This format is a useful representation for displaying potentially large chunks of binary data to the user, but it cannot be used for storage because the data itself would be lost.

The auto format automatically chooses the size format for large binary data (more than 64 bytes), and the hex format for smaller sizes. Use a format of auto: <limit> to specify a limit different than 64 bytes (for example, auto: 16 to display no more than 16 bytes of data in hex format).

Example:

set myData to "The cat in the hat was a mighty fine cat." as data -- Set a variable to contain data

-- The standard setting of the defaultDataFormat is text, which converts the data to text using the defaultStringEncoding

put "", the defaultDataFormat & " => " & myData

set the defaultDataFormat to "text: Unicode (UTF-7)" -- Interpret data as text using a different encoding

put "", the defaultDataFormat & " => " & myData

set the defaultDataFormat to "hex" -- Show data in hexadecimal format