Lists
Lists and property lists provide two convenient and powerful ways to organize and manipulate data within your scripts. This section presents the key things you must know to fully exploit the power of lists.
For more information about working with lists, see Chunk Expressions, and the control structure discussion in Repeat with Each.
In addition to lists and property lists, SenseTalk provides a hierarchical tree structure, which is described in Using XML and Tree Structures in SenseTalk Scripts.
Creating Lists
Create a list in a script by listing one or more expressions separated by commas and enclosed in square brackets [ ]
. Lists can also be enclosed in parentheses ( )
if the entire list is on a single line. Lists that are enclosed in square brackets may be written across multiple lines by including a line break after any item within the list (this will not work for lists enclosed in parentheses). Using square brackets is recommended as it makes the list syntax clear and consistent, as well as distinct from other script elements.
Syntax:
[ expr { , expr}... ]
( expr { , expr}... )
{ expr { , expr}... }
[ ]
{an} empty list
Prior to SenseTalk 2.00 (Eggplant Functional 20.1), both lists and property lists used parentheses () by default instead of square brackets [] or curly braces (respectively). Parentheses are still considered valid syntax for lists, but their use is not recommended as it can lead to confusion.
Example:
put [1,3,5,7,9] into oddList
Example:
put [["dog", "Fido"], ["cat", "Cleo"]] into nestedList // Creates a list of lists
Example:
set myList to ["sandwich",49,the date]
Example:
set TestEnvironments = ["Windows","MacOSX","Android","iOS"]
Example:
Lists can also span multiple lines using square [] brackets:
set searchPaths to [
"/Library/WebServer/Documents",
"~/Documents",
"/Users/hemingway/Documents/temp/ImportantStuff" ]
Lists, including lists containing other lists or property lists, can be passed as parameters. For more on lists as parameters, see Parameters and Results.
List Contents
Include any type of value in a list, including other lists and property lists.
You can also use expressions when constructing lists:
Example:
put ["geranium", pi * (2 * radius), {age:42}] into mixedList // "pi_* (2 * radius)" is an expression, and "{age:42}" is a property list
Example:
put [1,[2,[3,4]],5] into nestedList // Stores the list '[1,[2,[3,4]],5]' into a variable.
Single-Item Lists
Single item lists made using square brackets [] are identified as a list by SenseTalk. No commas are required, because the square brackets indicate that the single item is a list.
Example:
put [12] into shortList // This makes a list with one item
When a single value is enclosed in parentheses in a script, the parentheses are treated as a grouping operator, so that value will not be treated as a list. To make SenseTalk recognize a single item in parentheses as a list, include a comma after the value:
Example:
put (12,) into shortList // This makes a list with one item
Treatment of Single-Item Lists as a Single Value
For many purposes, a list containing a single item can be treated the same as a single (non-list) value.
Example:
In the example below, myList
is set to [4]
, that is, a list containing a single item that is the number 4. Another number is added to this value as if it were a non-list value. Following this basic arithmetic, the variable theSum
contains the number 6.
put [4] into myList -- Creates a single-item list
put myList + 2 into theSum -- This will add 2 to the single list item '4' as if it were a single non-list value
put theSum --> 6
Normally, when accessing such a list as text, the value shows in square brackets. To avoid this behavior, set the prefix
and suffix
properties of the listFormat
to empty.
Empty Lists
To create an empty list, use an empty pair of square brackets, or the phrase empty list
:
Example:
put [] into newlist // newlist is now a list with no items
put 16 into item 1 of newlist // [16]
put empty list into item 2 of newlist // [16,[]]
Inserting Items into a List
Use the Insert
Command to insert items before, into, or after a list or any item of a list. Insert
always treats the destination container as a list, and will turn it into a list if it is not one already.
Example:
put "abc" into myVar // Stores 'abc' in a variable as text (not actually a list)
put "de" after myVar // Appends 'de' to 'abc' resulting in 'abcde' (still not a list)
insert "xyz" after myVar // Creates a list using the myVar variable contents 'abcde' as the first list item, and 'xyz' as the second, resulting in the list ["abcde","xyz"]
insert 24 before item 2 of myVar // Inserts an additional item into the list, resulting in the list ["abcde",24,"xyz"]
Example:
put "First, let's connect to our SUT." into instructions // Populates variable instructions with a text string
insert "Next, let's enter Capture Mode." after instructions // Inserts a second text string in order to create a list
put instructions // Displays [First, let's connect to our SUT. Next let's enter Capture Mode.], which appears like a 4-item list based on comma position but is actually a 2-item list
set the listFormat to {prefix:"(",suffix:")",separator:"|"} // Changes the listFormat to separate list items with | instead of comma
put instructions // Displays (First, let's connect to our SUT.|Next, let's enter Capture Mode.) making it clear there are only 2 items in the list and not 4
When inserting a list of items into another list, there are two possible ways to complete the insertion. The default mode, known as “item by item," is to insert each item from the source list into the destination list:
Example:
put [1,2,3,4] into list // [1,2,3,4]
insert [A,B] after item 2 of list // Item 2 of list // -- [1,2,A,B,3,4]
It is also possible to insert a list into another to create a nested list by using the nested
keyword:
Example:
put [1,2,3,4] into list // [1,2,3,4]
put ["A","B"] into otherList // [A,B]
insert otherList nested after item 2 of list // [1,2,[A,B],3,4]
To control the standard insertion behavior, set the listInsertionMode
local property or the defaultListInsertionMode
global property to either "nested" or "item by item":
Example:
put [1,2,3] into aList
set the listInsertionMode to "nested"
insert [4,5] into aList // [1,2,3,[4,5]]