1.1 --- a/README	Thu Aug 21 20:20:20 2014 +0200
     1.2 +++ b/README	Thu Aug 21 21:32:01 2014 +0200
     1.3 @@ -3,10 +3,18 @@
     1.4  
     1.5  This is an experimental package to extend Lua in the following manner:
     1.6  
     1.7 -* allow ipairs(...) to accept tables as well as functions
     1.8 +* allow ``ipairs(seq)`` to accept tables as well as functions,
     1.9 +* add a new function ``string.concat(separator, seq)`` to concat either table
    1.10 +  entries or function return values,
    1.11  * provide auxiliary C functions and macros to simplify iterating over both
    1.12    tables and iterator functions with the same statement.
    1.13  
    1.14 +In other words:
    1.15 +When calling ``ipairs(seq)`` or ``string.concat(separator, seq)``,
    1.16 +then ``seq`` may either be a (table) sequence or a (function) iterator.
    1.17 +Auxiliary C functions and macros are provided to simplify extending your own
    1.18 +C functions in the same manner.
    1.19 +
    1.20  This library completely ignores the ``__ipairs`` metamethod (as it is
    1.21  deprecated since Lua 5.3.0-alpha). It respects, however, any ``__index`` and
    1.22  ``__call`` metamethods (this may cause unexpected behavior when passing
    1.23 @@ -18,7 +26,8 @@
    1.24  Lua part of the library
    1.25  -----------------------
    1.26  
    1.27 -The new ``ipairs(...)`` function works as follows:
    1.28 +The modified ``ipairs(seq)`` function and the new ``string.concat`` function
    1.29 +work as demonstrated in the following examples:
    1.30  
    1.31      require "seqlua"
    1.32  
    1.33 @@ -32,6 +41,9 @@
    1.34      --  2   b
    1.35      --  3   c
    1.36  
    1.37 +    print(string.concat(",", t))
    1.38 +    -- prints: a,b,c
    1.39 +
    1.40      function alphabet()
    1.41        local letter = nil
    1.42        return function()
    1.43 @@ -57,6 +69,9 @@
    1.44      --  25  y
    1.45      --  26  z
    1.46  
    1.47 +    print(string.concat(",", alphabet()))
    1.48 +    -- 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
    1.49 +
    1.50      function filter(f, seq)
    1.51        return coroutine.wrap(function()
    1.52          for i, v in ipairs(seq) do f(v) end
    1.53 @@ -85,6 +100,9 @@
    1.54      --  true
    1.55      --  c
    1.56  
    1.57 +    print((","):concat(filter(filterfunc, {"a", "b", 3, "c"})))
    1.58 +    -- prints: a,b,true,true,true,c
    1.59 +
    1.60  
    1.61  C part of the library
    1.62  ---------------------
    1.63 @@ -95,6 +113,14 @@
    1.64        for ( \
    1.65          seqlua_iterinit((L), (iter), (idx)); \
    1.66          seqlua_iternext(iter); \
    1.67 +      )
    1.68 +
    1.69 +and
    1.70 +
    1.71 +    #define seqlua_iterloopauto(L, iter, idx) \
    1.72 +      for ( \
    1.73 +        seqlua_iterinit((L), (iter), (idx)); \
    1.74 +        seqlua_iternext(iter); \
    1.75          lua_pop((L), 1) \
    1.76        )
    1.77  
    1.78 @@ -106,7 +132,9 @@
    1.79        seqlua_iterloop(L, &iter, 1) {
    1.80          if (seqlua_itercount(&iter) > 1) fputs(",", stdout);
    1.81          fputs(luaL_tolstring(L, -1, NULL), stdout);
    1.82 -        lua_pop(L, 1);  // pops value that luaL_tolstring pushed onto stack
    1.83 +        // two values need to be popped (the value pushed by
    1.84 +        // seqlua_iternext and the value pushed by luaL_tolstring)
    1.85 +        lua_pop(L, 2);
    1.86        }
    1.87        fputs("\n", stdout);
    1.88        return 0;