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).

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

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.

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'

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

Related:

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:

  1. If the value is a number, SenseTalk treats it as the number of seconds since the beginning of January 1, 2001.
  2. 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.
  3. 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)

Related:

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)

Related:

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)

Related:

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")

Related:

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

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

 

set the defaultDataFormat to "size" -- Show just the number of bytes, not the data

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

 

set the defaultDataFormat to "auto" -- Show as hex, or size if more than 64 bytes

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

 

set the defaultDataFormat to "auto: 30" -- If more than 30 bytes, will show as size

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

 

set the defaultDataFormat to "base64" -- Show data using base64 encoding

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

Related:

the booleanComparison Global Property

Values: Normal, Strict, Lenient

Default: Normal

Behavior: This global property controls how Boolean matches are made. When set to Normal, the values Yes and On compare as equal to True (or each other); and Off and No compare as equal to False. When an empty object is evaluated by itself, it is equivalent to a Boolean value of False. However, if an empty object is compared to the specific value False, they are not equivalent. The difference in this case is between evaluation and comparison.

If the booleanComparison is set to Strict, the values Yes, No, On, and Offcompare as strings, and thus are not equal to True or False. If the booleanComparison is set to Lenient, any value that evaluates to the strings Yes, No, On, or Off will be treated as Booleans for purposes of equality testing with other Booleans.

Example:

put Yes is true -- True

put off = false -- True

set the booleanComparison to "Strict"

put yes is true -- False

put off = false -- False

the asTextLimit Global Property

Values: A number representing the maximum characters

Default: 10,000,000 characters

Behavior: This property controls the maximum size of internally generated text representations of values. If a text representation is requested that exceeds this limit, an exception is thrown. This limit protects the system from possible crashes caused by extremely large values.

Example:

set the asTextLimit to 20 million

Related:

the endValue Global Property

Values: A string

Default: "    ⓔ ⓝ ⓓ    " (Note that this string includes several nonstandard space characters before, after, and between the visible characters.)

Behavior: This property is the value returned by iterators when no more values are available. The purpose of the endValue is to provide a unique string that, when returned, lets you know you've reached the end of your data.

Note: the endValue also sets the value for the end constant. Keep in mind that if you change the property value, you are also changing the value of the constant.

Example:

set the endValue to "MyCrazyString*&^%"

put end // MyCrazyString*&^%

the matchesCanOverlap Global Property

Values: True, False

Default: False

Behavior: This property controls whether multiple pattern matches within a string can overlap or be nested. When set to False and a pattern match is found, the search for the next match begins with the character after the previous match. When set to True, a search for the next pattern match begins with the second character in the preceding pattern match.

The setting of this property affects the results returned by the every match, every range, every occurrence, and every offset functions when used with patterns, and when requesting a particular match, range, occurrence, or offset, as with the third occurrence of pattern in text.

Example:

put every match of <3 digits> in "123456" --> ((text:"123", text_range:"1" to "3"),(text:"456", text_range:"4" to "6"))

set the matchesCanOverlap to true

put every match of <3 digits> in "123456" --> ((text:"123", text_range:"1" to "3"),(text:"234", text_range:"2" to "4"),(text:"345", text_range:"3" to "5"),(text:"456", text_range:"4" to "6"))

Related:

the patternCharacterMode Global Property

Values: Text, Line

Default: Text

Behavior: This property controls whether the term characters (or chars) includes line separators in pattern matches. When set to Text, characters matches any characters throughout the entire text, including line separators. If set to Line, only characters within a line can be matched, not line separators.

Example:

set fileName to <beginning of line,

{name:max chars then "."},

{extension:chars}, end of line>

 

set fileList to {{

geraldine.txt

transcript.10.29.18.txt

sunburst.png

}}

set the patternCharacterMode to "text"

put the first occurrence of fileName in fileList // Displays the whole list because the pattern considers the entire text, regardless of line breaks

set the patternCharacterMode to "line"

put the first occurrence of fileName in fileList // Displays only the first item because the pattern is restricted to a single line

Related:

the patternTimeout Global Property

Values: Time (in seconds if no unit is given)

Default: 30

Behavior: This property controls the maximum time taken on any single pattern search. If a pattern search takes longer than the set time, an exception is thrown.

Example:

set ssn to<3 digits then "-", 2 digits then "-", 4 digits>

set the patternTimeout to 10

log every occurrence of ssn in sourceText

Related:

 

This topic was last updated on July 16, 2019, at 06:03:14 PM.

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