| rev |
line source |
|
jbe@0
|
1 seqlua: Extended sequences and iterators in Lua
|
|
jbe@0
|
2 ===============================================
|
|
jbe@0
|
3
|
|
jbe@0
|
4 This is an experimental package to extend Lua in the following manner:
|
|
jbe@0
|
5
|
|
jbe@0
|
6 * allow ipairs(...) to accept tables as well as functions or iterator triplets,
|
|
jbe@0
|
7 * provide a function iterator(...) that returns single functions unmodified,
|
|
jbe@0
|
8 but converts
|
|
jbe@0
|
9 * iterator triplets into closures, and
|
|
jbe@0
|
10 * tables into a function closure that iterates over the elements,
|
|
jbe@0
|
11 * provide the auxiliary C functions and macros to simplify iterating over both
|
|
jbe@0
|
12 tables and iterator functions with the same statement.
|
|
jbe@0
|
13
|
|
jbe@0
|
14 This library completely ignores the ``__ipairs`` metamethod (as it is
|
|
jbe@18
|
15 deprecated since Lua 5.3.0-alpha). It respects, however, any ``__index`` and
|
|
jbe@18
|
16 ``__call`` metamethods (this may cause unexpected behavior when passing
|
|
jbe@18
|
17 callable tables to ``ipairs``). The ``__call`` metamethod takes precedence over
|
|
jbe@18
|
18 an existing ``__index`` metamethod.
|
|
jbe@0
|
19
|
|
jbe@0
|
20
|
|
jbe@0
|
21
|
|
jbe@0
|
22 Lua part of the library
|
|
jbe@0
|
23 -----------------------
|
|
jbe@0
|
24
|
|
jbe@0
|
25 The new ``ipairs(...)`` function works as follows:
|
|
jbe@0
|
26
|
|
jbe@0
|
27 require "seqlua"
|
|
jbe@0
|
28
|
|
jbe@0
|
29 t = {"a", "b", "c"}
|
|
jbe@0
|
30
|
|
jbe@0
|
31 for i, v in ipairs(t) do
|
|
jbe@0
|
32 print(i, v)
|
|
jbe@0
|
33 end
|
|
jbe@0
|
34 -- prints:
|
|
jbe@0
|
35 -- 1 a
|
|
jbe@0
|
36 -- 2 b
|
|
jbe@0
|
37 -- 3 c
|
|
jbe@0
|
38
|
|
jbe@19
|
39 function alphabet()
|
|
jbe@0
|
40 local letter = nil
|
|
jbe@0
|
41 return function()
|
|
jbe@0
|
42 if letter == nil then
|
|
jbe@19
|
43 letter = "a"
|
|
jbe@19
|
44 elseif letter == "z" then
|
|
jbe@0
|
45 return nil
|
|
jbe@0
|
46 else
|
|
jbe@0
|
47 letter = string.char(string.byte(letter) + 1)
|
|
jbe@0
|
48 end
|
|
jbe@0
|
49 return letter
|
|
jbe@0
|
50 end
|
|
jbe@0
|
51 end
|
|
jbe@0
|
52
|
|
jbe@8
|
53 f = alphabet("a", "z")
|
|
jbe@0
|
54
|
|
jbe@0
|
55 for i, v in ipairs(f) do
|
|
jbe@0
|
56 print(i, v)
|
|
jbe@0
|
57 end
|
|
jbe@0
|
58 -- prints:
|
|
jbe@0
|
59 -- 1 a
|
|
jbe@0
|
60 -- 2 b
|
|
jbe@0
|
61 -- 3 c
|
|
jbe@0
|
62 -- ...
|
|
jbe@0
|
63 -- 25 y
|
|
jbe@0
|
64 -- 26 z
|
|
jbe@0
|
65
|
|
jbe@0
|
66 set = {apple = true, banana = true}
|
|
jbe@0
|
67 for i, k, v in ipairs(pairs(set)) do
|
|
jbe@0
|
68 print(i, k, v)
|
|
jbe@0
|
69 end
|
|
jbe@0
|
70 -- prints:
|
|
jbe@0
|
71 -- 1 banana true
|
|
jbe@0
|
72 -- 2 apple true
|
|
jbe@0
|
73 -- (order of "apple" and "banana" may vary)
|
|
jbe@0
|
74
|
|
jbe@19
|
75 More examples for invoking the ``ipairs(...)`` function can be found in the
|
|
jbe@19
|
76 file ``seqlua_ipairs_example.lua``.
|
|
jbe@19
|
77
|
|
jbe@0
|
78 The function ``iterator(...)`` may be used to convert any table, any function,
|
|
jbe@0
|
79 or any iterator triplet into a single function (possibly creating a closure):
|
|
jbe@0
|
80
|
|
jbe@2
|
81 require "seqlua"
|
|
jbe@2
|
82
|
|
jbe@0
|
83 function filter_strings(...)
|
|
jbe@0
|
84 nextvalue = iterator(...)
|
|
jbe@0
|
85 return function()
|
|
jbe@0
|
86 local value
|
|
jbe@0
|
87 repeat
|
|
jbe@0
|
88 value = nextvalue()
|
|
jbe@0
|
89 until value == nil or type(value) == "string"
|
|
jbe@0
|
90 return value
|
|
jbe@0
|
91 end
|
|
jbe@0
|
92 end
|
|
jbe@0
|
93
|
|
jbe@0
|
94 for i, v in ipairs(filter_strings{"Hello", true, "World"}) do
|
|
jbe@0
|
95 print(i, v)
|
|
jbe@0
|
96 end
|
|
jbe@0
|
97 -- prints:
|
|
jbe@0
|
98 -- 1 Hello
|
|
jbe@0
|
99 -- 2 World
|
|
jbe@0
|
100
|
|
jbe@0
|
101 tbl = {apple = true, banana = true, [1] = "array entry"}
|
|
jbe@0
|
102 for v in filter_strings(pairs(tbl)) do
|
|
jbe@0
|
103 print(v)
|
|
jbe@0
|
104 end
|
|
jbe@0
|
105 -- prints:
|
|
jbe@0
|
106 -- banana
|
|
jbe@0
|
107 -- apple
|
|
jbe@0
|
108 -- (order may vary)
|
|
jbe@0
|
109
|
|
jbe@0
|
110
|
|
jbe@0
|
111
|
|
jbe@0
|
112 C part of the library
|
|
jbe@0
|
113 ---------------------
|
|
jbe@0
|
114
|
|
jbe@0
|
115 In ``seqlualib.h``, the following macro is defined:
|
|
jbe@0
|
116
|
|
jbe@0
|
117 #define seqlua_iterloop(L, iter, idx) \
|
|
jbe@0
|
118 for ( \
|
|
jbe@0
|
119 seqlua_iterinit((L), (iter), (idx)); \
|
|
jbe@0
|
120 seqlua_iternext(iter); \
|
|
jbe@0
|
121 lua_pop((L), 1) \
|
|
jbe@0
|
122 )
|
|
jbe@0
|
123
|
|
jbe@0
|
124 This macro allows iteration over either tables or iterator functions (but not
|
|
jbe@0
|
125 iterator triplets) as the following example function demonstrates:
|
|
jbe@0
|
126
|
|
jbe@0
|
127 int printcsv(lua_State *L) {
|
|
jbe@0
|
128 seqlua_Iterator iter;
|
|
jbe@0
|
129 seqlua_iterloop(L, &iter, 1) {
|
|
jbe@0
|
130 if (seqlua_itercount(&iter) > 1) fputs(",", stdout);
|
|
jbe@0
|
131 fputs(luaL_tolstring(L, -1, NULL), stdout);
|
|
jbe@1
|
132 lua_pop(L, 1); // pops value that luaL_tolstring pushed onto stack
|
|
jbe@0
|
133 }
|
|
jbe@0
|
134 fputs("\n", stdout);
|
|
jbe@0
|
135 return 0;
|
|
jbe@0
|
136 }
|
|
jbe@0
|
137
|
|
jbe@11
|
138 printcsv{"a", "b", "c"}
|
|
jbe@11
|
139 -- prints: a,b,c
|
|
jbe@11
|
140
|
|
jbe@11
|
141 printcsv(assert(io.open("testfile")):lines())
|
|
jbe@11
|
142 -- prints: line1,line2,... of "testfile"
|
|
jbe@0
|
143
|
|
jbe@0
|
144 Additionally, ``seqlualib`` includes a function ``seqlua_iterclosure(L, idx)``,
|
|
jbe@0
|
145 which converts a table at a given stack index into a function closure (stored
|
|
jbe@0
|
146 on the same stack index) that iterates over the elements of the table. If the
|
|
jbe@15
|
147 value at the given stack index is already a function (or if it is callable
|
|
jbe@15
|
148 through a ``__call`` metamethod), then ``seqlua_iterclosure(L, idx)`` leaves
|
|
jbe@15
|
149 the value at ``idx`` unchanged.
|
|
jbe@0
|
150
|
|
jbe@0
|
151
|