Skip to content

Commit 89c3c2c

Browse files
peter-bpeter-b
committed
scriptitems: Add a new extension module for manipulating LCS items
This patch adds a new "scriptitems" module extension. It provides utility functions for working with LiveCode Script item lists from LCB, converting them to-and-from LCB `List` values.
1 parent d8ac675 commit 89c3c2c

File tree

4 files changed

+273
-0
lines changed

4 files changed

+273
-0
lines changed

‎extensions/extensions.gyp‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
'sources':
2020
[
2121
'modules/widget-utils/widget-utils.lcb',
22+
'modules/scriptitems/scriptitems.lcb',
2223

2324
'libraries/canvas/canvas.lcb',
2425
'libraries/iconsvg/iconsvg.lcb',

‎extensions/modules/scriptitems/scriptitems.lcb‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
/* -*-LCB-*-
2+
Copyright (C) 2016 LiveCode Ltd.
3+
4+
This file is part of LiveCode.
5+
6+
LiveCode is free software; you can redistribute it and/or modify it under
7+
the terms of the GNU General Public License v3 as published by the Free
8+
Software Foundation.
9+
10+
LiveCode is distributed in the hope that it will be useful, but WITHOUT ANY
11+
WARRANTY; without even the implied warranty of MERCHANTABILITY or
12+
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13+
for more details.
14+
15+
You should have received a copy of the GNU General Public License
16+
along with LiveCode. If not see <http://www.gnu.org/licenses/>.
17+
*/
18+
19+
/**
20+
Utility functions for LiveCode Script-compatible item lists.
21+
22+
Many LiveCode Builder widget and library extensions expose APIs to
23+
LiveCode Script that use item lists. This library provides a set of
24+
functions for converting `List` values to-and-from comma-delimited
25+
item strings.
26+
*/
27+
28+
module com.livecode.library.scriptitems
29+
30+
metadata version is "1.0.0"
31+
metadata author is "LiveCode"
32+
metadata title is "LiveCode Script item list handling"
33+
34+
/**
35+
Summary: Parse a comma-delimited "item" string as a list of strings
36+
37+
Parameters:
38+
pStringValue: A string containing comma-delimited "items"
39+
pListLength: The number of elements the parsed list should contain
40+
pDefaultValue: Value to be used for extra elements
41+
42+
Returns: The parsed items as a list of strings
43+
44+
Description:
45+
Helper function for converting a LiveCode Script "item" list into list
46+
of strings, obeying the LiveCode Script rules for items.
47+
48+
If <pListLength> is provided, then the returned list will always
49+
contain that number of elements: extra elements will be discarded, and
50+
missing elements will be set to <pDefaultValue>.
51+
52+
Related: parseItemsAsNumberList (handler), formatStringListAsItems (handler)
53+
*/
54+
public handler parseItemsAsStringList(in pStringValue as String, \
55+
in pListLength as optional Number, \
56+
in pDefaultValue as optional String) returns List /* of String */
57+
58+
variable tItems as List
59+
split pStringValue by "," into tItems
60+
61+
if pListLength is not nothing then
62+
repeat while the number of elements in tItems < pListLength
63+
push pDefaultValue onto tItems
64+
end repeat
65+
if the number of elements in tItems > pListLength then
66+
delete element (pListLength + 1) to -1 of tItems
67+
end if
68+
end if
69+
70+
return tItems
71+
end handler
72+
73+
/**
74+
Summary: Parse a comma-delimited "item" string as a list of numbers
75+
76+
Parameters:
77+
pStringValue: A string containing comma-delimited "items"
78+
pListLength: The number of elements the parsed list should contain
79+
pDefaultValue: Value to be used for extra elements
80+
81+
Returns: The parsed items as a list of strings
82+
83+
Description:
84+
Helper function for converting a LiveCode Script "item" list into a
85+
list of numbers, obeying the LiveCode Script rules for items.
86+
87+
If <pListLength> is provided, then the returned list will always
88+
contain that number of elements: extra elements will be discarded, and
89+
missing elements will be set to <pDefaultValue>.
90+
91+
Related: parseItemsAsStringList (handler), formatNumberListAsItems (handler)
92+
*/
93+
public handler parseItemsAsNumberList(in pStringValue as String, \
94+
in pListLength as optional Number, \
95+
in pDefaultValue as optional Number) returns List /* of Number */
96+
variable tItems as List
97+
put parseItemsAsStringList(pStringValue, pListLength, nothing) into tItems
98+
99+
variable tNumbers as List
100+
variable tItem as optional String
101+
repeat for each element tItem in tItems
102+
variable tValue as Number
103+
if tItem is nothing then
104+
put pDefaultValue into tValue
105+
else
106+
put tItem parsed as number into tValue
107+
end if
108+
push tValue onto tNumbers
109+
end repeat
110+
111+
return tNumbers
112+
end handler
113+
114+
/**
115+
Summary: Format a list of strings as a comma-delimited "item" string
116+
117+
Parameters:
118+
pList: A list of strings
119+
120+
Returns: A comma-delimited LiveCode Script-compatible "item" string
121+
122+
Description:
123+
Helper function for converting a list of strings into a LiveCode
124+
Script "item" list, obeying the LiveCode Script rules for items.
125+
126+
Related: parseItemsAsStringList (handler), formatNumberListAsItems (handler)
127+
*/
128+
public handler formatStringListAsItems(in pList as List) returns String
129+
if pList is empty then
130+
return ""
131+
end if
132+
133+
variable tResult as String
134+
combine pList with "," into tResult
135+
136+
-- If a LiveCode Script string ends with a delimiter, it does _not_
137+
-- mean that the last item in the string is empty. To achieve
138+
-- that, it's necessary to add an extra delimiter.
139+
if tResult is empty or tResult ends with "," then
140+
put "," after tResult
141+
end if
142+
143+
return tResult
144+
end handler
145+
146+
/**
147+
Summary: Format a list of numbers as a comma-delimited "item" string
148+
149+
Parameters:
150+
pList: A list of numbers
151+
152+
Returns: A comma-delimited LiveCode Script-compatible "item" string
153+
154+
Description:
155+
Helper function for converting a list of numbers into a LiveCode
156+
Script "item" list, obeying the LiveCode Script rules for items.
157+
158+
Related: formatStringListAsItems (handler), parseItemsAsNumberList (handler)
159+
*/
160+
public handler formatNumberListAsItems(in pList as List) returns String
161+
variable tItems as List
162+
variable tValue as Number
163+
repeat for each element tValue in pList
164+
push tValue formatted as string onto tItems
165+
end repeat
166+
return formatStringListAsItems(tItems)
167+
end handler
168+
169+
end module

‎extensions/modules/scriptitems/tests/numberitems.lcb‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
module com.livecode.library.scriptitems.test.numberitems
2+
use com.livecode.library.scriptitems
3+
4+
handler expectList(in pString as String, in pLength as optional Number, \
5+
in pDefault as optional Number, in pValue as List) returns Boolean
6+
variable tList
7+
put parseItemsAsNumberList(pString, pLength, pDefault) into tList
8+
test diagnostic tList
9+
return tList is pValue
10+
end handler
11+
12+
public handler testParseItemsAsNumberList()
13+
test "basic, no trailing" when \
14+
expectList("-1,1.5", nothing, nothing, [-1, 1.5])
15+
test "basic, trailing" when \
16+
expectList("-1,1.5,", nothing, nothing, [-1, 1.5])
17+
18+
test "basic, empty" when \
19+
expectList("", nothing, nothing, [])
20+
21+
test "too short" when \
22+
parseItemsAsNumberList("-1,1.5", 3, 8) is [-1, 1.5, 8]
23+
24+
test "too long" when \
25+
parseItemsAsNumberList("-1,1.5", 1, 8) is [(-1)]
26+
end handler
27+
28+
handler expectString(in pList, in pValue)
29+
variable tString
30+
put formatNumberListAsItems(pList) into tString
31+
test diagnostic tString
32+
return tString is pValue
33+
end handler
34+
35+
public handler testFormatNumberListAsItems()
36+
test "basic" when \
37+
expectString([1, 2.3], "1,2.3")
38+
39+
test "basic, empty" when \
40+
expectString([], "")
41+
42+
test "basic, large int" when \
43+
expectString([400000000], "400000000")
44+
45+
test "basic, large real" when \
46+
expectString([400000000.000005], "4e+08")
47+
end handler
48+
49+
end module

‎extensions/modules/scriptitems/tests/stringitems.lcb‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
module com.livecode.library.scriptitems.test.stringitems
2+
use com.livecode.library.scriptitems
3+
4+
handler expectList(in pString, in pLength, in pDefault, in pValue)
5+
variable tList
6+
put parseItemsAsStringList(pString, pLength, pDefault) into tList
7+
test diagnostic tList
8+
return tList is pValue
9+
end handler
10+
11+
public handler testParseItemsAsStringList()
12+
test "basic, no trailing" when \
13+
expectList("aaa,bbb", nothing, nothing, ["aaa", "bbb"])
14+
test "basic, trailing" when \
15+
expectList("aaa,bbb,", nothing, nothing, ["aaa", "bbb"])
16+
17+
test "basic, empty" when \
18+
expectList("", nothing, nothing, [])
19+
test "basic, empty item" when \
20+
expectList(",", nothing, nothing, [""])
21+
22+
test "too short, no default" when \
23+
expectList("aaa,bbb", 3, nothing, ["aaa", "bbb", nothing])
24+
test "too short, default" when \
25+
expectList("aaa,bbb", 3, "ccc", ["aaa", "bbb", "ccc"])
26+
27+
test "too long" when \
28+
expectList("aaa,bbb", 1, nothing, ["aaa"])
29+
30+
test "trailing empty" when \
31+
expectList("aaa,bbb,,", nothing, nothing, ["aaa", "bbb", ""])
32+
end handler
33+
34+
handler expectString(in pList, in pValue)
35+
variable tString
36+
put formatStringListAsItems(pList) into tString
37+
test diagnostic tString
38+
return tString is pValue
39+
end handler
40+
41+
public handler testFormatStringListAsItems()
42+
test "basic" when \
43+
expectString(["aaa", "bbb"], "aaa,bbb")
44+
45+
test "basic, empty" when \
46+
expectString([], "")
47+
test "basic, empty item" when \
48+
expectString([""], ",")
49+
50+
test "trailing empty" when \
51+
expectString(["aaa", "bbb", ""], "aaa,bbb,,")
52+
end handler
53+
54+
end module

0 commit comments

Comments
 (0)