doc/manual/clist-ref.tex

   1 \section{{\tt clist}: Lists by comprehension}
   2
   3 This extension offers improved tables-as-list syntax:
   4 \begin{itemize}
   5 \item lists by comprehension;
   6 \item literal lists splicing;
   7 \item list sub-sampling.
   8 \end{itemize}
   9
  10 Lists by comprehensions allow to describe a list in terms of
  11 generation loops and filtering. The loops are the two flavors of
  12 ``for'' controls, and the syntax is {\tt\{ <value> <loop\_header>
  13   \}}. For instance, the list {\tt\{10, 20, 30, 40, 50\}} can be generated
  14 as {\tt\{ x for x=10, 50, 10 \}}, or {\tt\{ 10*x for i=1, 5 \}}. The
  15 list of all keys from table {\tt t} can be gathered with {\tt\{ k for
  16   k, v in pairs(t) \}}. Several loops can be nested. For instance, the
  17 list of all products of elements taken from list {\tt a} and {\tt b}
  18 can be computed with {\tt\{ i*j for \_, i in ipairs(a) for \_, j in
  19   ipairs(b) \}}.
  20
  21 Finally, results can be filtered out of a list. For instance, the
  22 elements of {\tt a} which are multiple of 3 can be gathered with
  23 {\tt\{ x for \_, x in ipairs(a) if x\%3==0 \}}.
  24
  25 In Lua, when a list is defined and one of its elements is a multiple
  26 return function, only the first returned value is kept, except for the
  27 last element (cf. Lua manual 2.5.7). For instance, in the example
  28 below, {\tt x} is set to {\tt\{1, 1, 1, 2, 3\}}: only the last call to
  29 {\tt f()} is expanded:
  30
  31 \begin{verbatim}
  32 function f()
  33   return 1, 2, 3
  34 end
  35 x = { f(), f(), f() }
  36 \end{verbatim}
  37
  38 The extension offers a way to expand intermediate response: they have
  39 to be followed by {\tt...}. In the example above, {\tt y = \{f()...,
  40   f()..., f()...\}} would expand as {\tt\{1, 2, 3, 1, 2, 3, 1, 2,
  41   3\}}.
  42
  43 Comprehensions are naturally expanded, i.e. another way to write {\tt
  44   y} would have been {\tt y = \{i for i=1,3; i for i=1,3; i for
  45   i=1,3\}} (notice however that we had to separate elements with
  46 semicolons rather than commas: if we didn't, the {\tt i} of the second
  47 loop would have been taken as a third parameter to the first for loop
  48 header).
  49
  50 Sub-sampling is done with indexes, by using the comma to separate
  51 indices, and {\tt...} as an infix operator to denote intervals. The
  52 latter binds tighter than the former. For instance:
  53
  54 \begin{verbatim}
  55 x = { i for i=101, 130 }
  56 y = x[1 ... 10, 20, 25]
  57 z = { i for i=101,110; 120; 125 }
  58
  59 assert (#y == #z)
  60 for i = 1, #x do
  61   assert (y[i] == z[i]
  62 end
  63 \end{verbatim}
  64
  65 Beware of a lexing issue: if you write ``{\tt[1...n]}'', it will be
  66 interpreted as number {\tt 1.} followed by operator {\tt..}: put a
  67 space between literal numbers and operators starting with a dot.
  68
  69 Notice that there are now two substancially different operators with
  70 very similar syntaxes: the original index operator, which returns a
  71 single element, and the sub-sampling operators, which returns a list
  72 of elements. If you want to returna single element list, you can
  73 either reconstruct it from the regular index operator ({\tt
  74   y=\{x[i]\}}), or use a single element wide interval ({\tt
  75   y=x[i...i]}).
  76
  77 FIXME: there should be \verb|x[...i]| and \verb|x[i...]| sub-sampling
  78 notations, but they aren't currently implemented.