seqlua

annotate README @ 55:37c2841c6e8c

Added warning regarding nested/repeated loops to README
author jbe
date Wed Aug 27 00:21:04 2014 +0200 (2014-08-27)
parents 92ce3958aca7
children c3976eacc6ab
rev   line source
jbe@37 1 seqlua: Extension for handling sequential data in Lua
jbe@37 2 =====================================================
jbe@0 3
jbe@55 4 This package is an experimental extension for the Lua 5.2 programming language
jbe@54 5 which:
jbe@0 6
jbe@54 7 * allows ``ipairs(seq)`` to accept either tables or functions (i.e function
jbe@54 8 iterators) as an argument,
jbe@49 9 * adds a new function ``string.concat(separator, seq)`` that concats either
jbe@32 10 table entries or function return values,
jbe@49 11 * provides auxiliary C functions and macros to simplify iterating over both
jbe@38 12 tables and iterator functions with a generic statement.
jbe@0 13
jbe@33 14 Existing ``__ipairs`` or ``__index`` (but not ``__len``) metamethods are
jbe@33 15 respected by both the Lua functions and the C functions and macros. The
jbe@32 16 ``__ipairs`` metamethod takes precedence over ``__index``, while the
jbe@32 17 ``__len`` metamethod is never used.
jbe@32 18
jbe@37 19 Metamethod handling in detail is explained in the last section
jbe@37 20 ("Respected metamethods") at the bottom of this README.
jbe@37 21
jbe@49 22 In Lua, this extension is loaded by ``require "seqlua"``. In order to use the
jbe@49 23 auxiliary C functions and macros, add ``#include <seqlualib.h>`` to your C file
jbe@49 24 and ensure that the functions implemented in ``seqlualib.c`` are statically or
jbe@49 25 dynamically linked with your C Lua library.
jbe@49 26
jbe@37 27
jbe@37 28
jbe@37 29 Motivation
jbe@37 30 ----------
jbe@37 31
jbe@37 32 Sequential data (such as arrays or streams) is often represented in two
jbe@37 33 different ways:
jbe@37 34
jbe@37 35 * as an ordered set of values (usually implemented as an array in other
jbe@37 36 programming languages, or as a sequence in Lua: a table with numeric keys
jbe@37 37 {1..n} associated with a value each),
jbe@37 38 * as some sort of data stream (sometimes implemented as a class of objects
jbe@37 39 providing certain methods, or as an iterator function in Lua: a function that
jbe@37 40 returns the next value with every call, where nil indicates the end of the
jbe@37 41 stream).
jbe@37 42
jbe@37 43 Quite often, when functions work on sequential data, it shouldn't matter in
jbe@37 44 which form the sequential data is being provided to the function. As an
jbe@37 45 example, consider a function that is writing a sequence of strings to a file.
jbe@37 46 Such function could either be fed with an array of strings (a table with
jbe@37 47 numeric keys in Lua) or with a (possibly infinite) stream of data (an iterator
jbe@37 48 function in Lua).
jbe@37 49
jbe@37 50 A function in Lua that accepts a table, might look like as follows:
jbe@37 51
jbe@37 52 function write_lines(lines)
jbe@37 53 for i, line in ipairs(lines) do
jbe@37 54 io.stdout:write(line)
jbe@37 55 io.stdout:write("\n")
jbe@37 56 end
jbe@37 57 end
jbe@37 58
jbe@37 59 In contrast, a function in Lua that accepts an iterator function would have to
jbe@37 60 be implemented differently:
jbe@37 61
jbe@37 62 function write_lines(get_next_line)
jbe@37 63 for line in get_next_line do
jbe@37 64 io.stdout:write(line)
jbe@37 65 io.stdout:write("\n")
jbe@37 66 end
jbe@37 67 end
jbe@37 68
jbe@37 69 If one wanted to create a function that accepts either a sequence in form of a
jbe@37 70 table or an iterator function, then one might need to write:
jbe@37 71
jbe@41 72 do
jbe@41 73 local function write_line(line)
jbe@37 74 io.stdout:write(line)
jbe@37 75 io.stdout:write("\n")
jbe@37 76 end
jbe@41 77 function write_lines(lines)
jbe@41 78 if type(lines) == "function" then
jbe@41 79 for line in lines do
jbe@41 80 write_line(line)
jbe@41 81 end
jbe@41 82 else
jbe@41 83 for i, line in ipairs(lines) do
jbe@41 84 write_line(line)
jbe@41 85 end
jbe@41 86 end
jbe@41 87 end
jbe@37 88 end
jbe@37 89
jbe@41 90 Obviously, this isn't something we want to do in every function that accepts
jbe@37 91 sequential data. Therefore, we usually decide for one of the two first forms
jbe@48 92 and thus disallow the other possible representation of sequential data to be
jbe@48 93 passed to the function.
jbe@37 94
jbe@37 95 This extension, however, modifies Lua's ``ipairs`` statement in such way that
jbe@37 96 it automatically accepts either a table or an iterator function as argument.
jbe@54 97 Thus, the first of the three ``write_lines`` functions above will accept both
jbe@54 98 (table) sequences and (function) iterators.
jbe@37 99
jbe@37 100 In addition to the modification of ``ipairs``, it also provides C functions and
jbe@37 101 macros to iterate over values in the same manner as a generic loop statement
jbe@37 102 with ``ipairs`` would do.
jbe@37 103
jbe@55 104 Note that in case of repeated or nested loops, using function iterators may not
jbe@55 105 be feasible:
jbe@55 106
jbe@55 107 function print_list_twice(seq)
jbe@55 108 for i = 1, 2 do
jbe@55 109 for i, v in ipairs(seq) do
jbe@55 110 print(v)
jbe@55 111 end
jbe@55 112 end
jbe@55 113 end
jbe@55 114 print_list_twice(io.stdin:lines()) -- won't work as expected
jbe@55 115
jbe@55 116 Also note that this extension doesn't aim to supersede Lua's concept of
jbe@55 117 iterator functions. While metamethods (see section "Respected metamethods"
jbe@55 118 below) may be used to customize iteration behavior on values, this extension
jbe@55 119 isn't thought to replace the common practice to use function closures as
jbe@55 120 iterators. Consider the following example:
jbe@37 121
jbe@37 122 local result = sql_query("SELECT * FROM actor ORDER BY birthdate")
jbe@37 123 write_lines(result:get_column_entries("name"))
jbe@37 124
jbe@37 125 The ``get_column_entries`` method can return a simple function closure that
jbe@37 126 returns the next entry in the "name" column (returning ``nil`` to indicate the
jbe@37 127 end). Such a closure can then be passed to another function that iterates
jbe@37 128 through a sequence of values by invoking ``ipairs`` with the general for-loop
jbe@37 129 (as previously shown).
jbe@37 130
jbe@37 131 Where desired, it is also possible to use metamethods to customize iteration
jbe@44 132 behavior:
jbe@44 133
jbe@44 134 function print_rows(rows)
jbe@44 135 for i, row in ipairs(rows) do
jbe@44 136 print_row(row)
jbe@44 137 end
jbe@44 138 end
jbe@44 139 local result = sql_query("SELECT * FROM actor ORDER BY birthday")
jbe@46 140 assert(type(result) == "userdata")
jbe@44 141
jbe@44 142 -- we may rely on the ``__index`` or ``__ipairs`` metamethod to
jbe@44 143 -- iterate through all result rows here:
jbe@44 144 print_rows(result) -- no need to use ":rows()" or a similar syntax
jbe@44 145
jbe@45 146 -- but we can also still pass an individual set of result rows to the
jbe@44 147 -- print_rows function:
jbe@44 148 print_rows{result[1], result[#result]}
jbe@44 149
jbe@44 150 This extension, however, doesn't respect the ``__len`` metamethod due to the
jbe@47 151 following considerations:
jbe@37 152
jbe@39 153 * An efficient implementation where ``for i, v in ipairs(tbl) do ... end`` does
jbe@39 154 neither create a closure nor repeatedly evaluate ``#tbl`` seems to be
jbe@39 155 impossible.
jbe@37 156 * Respecting ``__len`` could be used to implement sparse arrays, but this would
jbe@37 157 require iterating functions to expect ``nil`` as a potential value. This may
jbe@37 158 lead to problems because ``nil`` is usually also used to indicate the absence
jbe@37 159 of a value.
jbe@37 160
jbe@40 161 Though, if such behavior is desired, it can still be implemented through the
jbe@37 162 ``__ipairs`` metamethod.
jbe@37 163
jbe@48 164 Unless manually done by the user in the ``__ipairs`` metamethod, the ``ipairs``
jbe@48 165 function as well as the corresponding C functions and macros provided by this
jbe@48 166 extension never create any closures or other values that need to be garbage
jbe@48 167 collected.
jbe@37 168
jbe@0 169
jbe@0 170
jbe@0 171 Lua part of the library
jbe@0 172 -----------------------
jbe@0 173
jbe@30 174 The modified ``ipairs(seq)`` and the new ``string.concat(sep, seq)`` functions
jbe@30 175 accept either a table or a function as ``seq``. This is demonstrated in the
jbe@30 176 following examples:
jbe@0 177
jbe@0 178 require "seqlua"
jbe@0 179
jbe@0 180 t = {"a", "b", "c"}
jbe@0 181
jbe@54 182 for i, v in ipairs(t) do
jbe@0 183 print(i, v)
jbe@0 184 end
jbe@0 185 -- prints:
jbe@0 186 -- 1 a
jbe@0 187 -- 2 b
jbe@0 188 -- 3 c
jbe@0 189
jbe@25 190 print(string.concat(",", t))
jbe@25 191 -- prints: a,b,c
jbe@25 192
jbe@19 193 function alphabet()
jbe@0 194 local letter = nil
jbe@0 195 return function()
jbe@0 196 if letter == nil then
jbe@19 197 letter = "a"
jbe@19 198 elseif letter == "z" then
jbe@0 199 return nil
jbe@0 200 else
jbe@0 201 letter = string.char(string.byte(letter) + 1)
jbe@0 202 end
jbe@0 203 return letter
jbe@0 204 end
jbe@0 205 end
jbe@0 206
jbe@54 207 for i, v in ipairs(alphabet()) do
jbe@0 208 print(i, v)
jbe@0 209 end
jbe@0 210 -- prints:
jbe@0 211 -- 1 a
jbe@0 212 -- 2 b
jbe@0 213 -- 3 c
jbe@0 214 -- ...
jbe@0 215 -- 25 y
jbe@0 216 -- 26 z
jbe@0 217
jbe@25 218 print(string.concat(",", alphabet()))
jbe@25 219 -- prints: a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z
jbe@25 220
jbe@26 221 function filter(f)
jbe@26 222 return function(seq)
jbe@26 223 return coroutine.wrap(function()
jbe@54 224 for i, v in ipairs(seq) do f(v) end
jbe@26 225 end)
jbe@26 226 end
jbe@0 227 end
jbe@19 228
jbe@29 229 alpha_beta_x = filter(function(v)
jbe@28 230 if v == "a" then
jbe@28 231 coroutine.yield("alpha")
jbe@28 232 elseif v == "b" then
jbe@28 233 coroutine.yield("beta")
jbe@28 234 elseif type(v) == "number" then
jbe@23 235 for i = 1, v do
jbe@28 236 coroutine.yield("X")
jbe@23 237 end
jbe@0 238 end
jbe@26 239 end)
jbe@0 240
jbe@29 241 print((","):concat(alpha_beta_x{"a", 3, "b", "c", "d"}))
jbe@28 242 -- prints: alpha,X,X,X,beta
jbe@25 243
jbe@29 244 print((","):concat(alpha_beta_x(alphabet())))
jbe@28 245 -- prints: alpha,beta
jbe@27 246
jbe@0 247
jbe@37 248
jbe@0 249 C part of the library
jbe@0 250 ---------------------
jbe@0 251
jbe@0 252 In ``seqlualib.h``, the following macro is defined:
jbe@0 253
jbe@54 254 #define seqlua_iterloop(L, iter, idx) \
jbe@0 255 for ( \
jbe@54 256 seqlua_iterinit((L), (iter), (idx)); \
jbe@0 257 seqlua_iternext(iter); \
jbe@25 258 )
jbe@25 259
jbe@25 260 and
jbe@25 261
jbe@25 262 #define seqlua_iterloopauto(L, iter, idx) \
jbe@25 263 for ( \
jbe@54 264 seqlua_iterinit((L), (iter), (idx)); \
jbe@25 265 seqlua_iternext(iter); \
jbe@0 266 lua_pop((L), 1) \
jbe@0 267 )
jbe@0 268
jbe@23 269 This macro allows iteration over either tables or iterator functions as the
jbe@23 270 following example function demonstrates:
jbe@0 271
jbe@0 272 int printcsv(lua_State *L) {
jbe@0 273 seqlua_Iterator iter;
jbe@54 274 seqlua_iterloop(L, &iter, 1) {
jbe@0 275 if (seqlua_itercount(&iter) > 1) fputs(",", stdout);
jbe@0 276 fputs(luaL_tolstring(L, -1, NULL), stdout);
jbe@25 277 // two values need to be popped (the value pushed by
jbe@25 278 // seqlua_iternext and the value pushed by luaL_tolstring)
jbe@25 279 lua_pop(L, 2);
jbe@0 280 }
jbe@0 281 fputs("\n", stdout);
jbe@0 282 return 0;
jbe@0 283 }
jbe@0 284
jbe@11 285 printcsv{"a", "b", "c"}
jbe@11 286 -- prints: a,b,c
jbe@11 287
jbe@11 288 printcsv(assert(io.open("testfile")):lines())
jbe@11 289 -- prints: line1,line2,... of "testfile"
jbe@0 290
jbe@31 291 NOTE: During iteration using ``seqlua_iterloop``, ``seqlua_iterloopauto``, or
jbe@31 292 ``seqlua_iterinit``, three extra elements are stored on the stack (additionally
jbe@31 293 to the value). These extra elements are removed automatically when the loop ends
jbe@31 294 (i.e. when ``seqlua_iternext`` returns zero). The value pushed onto the stack
jbe@31 295 for every iteration step has to be removed manually from the stack, unless
jbe@31 296 ``seqlua_iterloopauto`` is used.
jbe@0 297
jbe@31 298
jbe@37 299
jbe@35 300 Respected metamethods
jbe@35 301 ---------------------
jbe@35 302
jbe@35 303 Regarding the behavior of the Lua functions and the C functions and macros
jbe@35 304 provided by this extension, an existing ``__index`` metamethod will be
jbe@35 305 respected automatically. An existing ``__ipairs`` metamethod, however, takes
jbe@35 306 precedence.
jbe@35 307
jbe@35 308 If the ``__ipairs`` field of a value's metatable is set, then it must always
jbe@35 309 refer to a function. When starting iteration over a value with such a
jbe@35 310 metamethod being set, then this function is called with ``self`` (i.e. the
jbe@35 311 value itself) passed as first argument. The return values of the ``__ipairs``
jbe@35 312 metamethod may take one of the following 4 forms:
jbe@35 313
jbe@35 314 * ``return function_or_callable, static_argument, startindex`` causes the three
jbe@35 315 arguments to be returned by ``ipairs`` without further modification. Using
jbe@35 316 the C macros and functions for iteration, the behavior is according to the
jbe@35 317 generic loop statement in Lua:
jbe@35 318 ``for i, v in function_or_callable, static_argument, startindex do ... end``
jbe@35 319 * ``return "raw", table`` will result in iteration over the table ``table``
jbe@35 320 using ``lua_rawgeti``
jbe@35 321 * ``return "index", table_or_userdata`` will result in iteration over the table
jbe@35 322 or userdata while respecting any ``__index`` metamethod of the table or
jbe@35 323 userdata value
jbe@35 324 * ``return "call", function_or_callable`` will use the callable value as
jbe@35 325 (function) iterator where the function is expected to return a single value
jbe@35 326 without any index (the index is inserted automatically when using the
jbe@35 327 ``ipairs`` function for iteration)
jbe@35 328
jbe@35 329 These possiblities are demonstrated by the following example code:
jbe@35 330
jbe@35 331 require "seqlua"
jbe@35 332
jbe@35 333 do
jbe@35 334 local function ipairsaux(t, i)
jbe@35 335 i = i + 1
jbe@35 336 if i <= 3 then
jbe@35 337 return i, t[i]
jbe@35 338 end
jbe@35 339 end
jbe@35 340 custom = setmetatable(
jbe@35 341 {"one", "two", "three", "four", "five"},
jbe@35 342 {
jbe@35 343 __ipairs = function(self)
jbe@35 344 return ipairsaux, self, 0
jbe@35 345 end
jbe@35 346 }
jbe@35 347 )
jbe@35 348 end
jbe@35 349 print(string.concat(",", custom))
jbe@36 350 -- prints: one,two,three
jbe@35 351 -- (note that "four" and "five" are not printed)
jbe@35 352
jbe@35 353 tbl = {"alpha", "beta"}
jbe@35 354
jbe@35 355 proxy1 = setmetatable({}, {__index = tbl})
jbe@35 356 for i, v in ipairs(proxy1) do print(i, v) end
jbe@35 357 -- prints:
jbe@35 358 -- 1 alpha
jbe@35 359 -- 2 beta
jbe@35 360
jbe@35 361 proxy2 = setmetatable({}, {
jbe@35 362 __ipairs = function(self)
jbe@35 363 return "index", proxy1
jbe@35 364 end
jbe@35 365 })
jbe@35 366 for i, v in ipairs(proxy2) do print(i, v) end
jbe@35 367 -- prints:
jbe@35 368 -- 1 alpha
jbe@35 369 -- 2 beta
jbe@35 370 print(proxy2[1])
jbe@35 371 -- prints: nil
jbe@35 372
jbe@35 373 cursor = setmetatable({
jbe@35 374 "alice", "bob", "charlie", pos=1
jbe@35 375 }, {
jbe@35 376 __call = function(self)
jbe@35 377 local value = self[self.pos]
jbe@35 378 if value == nil then
jbe@35 379 self.pos = 1
jbe@35 380 else
jbe@35 381 self.pos = self.pos + 1
jbe@35 382 end
jbe@35 383 return value
jbe@35 384 end,
jbe@35 385 __ipairs = function(self)
jbe@35 386 return "call", self
jbe@35 387 end
jbe@35 388 })
jbe@35 389 for i, v in ipairs(cursor) do print(i, v) end
jbe@35 390 -- prints:
jbe@35 391 -- 1 alice
jbe@35 392 -- 2 bob
jbe@35 393 -- 3 charlie
jbe@35 394 print(cursor())
jbe@35 395 -- prints: alice
jbe@35 396 for i, v in ipairs(cursor) do print(i, v) end
jbe@35 397 -- prints:
jbe@35 398 -- 1 bob
jbe@35 399 -- 2 charlie
jbe@35 400 -- (note that "alice" has been returned earlier)
jbe@35 401
jbe@35 402 coefficients = setmetatable({1.25, 3.14, 17.5}, {
jbe@35 403 __index = function(self) return 1 end,
jbe@35 404 __ipairs = function(self) return "raw", self end
jbe@35 405 })
jbe@35 406 for i, v in ipairs(coefficients) do print(i, v) end
jbe@35 407 -- prints:
jbe@35 408 -- 1 1.25
jbe@35 409 -- 2 3.14
jbe@35 410 -- 3 17.5
jbe@35 411 -- (note that iteration terminates even if coefficients[4] == 1)
jbe@35 412 print(coefficients[4])
jbe@35 413 -- prints: 1
jbe@35 414
jbe@35 415

Impressum / About Us