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 of 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 is passed as arguments, 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 indices to use in the tables. The first index defaults
  77 to 1, the last index defaults to the length of the longest table. If
  78 only one number is passed, it's considered to be the first index. For
  79 instance,
  80 {\tt table.iforeach (print, 2, \{1, 2, 3\}, \{4, 5, 6\}, \{7, 8, 9\})}
  81 will only print:
  82 \begin{verbatim}
  83 2 5 8
  84 3 6 9
  85 \end{verbatim}
  86
  87 \function{table.imap(f, ...)}
  88
  89 Similar to {\tt table.iforeach()}, except that the results of {\tt
  90   f()} calls are collected into a list and returned.
  91
  92 For instance, {\tt table.imap((|x,y|x+y), 2, \{"foo", 1, 2, 3\},
  93   \{"bar", 10, 20, 30\})} will return {\tt\{11, 22, 33\}}.
  94
  95 \function{table.ifold(f, acc, ...)}
  96
  97 Fold list elements thanks to a combining function {\tt f()}, which
  98 takes two list elements and returns one result. For the first
  99 iteration, {\tt f()} takes {\tt acc} as its first param. For instance,
 100 the sum of {\tt list}'s elements can be computed by {\tt table.ifold(
 101   (|x,y| x+y), 0, list)}.
 102
 103 This function also accepts first and last indices after {\tt acc}, and
 104 more than one table argument: if there is more than one table, then
 105 more than two parameters are passed to {\tt f()}. For instance, this
 106 function returns $\sum_{i\le2} \max(x[i], y[i])$: {\tt
 107   table.ifold( (|acc, xi, yi| acc + max (xi, yi)), 0, 2, x, y)}.
 108
 109 \function{table.izip(...)}
 110
 111 Takes a sequence of lists, and returns the
 112 list of their first elements, then their second elements, etc. For
 113 instance, {\tt table.izip (\{1,2,3\}, \{4,5,6\})} will return
 114 {\tt\{\{1,4\}, \{2,5\} , \{3,6\}\}}.
 115
 116 \function{table.ifilter(f, t)}
 117
 118 Return the list of all elements of {\tt t} for which {\tt f} returns
 119 neither {\tt nil} nor {\tt false}.
 120
 121 \function{table.icat(...)}
 122
 123 Concatenate all the lists passed as arguments into a single one, then
 124 return it.
 125
 126 \function{table.iflatten(x)}
 127
 128 Flatten a list of lists into a list. for instance, {\tt
 129   table.iflatten\{\{1,2\}, \{3,4\}\}} returns {\tt\{1,2,3,4\}}.
 130
 131 \function{table.irev(t)}
 132 Reverse the order of elements in {\tt t}'s array-part. This is done
 133 in-place: if you don't want to alter the original list, first copy
 134 it.
 135
 136 \function{table.iall(f, ...)}
 137
 138 Return true if and only if {\tt table.iforeach(f, ...)} would return only
 139 non-false values.
 140
 141 \function{table.iany(f, ...)}
 142
 143 Return true if and only if {\tt table.iforeach(f, ...)} would return
 144 at least one non-false value.
 145
 146 \function{table.shallow\_copy(t)}
 147
 148 Does a shallow copy of the table {\tt t}. This differs from {\tt
 149   table.icat(t)}, because the latter would only copy tha array-part,
 150 whereas the former also copies the hash-part.
 151
 152 \function{table.deep\_copy(t)}
 153
 154 Does a deep copy of {\tt t}, i.e. all keys and values are recursively
 155 copied. Handles tables with shared and circular references correctly;
 156 also sets the copy's metatable to the original's one.
 157
 158 \function{table.range(a, b, c)}
 159
 160 Return a list of all integers between {\tt a} and {\tt b} inclusive,
 161 with an increment {\tt c} (which defaults to 1).
 162
 163 \function{table.tostring(t, ...)}
 164
 165 Return a string which represents {\tt t}. This string is correctly
 166 indented, and handles Metalua's special syntax for ADT/AST
 167 gracefully. If {\tt"nohash"} is passed as an additional argument, then
 168 only the tag and array-part of the table are displayed. If a number
 169 {\tt n} is passed as extra argument, the function tries to keep the
 170 number of characters per line under {\tt n}.
 171
 172 \function{table.print(t, ...)}
 173
 174 Equivalent to {\tt print(table.tostring(t, ...))}.
 175
 176 \subsection{{\tt string} extensions}
 177
 178 \function{string.split(string, pattern)}
 179 Cut {\tt string} into a list of substrings separated by pattern {\tt
 180   pattern}, and return that list.
 181
 182
 183 \function{string.strmatch(...)}
 184
 185 Alias for {\tt string.match}: since it's quite common in metalua to
 186 use the pattern matching extension, which turns {\tt match} into a
 187 keyword, it's practical to have another name for this function.
 188
 189 \subsection{Library {\tt mlc}}
 190
 191 FIXME: move into metalua.compiler.
 192
 193 This library offers conversions between the different possible
 194 representations of metalua programs:
 195 \begin{itemize}
 196 \item as source files
 197 \item as compiled files
 198 \item as source strings
 199 \item as compiled chunk dumps (which are actually strings)
 200 \item as lexeme streams
 201 \item as AST
 202 \item FIXME
 203 \end{itemize}
 204
 205 The function names are hopefully self-explanatory. Some of them are
 206 simply aliases to other standard functions such as {\tt loadstring()}
 207 or {\tt string.dump()}; many others are compositions of other
 208 functions. The point is that every sensible transformation from
 209 representation {\tt xxx} to representation {\tt yyy} should appear in
 210 this library under the name {\tt yyy\_of\_xxx()}. This way, users
 211 don't have to wonder how to chain the appropriate functions to get the
 212 expected result.
 213
 214 The functions available in this module are:
 215
 216 \begin{tabular}{|l|l|l|l|}
 217   \hline
 218   FIXME \\\hline
 219 \end{tabular}
 220
 221 FIXME: implementation sucks beyond maintainability, it should be
 222 rewritten.
 223
 224 \subsection{Library {\tt walker}}
 225 This library allows code-walking, i.e. applying advanced, non-local
 226 transformations on ASTs. It's powerful, but definitely not user
 227 friendly; eventuallty, it might be replaced by a Term Rewriting
 228 System, supported by its own Domain-Specific Language.
 229
 230 \function{walk\_stat (cfg)}
 231 FIXME
 232 %don't get confused between the AST it applies on and the AST being
 233 %currently inspected.
 234
 235 %function calls and method invocations in a statement context are not
 236 %considered as expressions.
 237
 238 \function{walk\_expr (cfg)}
 239 Same as {\tt walk\_stat}, except that it takes an expression AST
 240 instead of a statement AST.
 241
 242 \function{walk\_block (cfg)}
 243 Same as {\tt walk\_stat}, except that it takes a statements block AST
 244 instead of a single statement AST.