You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* in Objects, fixed bug in timer object constructor (direct parameters in library handlers can't be optional, so timer name now uses keyword parameter instead)
* Date library now runs tests in multiple time zones (and currently fails on them too)
* revised various conversion handlers in TypeSupport for improved reuse and greater strictness (e.g. `asNumber[Parameter]`, `asInteger[Parameter]` etc now reject booleans, month and weekday constants, etc)
* documentation improvements
Copy file name to clipboardExpand all lines: List.scptd/Contents/Resources/List.sdef
+87-39Lines changed: 87 additions & 39 deletions
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,8 @@
2
2
<!DOCTYPEdictionary SYSTEM "file://localhost/System/Library/DTDs/sdef.dtd">
3
3
<dictionary>
4
4
5
+
<!-- TO DO: finish `sort list` documentation -->
6
+
5
7
<suitename="Modify"code="****">
6
8
7
9
<commandname="insert into list"code="Lst:Inst"description="insert an item (or items) into the given list, returning a new list">
@@ -53,15 +55,15 @@ delete from list {1, 2, 3, 4, 5} to item 3 → {4, 5}</code></pre>
53
55
<resulttype="list"/>
54
56
<documentation>
55
57
<html><![CDATA[
56
-
<p>The <code>using</code> parameter's script object must implement a handler named <code>mapItem</code> that takes a value as its input and returns a new value as its output.</p>
58
+
<p>The <code>using</code> parameter's script object must implement a handler named <code>mapItem</code> that takes a value as its input and returns a new value as its output. The following example demonstrates how to map a list of numbers to create a new list where each item is the square of its original value:</p>
57
59
58
-
<pre><code>script DoubleNumber
60
+
<pre><code>script SquareNumbers
59
61
to mapItem(aValue)
60
-
return aValue * 2
62
+
return aValue ^ 2
61
63
end mapItem
62
64
end script
63
65
64
-
map list {1, 2, 3} using DoubleNumber → {2, 4, 6}</code></pre>
66
+
map list {1, 2, 3, 4, 5} using SquareNumbers → {1, 4, 9, 16, 25}</code></pre>
65
67
]]></html>
66
68
</documentation>
67
69
</command>
@@ -73,7 +75,7 @@ map list {1, 2, 3} using DoubleNumber → {2, 4, 6}</code></pre>
73
75
<resulttype="list"/>
74
76
<documentation>
75
77
<html><![CDATA[
76
-
<p>The <code>using</code> parameter's script object must implement a handler named <code>reduceItem</code> that takes two values as its input and returns a new value as its output.</p>
78
+
<p>The <code>using</code> parameter's script object must implement a handler named <code>reduceItem</code> that takes two values as its input and returns a new value as its output. The following example demonstrates how to reduce a list of numbers to the sum of all its items:</p>
77
79
78
80
<pre><code>script SumNumbers
79
81
to reduceItem(partialResult, aValue)
@@ -92,7 +94,17 @@ reduce list {5, 1, 9, 3} using SumNumbers → 18</code></pre>
92
94
<resulttype="list"/>
93
95
<documentation>
94
96
<html><![CDATA[
95
-
<p>This uses AppleScript’s <code>is in</code> operator to determine if each item has already appeared in the list. When processing lists of text, wrap the <code>remove duplicates from list</code> command in <code>considering</code>/<code>ignoring</code> blocks as necessary.</p>
97
+
<p>For example:</p>
98
+
99
+
<pre><code>remove duplicates from list {"A", "b", "c", B", "E", "b"} → {"A", "b", "c", "E"}</code></pre>
100
+
101
+
<p>Be aware that this command uses AppleScript’s standard <code>is in</code> operator to check if each item has previously appeared in the list. When working with lists of text, for example, you may want to wrap the <code>remove duplicates from list</code> command in an appropriate <code>considering</code>/<code>ignoring</code> block to ensure predictable behavior whenever that code is executed. For example, wrapping the previous command in a <code>considering case</code> block alters the way in which text items are compared:</p>
102
+
103
+
<pre><code>considering case
104
+
remove duplicates from list {"A", "b", "c", B", "E", "b"} → {"A", "b", "c", "B", "E"}
105
+
end considering</code></pre>
106
+
107
+
<p>(Similarly, when working with lists of real numbers, be aware that two fractional numbers that appear identical can sometimes compare as <code>false</code> due to the limited accuracy of that data type. For example, <code>0.7 * 0.7 ≠ 0.49</code>(!) due to tiny imprecisions in the CPU’s floating point math calculations.)</p>
96
108
]]></html>
97
109
</documentation>
98
110
</command>
@@ -105,7 +117,21 @@ reduce list {5, 1, 9, 3} using SumNumbers → 18</code></pre>
105
117
<resulttype="text"/>
106
118
<documentation>
107
119
<html><![CDATA[
108
-
<p><code>slice list theList from i to j</code> is similar to <code>get items i thru j of theList</code>, except that it returns an empty list if the start index is greater than the end index, and doesn’t throw an error if an index is out of range.</p>
120
+
<p>This command works similarly to <code>get items i thru j of theList</code>, except that it returns an empty list if the start index is greater than the end index, and doesn’t throw an error if an index is out of range. (Index 0 is still forbidden though, as AppleScript lists are 1-indexed.) For example:</p>
121
+
122
+
<pre><code>slice list {"a", "b", "c", "d", "e"} from item 4 → {"d", "e"}
123
+
124
+
slice list {"a", "b", "c", "d", "e"} from item 2 to item -2 → {"b", "c", "d"}
125
+
126
+
slice list {"a", "b", "c", "d", "e"} from item 3 to item 3 → {"c"}
127
+
128
+
slice list {"a", "b", "c", "d", "e"} to item 2 → {"a", "b"}
129
+
130
+
slice list {"a", "b", "c", "d", "e"} from item 10 to item 15 → {}
131
+
132
+
slice list {"a", "b", "c", "d", "e"} from item 4 to item 3 → {}
133
+
134
+
</code></pre>
109
135
]]></html>
110
136
</documentation>
111
137
</command>
@@ -122,14 +148,24 @@ reduce list {5, 1, 9, 3} using SumNumbers → 18</code></pre>
<p>The <code>transpose list</code> command treats a list of lists as a 2D matrix, rearranging it so that rows become columns and columns become rows.</p>
126
152
127
-
<p>To obtain a list of {name, album, artist} sublists for each track in iTunes:</p>
<p>This command is particularly useful when getting large amounts of data from scriptable applications, as it is much quicker to ask the application to <code>get <var>property</var> of every <var>element</var></code> than to get every element, then iterate over the returned list of references asking for each element’s properties one at a time. For example, to obtain name, album, and artist information for every track in iTunes, then rearrange it into an easier-to-use form:</p>
128
156
129
157
<pre><code>tell application "iTunes"
130
-
set trackInfo to {name, album, artist} of every track
158
+
tell every track
159
+
set allNames to its name
160
+
set allAlbums to its album
161
+
set allArtists to its artist
162
+
end tell
131
163
end tell
132
-
transpose list trackInfo</code></pre>
164
+
set trackInfo to {allNames, allAlbum, allArtists}
165
+
-- trackInfo is a list of form {{name, name, ...}, {album, album, ...}, {artist, artist, ...}}
166
+
167
+
set trackInfo to transpose list trackInfo
168
+
-- trackInfo is now a list of form {{name, album, artist}, {name, album, artist}, ...}</code></pre>
133
169
]]></html>
134
170
</documentation>
135
171
</command>
@@ -146,57 +182,69 @@ transpose list trackInfo</code></pre>
146
182
147
183
148
184
<suitename="Search"code="****">
149
-
150
-
<commandname="find in list"code="Lst:Find"description="return the index(es) of the specified value in a list">
185
+
186
+
<commandname="filter list"code="Lst:Filt"description="check each item in the given list, returning a new list containing only those items that pass the test">
151
187
<direct-parametertype="list"/>
152
-
<parametername="value"code="Valu"type="anything"optional="yes"description="the value to find (default: missing value)"/>
153
-
<parametername="using"code="Usin"type="script"optional="yes"definition="the test to perform on each item; if given, the ‘value’ parameter is ignored"/>
<typetype="integer"list="yes"description="a list of item index(es), or an empty list if no matches are found"/>
157
-
</result>
188
+
<parametername="using"code="Usin"type="script"/>
189
+
<resulttype="list"/>
158
190
<documentation>
159
191
<html><![CDATA[
160
-
<pre><code>find in list {"a", "b", "c"} value "b" → {2}</code></pre>
192
+
<p>The <code>using</code> parameter's script object must implement a handler named <code>filterItem</code> that takes a value as its input and returns <code>true</code> or <code>false</code> indicating whether or not the item should appear in the output list. The following example demonstrates how to filter a list of numbers to obtain a new list containing only the items that are greater than 18:</p>
193
+
194
+
<pre><code>script IsOverEighteen
195
+
to filterItem(aValue)
196
+
return aValue > 18
197
+
end filterItem
198
+
end script
161
199
162
-
<p>The <code>value</code> parameter uses AppleScript’s <code>is</code> operator to determine if a list item matches the specified value. e.g. When processing lists of text, wrap the <code>find in list</code> command in <code>considering</code>/<code>ignoring</code> blocks as necessary.</p>
200
+
filter list {12, 23, 17, 22, 14} using IsOverEighteen → {23, 22}</code></pre>
163
201
164
-
<p>For more complex tests, use the <code>using</code> parameter instead. This takes a script object containing a <code>filterItem</code> handler that takes the item to check as its sole parameter and returns <code>true</code> or <code>false</code> to indicate a match or non-match.</p>
165
202
]]></html>
166
203
</documentation>
167
204
</command>
168
205
169
-
<enumerationname="LFWh"code="LFWh">
170
-
<enumeratorname="first occurrence"code="LFWF"/>
171
-
<enumeratorname="last occurrence"code="LFWL"/>
172
-
<enumeratorname="all occurrences"code="LFWA"/>
173
-
</enumeration>
174
-
175
206
176
-
<commandname="filter list"code="Lst:Filt"description="check each item in the given list, returning a new list containing only those items that pass the test">
207
+
<commandname="find in list"code="Lst:Find"description="return the index(es) of the specified value in a list">
177
208
<direct-parametertype="list"/>
178
-
<parametername="using"code="Usin"type="script"/>
179
-
<resulttype="list"/>
209
+
<parametername="value"code="Valu"type="anything"optional="yes"description="the value to find (default: missing value)"/>
210
+
<parametername="using"code="Usin"type="script"optional="yes"definition="the test to perform on each item; if given, the ‘value’ parameter is ignored"/>
211
+
<parametername="returning"code="Retu"type="LFWh"optional="yes"description="(default: all occurences)"/>
212
+
<result>
213
+
<typetype="integer"list="yes"description="a list of item index(es), or an empty list if no matches are found"/>
214
+
</result>
180
215
<documentation>
181
216
<html><
0 commit comments