seqlua

annotate README @ 11:814d42156b14

find changesets by author, revision, files, or words in the commit message
Extended README to contain example for file:lines() iterator
author jbe
date Wed Aug 20 04:54:49 2014 +0200 (2014-08-20)
parents bb2cf91174ac
children 91b0d0d4c4dd
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@0 15 deprecated since Lua 5.3.0-alpha). It respects, however, any ``__call``
jbe@0 16 metamethods (this may cause unexpected behavior when passing callable tables
jbe@0 17 to ``ipairs``).
jbe@0 18
jbe@0 19
jbe@0 20
jbe@0 21 Lua part of the library
jbe@0 22 -----------------------
jbe@0 23
jbe@0 24 The new ``ipairs(...)`` function works as follows:
jbe@0 25
jbe@0 26 require "seqlua"
jbe@0 27
jbe@0 28 t = {"a", "b", "c"}
jbe@0 29
jbe@0 30 for i, v in ipairs(t) do
jbe@0 31 print(i, v)
jbe@0 32 end
jbe@0 33 -- prints:
jbe@0 34 -- 1 a
jbe@0 35 -- 2 b
jbe@0 36 -- 3 c
jbe@0 37
jbe@8 38 function alphabet(from, to)
jbe@0 39 local letter = nil
jbe@0 40 return function()
jbe@0 41 if letter == nil then
jbe@8 42 letter = from
jbe@8 43 elseif letter == to then
jbe@0 44 return nil
jbe@0 45 else
jbe@0 46 letter = string.char(string.byte(letter) + 1)
jbe@0 47 end
jbe@0 48 return letter
jbe@0 49 end
jbe@0 50 end
jbe@0 51
jbe@8 52 f = alphabet("a", "z")
jbe@0 53
jbe@0 54 for i, v in ipairs(f) do
jbe@0 55 print(i, v)
jbe@0 56 end
jbe@0 57 -- prints:
jbe@0 58 -- 1 a
jbe@0 59 -- 2 b
jbe@0 60 -- 3 c
jbe@0 61 -- ...
jbe@0 62 -- 25 y
jbe@0 63 -- 26 z
jbe@0 64
jbe@8 65 c = setmetatable(
jbe@8 66 { iter = alphabet("a", "f") },
jbe@8 67 { __call = function(t) return t.iter() end }
jbe@8 68 )
jbe@8 69
jbe@8 70 for i, v in ipairs(c) do
jbe@8 71 print(i, v)
jbe@8 72 end
jbe@8 73 -- prints:
jbe@8 74 -- 1 a
jbe@8 75 -- 2 b
jbe@8 76 -- 3 c
jbe@10 77 -- 4 d
jbe@10 78 -- 5 e
jbe@10 79 -- 6 f
jbe@8 80
jbe@0 81 set = {apple = true, banana = true}
jbe@0 82 for i, k, v in ipairs(pairs(set)) do
jbe@0 83 print(i, k, v)
jbe@0 84 end
jbe@0 85 -- prints:
jbe@0 86 -- 1 banana true
jbe@0 87 -- 2 apple true
jbe@0 88 -- (order of "apple" and "banana" may vary)
jbe@0 89
jbe@0 90 The function ``iterator(...)`` may be used to convert any table, any function,
jbe@0 91 or any iterator triplet into a single function (possibly creating a closure):
jbe@0 92
jbe@2 93 require "seqlua"
jbe@2 94
jbe@0 95 function filter_strings(...)
jbe@0 96 nextvalue = iterator(...)
jbe@0 97 return function()
jbe@0 98 local value
jbe@0 99 repeat
jbe@0 100 value = nextvalue()
jbe@0 101 until value == nil or type(value) == "string"
jbe@0 102 return value
jbe@0 103 end
jbe@0 104 end
jbe@0 105
jbe@0 106 for i, v in ipairs(filter_strings{"Hello", true, "World"}) do
jbe@0 107 print(i, v)
jbe@0 108 end
jbe@0 109 -- prints:
jbe@0 110 -- 1 Hello
jbe@0 111 -- 2 World
jbe@0 112
jbe@0 113 tbl = {apple = true, banana = true, [1] = "array entry"}
jbe@0 114 for v in filter_strings(pairs(tbl)) do
jbe@0 115 print(v)
jbe@0 116 end
jbe@0 117 -- prints:
jbe@0 118 -- banana
jbe@0 119 -- apple
jbe@0 120 -- (order may vary)
jbe@0 121
jbe@0 122
jbe@0 123
jbe@0 124 C part of the library
jbe@0 125 ---------------------
jbe@0 126
jbe@0 127 In ``seqlualib.h``, the following macro is defined:
jbe@0 128
jbe@0 129 #define seqlua_iterloop(L, iter, idx) \
jbe@0 130 for ( \
jbe@0 131 seqlua_iterinit((L), (iter), (idx)); \
jbe@0 132 seqlua_iternext(iter); \
jbe@0 133 lua_pop((L), 1) \
jbe@0 134 )
jbe@0 135
jbe@0 136 This macro allows iteration over either tables or iterator functions (but not
jbe@0 137 iterator triplets) as the following example function demonstrates:
jbe@0 138
jbe@0 139 int printcsv(lua_State *L) {
jbe@0 140 seqlua_Iterator iter;
jbe@0 141 seqlua_iterloop(L, &iter, 1) {
jbe@0 142 if (seqlua_itercount(&iter) > 1) fputs(",", stdout);
jbe@0 143 fputs(luaL_tolstring(L, -1, NULL), stdout);
jbe@1 144 lua_pop(L, 1); // pops value that luaL_tolstring pushed onto stack
jbe@0 145 }
jbe@0 146 fputs("\n", stdout);
jbe@0 147 return 0;
jbe@0 148 }
jbe@0 149
jbe@11 150 printcsv{"a", "b", "c"}
jbe@11 151 -- prints: a,b,c
jbe@11 152
jbe@11 153 printcsv(assert(io.open("testfile")):lines())
jbe@11 154 -- prints: line1,line2,... of "testfile"
jbe@0 155
jbe@7 156 NOTE: ``seqlua_iterinit`` will store one extra element on the stack during
jbe@7 157 iteration. When ``seqlua_iternext`` returns 0, this extra element is popped
jbe@7 158 from the stack automatically.
jbe@3 159
jbe@0 160 Additionally, ``seqlualib`` includes a function ``seqlua_iterclosure(L, idx)``,
jbe@0 161 which converts a table at a given stack index into a function closure (stored
jbe@0 162 on the same stack index) that iterates over the elements of the table. If the
jbe@0 163 value at the given stack index is already a function, it leaves the value
jbe@4 164 unchanged. If the value is convertible to a function using ``__call,`` then the
jbe@7 165 value is replaced by a closure calling the ``__call`` metamethod.
jbe@0 166
jbe@0 167

Impressum / About Us