doc/manual/stdlib.tex

   1 \def\function#1{\paragraph{#1}}
   2
   3 \section{Standard library}
   4 Metalua comes with a standard library which extends Lua's one. These
   5 extended features are enabled by adding a ``{\tt require "std"}''
   6 statement in your source files (it is already required at the
   7 compile-time level, so there's no need for a
   8 ``{\tt -\{ require "std" \}}'').
   9
  10 \subsection{Base library extensions}
  11
  12 \function{min(...)}
  13 Return the min of its arguments, according to {\tt<}. There must be at
  14 least one argument.
  15
  16 \function{max(...)}
  17 Return the max of its arguments, according to {\tt<}. There must be at
  18 least one argument.
  19
  20 \function{o(...)}
  21 Return the composition of all functions passed as arguments. For
  22 instance, {\tt printf} could be defined as {\tt print `o`
  23   string.format}\footnote{Or in regular Lua syntax {\tt o(print,
  24     string.format)}.}
  25
  26 \function{id(...)}
  27 Return all its arguments unchanged.
  28
  29 \function{const (...)}
  30 Return a function which always returns {\tt ...}, whatever its arguments.
  31 For instance, {\tt const(1, 2, 3)(4, 5, 6)} returns {\tt1, 2, 3}.
  32
  33 \function{printf(fmt,...)}
  34 Equivalent to {\tt print(string.format(fmt,...))}.
  35
  36 \function{values(table)}
  37 Iterator, to be used in a {\tt for} loop, which returns all the values
  38 of {\tt table}.
  39
  40 {\tt for x in values(t) do [...] end} is equivalent to {\tt for \_, x in
  41   pairs(t) do [...] end}.
  42
  43 \function{keys(table)}
  44 Iterators, to be used in a {\tt for} loop, which return all the keys
  45 of {\tt table}.
  46
  47 {\tt for k in keys(t) do [...] end} is equivalent to {\tt for k, \_ in
  48   pairs(t) do [...] end}.
  49
  50 \function{extension(name)}
  51 FIXME: move this into metalua.compiler?
  52
  53 \subsection{{\tt table} extensions}
  54
  55 Many of the extensions of {\tt table} are dedicated to a more
  56 functional style programming. When compared to the functions in
  57 Haskell or ML's standard libs, these one are slightly more general,
  58 taking advantage from Lua's dynamic typing.
  59
  60 \function{table.iforeach(f, ...)}
  61
  62 {\tt table.iforeach(f, t)} will evaluate f with every array-part
  63 elements of t in order.
  64
  65 If more than one table are passed as parameters, f will receive an
  66 element of each table at each iteration. For instance, {\tt
  67   table.iforeach (print, \{1, 2, 3\}, \{4, 5, 6\}, \{7, 8, 9\})} will
  68 print:
  69 \begin{verbatim}
  70 1 4 7
  71 2 5 8
  72 3 6 9
  73 \end{verbatim}
  74
  75 If the second and/or third parameters are numbers, they indicate the
  76 first and last indexes to use in the tables. First index defaults to
  77 1, last index default to the length of the longest table. If only one
  78 number is passed, it's considered to be the first index. For instance,
  79 {\tt table.iforeach (print, 2, \{1, 2, 3\}, \{4, 5, 6\}, \{7, 8, 9\})}
  80 will only print:
  81 \begin{verbatim}
  82 2 5 8
  83 3 6 9
  84 \end{verbatim}
  85
  86 \function{table.imap(f, ...)}
  87
  88 Similar to {\tt table.iforeach()}, except that the results of {\tt
  89   f()} calls are collected into a list and returned.
  90
  91 For instance, {\tt table.imap((|x,y|x+y), 2, \{"foo", 1, 2, 3\},
  92   \{"bar", 10, 20, 30\})} will return {\tt\{11, 22, 33\}}.
  93
  94 \function{table.ifold(f, acc, ...)}
  95
  96 Fold list elements thanks to a combining function {\tt f()}, which
  97 takes two list elements and returns one result. For the first
  98 iteration, {\tt f()} takes {\tt acc} as its first param. For instance,
  99 the sum of {\tt list}'s elements can be computed by {\tt table.ifold(
 100   (|x,y| x+y), 0, list)}.
 101
 102 This function also accepts first and last indexes after {\tt acc}, and
 103 more than one table argument: if there are more than one table, then
 104 more than two parameters are passed to {\tt f()}. For instance, this
 105 function returns $\sum_{i\le2} \max(x[i], y[i])$: {\tt
 106   table.ifold( (|acc, xi, yi| acc + max (xi, yi)), 0, 2, x, y)}.
 107
 108 \function{table.izip(...)}
 109
 110 Take a sequence of lists, and return the
 111 list of their first elements, then their second elements, etc. For
 112 instance, {\tt table.izip (\{1,2,3\}, \{4,5,6\})} will return
 113 {\tt\{\{1,4\}, \{2,5\} , \{3,6\}\}}.
 114
 115 \function{table.ifilter(f, t)}
 116
 117 Return the list of all elements of {\tt t} for which {\tt f} returns
 118 neither {\tt nil} nor {\tt false}.
 119
 120 \function{table.icat(...)}
 121
 122 Concatenate all the lists passed as arguments into a single one, then
 123 return it.
 124
 125 \function{table.iflatten(x)}
 126
 127 Flatten a list of lists into a list. for instance, {\tt
 128   table.iflatten\{\{1,2\}, \{3,4\}\}} returns {\tt\{1,2,3,4\}}.
 129
 130 \function{table.irev(t)}
 131 Reverse the order of elements in {\tt t}'s array-part. This is done
 132 in-place: if you don't want to alter the original list, first copy
 133 it.
 134
 135 \function{table.iall(f, ...)}
 136
 137 Return true if and only if {\tt table.iforeach(f, ...)} would return only
 138 non-false values.
 139
 140 \function{table.iany(f, ...)}
 141
 142 Return true if and only if {\tt table.iforeach(f, ...)} would return
 143 at least one non-false value.
 144
 145 \function{table.shallow\_copy(t)}
 146
 147 Does a shallow copy of the table {\tt t}. This differs from {\tt
 148   table.icat(t)}, because the latter would only copy tha array-part,
 149 whereas the former also copies the hash-part.
 150
 151 \function{table.deep\_copy(t)}
 152
 153 Does a deep copy of {\tt t}, i.e. all keys and values are recursively
 154 copied. Handles tables with shared and circular references correctly;
 155 also set the copy's metatable to the original's one.
 156
 157 \function{table.range(a, b, c)}
 158
 159 Return a list of all integers between {\tt a} and {\tt b} inclusive,
 160 with an increment {\tt c} (which defaults to 1).
 161
 162 \function{table.tostring(t, ...)}
 163
 164 Return a string which represents {\tt t}. This string is correctly
 165 indented, and handles Metalua's special syntax for ADT/AST
 166 gracefully. If {\tt"nohash"} is passed as an additional argument, then
 167 only the tag and array-part of the table are displayed. If a number
 168 {\tt n} is passed as extra argument, the function tries to keep the
 169 number of characters per line under {\tt n}.
 170
 171 \function{table.print(t, ...)}
 172
 173 Equivalent to {\tt print(table.tostring(t, ...))}.
 174
 175 \subsection{{\tt string} extensions}
 176
 177 \function{string.split(string, pattern)}
 178 Cut {\tt string} into a list of substrings separated by pattern {\tt
 179   pattern}, and return that list.
 180
 181
 182 \function{string.strmatch(...)}
 183
 184 Alias for {\tt string.match}: since it's quite common in metalua to
 185 use the pattern matching extension, which turns {\tt match} into a
 186 keyword, it's practical to have another name for this function.
 187
 188 \subsection{Library {\tt mlc}}
 189
 190 FIXME: move in metalua.compiler.
 191
 192 This library offer conversion between the different possible
 193 representations of metalua programs:
 194 \begin{itemize}
 195 \item as source files
 196 \item as compiled files
 197 \item as source strings
 198 \item as compiled chunk dumps (which are actually strings)
 199 \item as lexeme streams
 200 \item as AST
 201 \item FIXME
 202 \end{itemize}
 203
 204 Hopefully, the function names are self-explanatory. Some of them are
 205 simply aliases to other standard functions such as {\tt loadstring()}
 206 or {\tt string.dump()}; many others are compositions of other
 207 functions. The point is that every sensible transformation from
 208 representation {\tt xxx} to representation {\tt yyy} should appear in
 209 this library under the name {\tt yyy\_of\_xxx()}. This way, users
 210 don't have to wonder how to chain the appropriate functions to get the
 211 expected result.
 212
 213 The functions available in this module are:
 214
 215 \begin{tabular}{|l|l|l|l|}
 216   \hline
 217   FIXME \\\hline
 218 \end{tabular}
 219
 220 FIXME: implementation sucks beyond maintainability, it should be
 221 rewritten.
 222
 223 \subsection{Library {\tt walker}}
 224 This library allows code-walking, i.e. applying advanced, non-local
 225 transformations on ASTs. It's powerful, but definitely not user
 226 friendly; eventuallty, it might be replaced by a Term Rewriting
 227 System, supported by its own Domain-Specific Language.
 228
 229 \function{walk\_stat (cfg)}
 230 FIXME
 231 %don't get confused between the AST it applies on, the the AST being
 232 %currently inspected.
 233
 234 %function calls and method invocations in a statement context are not
 235 %considered as expressions.
 236
 237 \function{walk\_expr (cfg)}
 238 Same as {\tt walk\_stat}, except that it takes an expression AST
 239 instead of a statement AST.
 240
 241 \function{walk\_block (cfg)}
 242 Same as {\tt walk\_stat}, except that it takes a statements block AST
 243 instead of a single statement AST.