luci-base: break circular luci.config <> luci.model.uci dependency
[project/luci.git] / modules / luci-base / luasrc / util.luadoc
1 ---[[
2 LuCI utility functions.
3 ]]
4 module "luci.util"
5
6 ---[[
7 Create a Class object (Python-style object model).
8
9 The class object can be instantiated by calling itself.
10 Any class functions or shared parameters can be attached to this object.
11 Attaching a table to the class object makes this table shared between
12 all instances of this class. For object parameters use the __init__ function.
13 Classes can inherit member functions and values from a base class.
14 Class can be instantiated by calling them. All parameters will be passed
15 to the __init__ function of this class - if such a function exists.
16 The __init__ function must be used to set any object parameters that are not shared
17 with other objects of this class. Any return values will be ignored.
18
19 @class                          function
20 @name                           class
21 @param base                     The base class to inherit from (optional)
22 @return                         A class object
23 @see                            instanceof
24 @see                            clone
25 ]]
26
27 ---[[
28 Test whether the given object is an instance of the given class.
29
30 @class                          function
31 @name                           instanceof
32 @param object           Object instance
33 @param class            Class object to test against
34 @return                         Boolean indicating whether the object is an instance
35 @see                            class
36 @see                            clone
37 ]]
38
39 ---[[
40 Create a new or get an already existing thread local store associated with
41 the current active coroutine.
42
43 A thread local store is private a table object
44 whose values can't be accessed from outside of the running coroutine.
45
46 @class                          function
47 @name                           threadlocal
48 @return                         Table value representing the corresponding thread local store
49 ]]
50
51 ---[[
52 Write given object to stderr.
53
54 @class                          function
55 @name                           perror
56 @param obj                      Value to write to stderr
57 @return                         Boolean indicating whether the write operation was successful
58 ]]
59
60 ---[[
61 Recursively dumps a table to stdout, useful for testing and debugging.
62
63 @class                          function
64 @name                           dumptable
65 @param t                        Table value to dump
66 @param maxdepth         Maximum depth
67 @return                         Always nil
68 ]]
69
70 ---[[
71 Create valid XML PCDATA from given string.
72
73 @class                          function
74 @name                           pcdata
75 @param value            String value containing the data to escape
76 @return                         String value containing the escaped data
77 ]]
78
79 ---[[
80 Decode an URL-encoded string - optionally decoding the "+" sign to space.
81
82 @class                          function
83 @name                           urldecode
84 @param str                      Input string in x-www-urlencoded format
85 @param decode_plus      Decode "+" signs to spaces if true (optional)
86 @return                         The decoded string
87 @see                            urlencode
88 ]]
89
90 ---[[
91 URL-encode given string.
92
93 @class                          function
94 @name                           urlencode
95 @param str                      String to encode
96 @return                         String containing the encoded data
97 @see                            urldecode
98 ]]
99
100 ---[[
101 Strip HTML tags from given string.
102
103 @class                          function
104 @name                           striptags
105 @param value            String containing the HTML text
106 @return                         String with HTML tags stripped of
107 ]]
108
109 ---[[
110 Safely quote value for use in shell commands.
111
112 @class                          function
113 @name                           shellquote
114 @param value            String containing the value to quote
115 @return                         Single-quote enclosed string with embedded quotes escaped
116 ]]
117
118 ---[[
119 Splits given string on a defined separator sequence and return a table
120 containing the resulting substrings.
121
122 The optional max parameter specifies the number of bytes to process,
123 regardless of the actual length of the given string. The optional last
124 parameter, regex, specifies whether the separator sequence is
125 nterpreted as regular expression.
126
127 @class                          function
128 @name                           split
129 @param str                      String value containing the data to split up
130 @param pat                      String with separator pattern (optional, defaults to "\n")
131 @param max                      Maximum times to split (optional)
132 @param regex            Boolean indicating whether to interpret the separator
133 --                                      pattern as regular expression (optional, default is false)
134 @return                         Table containing the resulting substrings
135 ]]
136
137 ---[[
138 Remove leading and trailing whitespace from given string value.
139
140 @class                          function
141 @name                           trim
142 @param str                      String value containing whitespace padded data
143 @return                         String value with leading and trailing space removed
144 ]]
145
146 ---[[
147 Count the occurrences of given substring in given string.
148
149 @class                          function
150 @name                           cmatch
151 @param str                      String to search in
152 @param pattern          String containing pattern to find
153 @return                         Number of found occurrences
154 ]]
155
156 ---[[
157 Return a matching iterator for the given value.
158
159 The iterator will return one token per invocation, the tokens are separated by
160 whitespace. If the input value is a table, it is transformed into a string first.
161 A nil value will result in a valid interator which aborts with the first invocation.
162
163 @class                          function
164 @name                           imatch
165 @param val                      The value to scan (table, string or nil)
166 @return                         Iterator which returns one token per call
167 ]]
168
169 ---[[
170 Parse certain units from the given string and return the canonical integer
171 value or 0 if the unit is unknown.
172
173 Upper- or lower case is irrelevant.
174 Recognized units are:
175
176 --      o "y"   - one year   (60*60*24*366)
177  o "m"  - one month  (60*60*24*31)
178  o "w"  - one week   (60*60*24*7)
179  o "d"  - one day    (60*60*24)
180  o "h"  - one hour       (60*60)
181  o "min"        - one minute (60)
182  o "kb"  - one kilobyte (1024)
183  o "mb" - one megabyte (1024*1024)
184  o "gb" - one gigabyte (1024*1024*1024)
185  o "kib" - one si kilobyte (1000)
186  o "mib"        - one si megabyte (1000*1000)
187  o "gib"        - one si gigabyte (1000*1000*1000)
188
189 @class                          function
190 @name                           parse_units
191 @param ustr                     String containing a numerical value with trailing unit
192 @return                         Number containing the canonical value
193 ]]
194
195 ---[[
196 Appends numerically indexed tables or single objects to a given table.
197
198 @class                          function
199 @name                           append
200 @param src                      Target table
201 @param ...                      Objects to insert
202 @return                         Target table
203 ]]
204
205 ---[[
206 Combines two or more numerically indexed tables and single objects into one table.
207
208 @class                          function
209 @name                           combine
210 @param tbl1                     Table value to combine
211 @param tbl2                     Table value to combine
212 @param ...                      More tables to combine
213 @return                         Table value containing all values of given tables
214 ]]
215
216 ---[[
217 Checks whether the given table contains the given value.
218
219 @class                          function
220 @name                           contains
221 @param table            Table value
222 @param value            Value to search within the given table
223 @return                         Number indicating the first index at which the given value occurs
224 --                                      within table or false.
225 ]]
226
227 ---[[
228 Update values in given table with the values from the second given table.
229
230 Both table are - in fact - merged together.
231
232 @class                          function
233 @name                           update
234 @param t                        Table which should be updated
235 @param updates          Table containing the values to update
236 @return                         Always nil
237 ]]
238
239 ---[[
240 Retrieve all keys of given associative table.
241
242 @class                          function
243 @name                           keys
244 @param t                        Table to extract keys from
245 @return                         Sorted table containing the keys
246 ]]
247
248 ---[[
249 Clones the given object and return it's copy.
250
251 @class                          function
252 @name                           clone
253 @param object           Table value to clone
254 @param deep                     Boolean indicating whether to do recursive cloning
255 @return                         Cloned table value
256 ]]
257
258 ---[[
259 Recursively serialize given data to lua code, suitable for restoring
260 with loadstring().
261
262 @class                          function
263 @name                           serialize_data
264 @param val                      Value containing the data to serialize
265 @return                         String value containing the serialized code
266 @see                            restore_data
267 @see                            get_bytecode
268 ]]
269
270 ---[[
271 Restore data previously serialized with serialize_data().
272
273 @class                          function
274 @name                           restore_data
275 @param str                      String containing the data to restore
276 @return                         Value containing the restored data structure
277 @see                            serialize_data
278 @see                            get_bytecode
279 ]]
280
281 ---[[
282 Return the current runtime bytecode of the given data. The byte code
283 will be stripped before it is returned.
284
285 @class                          function
286 @name                           get_bytecode
287 @param val                      Value to return as bytecode
288 @return                         String value containing the bytecode of the given data
289 ]]
290
291 ---[[
292 Strips unnescessary lua bytecode from given string.
293
294 Information like line numbers and debugging numbers will be discarded.
295 Original version by Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
296
297 @class                          function
298 @name                           strip_bytecode
299 @param code                     String value containing the original lua byte code
300 @return                         String value containing the stripped lua byte code
301 ]]
302
303 ---[[
304 Return a key, value iterator which returns the values sorted according to
305 the provided callback function.
306
307 @class                          function
308 @name                           spairs
309 @param t                        The table to iterate
310 @param f                        A callback function to decide the order of elements
311 @return                         Function value containing the corresponding iterator
312 ]]
313
314 ---[[
315 Return a key, value iterator for the given table.
316
317 The table pairs are sorted by key.
318
319 @class                          function
320 @name                           kspairs
321 @param t                        The table to iterate
322 @return                         Function value containing the corresponding iterator
323 ]]
324
325 ---[[
326 Return a key, value iterator for the given table.
327
328 The table pairs are sorted by value.
329
330 @class                          function
331 @name                           vspairs
332 @param t                        The table to iterate
333 @return                         Function value containing the corresponding iterator
334 ]]
335
336 ---[[
337 Test whether the current system is operating in big endian mode.
338
339 @class                          function
340 @name                           bigendian
341 @return                         Boolean value indicating whether system is big endian
342 ]]
343
344 ---[[
345 Execute given commandline and gather stdout.
346
347 @class                          function
348 @name                           exec
349 @param command          String containing command to execute
350 @return                         String containing the command's stdout
351 ]]
352
353 ---[[
354 Return a line-buffered iterator over the output of given command.
355
356 @class                          function
357 @name                           execi
358 @param command          String containing the command to execute
359 @return                         Iterator
360 ]]
361
362 ---[[
363 Issue an ubus call.
364
365 @class                          function
366 @name                           ubus
367 @param object           String containing the ubus object to call
368 @param method           String containing the ubus method to call
369 @param values           Table containing the values to pass
370 @return                         Table containin the ubus result
371 ]]
372
373 ---[[
374 Convert data structure to JSON
375
376 @class                          function
377 @name                           serialize_json
378 @param data                     The data to serialize
379 @param writer           A function to write a chunk of JSON data (optional)
380 @return                         String containing the JSON if called without write callback
381 ]]
382
383 ---[[
384 Returns the absolute path to LuCI base directory.
385
386 @class                          function
387 @name                           libpath
388 @return                         String containing the directory path
389 ]]
390
391 ---[[
392 This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
393
394 @class                          function
395 @name                           coxpcall
396 @param f                        Lua function to be called protected
397 @param err                      Custom error handler
398 @param ...                      Parameters passed to the function
399 @return                         A boolean whether the function call succeeded and the return
400 --                                      values of either the function or the error handler
401 ]]
402
403 ---[[
404 This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
405
406 @class                          function
407 @name                           copcall
408 @param f                        Lua function to be called protected
409 @param ...                      Parameters passed to the function
410 @return                         A boolean whether the function call succeeded and the returns
411 --                                      values of the function or the error object
412 ]]
413