1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
5 <title>Reference</title>
6 <link rel="stylesheet" href="../luadoc.css" type="text/css" />
7 <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
14 <div id="product_logo"></div>
15 <div id="product_name"><big><b></b></big></div>
16 <div id="product_description"></div>
17 </div> <!-- id="product" -->
27 <li><a href="../index.html">Index</a></li>
38 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
42 <a href="../modules/luci.http.html">luci.http</a>
46 <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
50 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
54 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
58 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
62 <a href="../modules/luci.i18n.html">luci.i18n</a>
66 <a href="../modules/luci.ip.html">luci.ip</a>
70 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
74 <a href="../modules/luci.json.html">luci.json</a>
78 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
82 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
86 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
90 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
94 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
98 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
102 <a href="../modules/luci.sys.html">luci.sys</a>
106 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
110 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
114 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
118 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
122 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
126 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
129 <li><strong>luci.util</strong></li>
132 <a href="../modules/nixio.html">nixio</a>
136 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
140 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
144 <a href="../modules/nixio.File.html">nixio.File</a>
148 <a href="../modules/nixio.README.html">nixio.README</a>
152 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
156 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
160 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
164 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
168 <a href="../modules/nixio.bin.html">nixio.bin</a>
172 <a href="../modules/nixio.bit.html">nixio.bit</a>
176 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
180 <a href="../modules/nixio.fs.html">nixio.fs</a>
195 </div><!-- id="navigation" -->
199 <h1>Class <code>luci.util</code></h1>
210 <table class="function_list">
213 <td class="name" nowrap><a href="#append">append</a> (src, ...)</td>
216 Appends numerically indexed tables or single objects to a given table.</td>
220 <td class="name" nowrap><a href="#bigendian">bigendian</a> ()</td>
223 Test whether the current system is operating in big endian mode.</td>
227 <td class="name" nowrap><a href="#class">class</a> (base)</td>
230 Create a Class object (Python-style object model).</td>
234 <td class="name" nowrap><a href="#clone">clone</a> (object, deep)</td>
237 Clones the given object and return it's copy.</td>
241 <td class="name" nowrap><a href="#cmatch">cmatch</a> (str, pattern)</td>
244 Count the occurrences of given substring in given string.</td>
248 <td class="name" nowrap><a href="#combine">combine</a> (tbl1, tbl2, ...)</td>
251 Combines two or more numerically indexed tables and single objects into one table.</td>
255 <td class="name" nowrap><a href="#contains">contains</a> (table, value)</td>
258 Checks whether the given table contains the given value.</td>
262 <td class="name" nowrap><a href="#copcall">copcall</a> (f, ...)</td>
265 This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
270 <td class="name" nowrap><a href="#coxpcall">coxpcall</a> (f, err, ...)</td>
273 This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
278 <td class="name" nowrap><a href="#dtable">dtable</a> ()</td>
281 Create a dynamic table which automatically creates subtables.</td>
285 <td class="name" nowrap><a href="#dumptable">dumptable</a> (t, maxdepth)</td>
288 Recursively dumps a table to stdout, useful for testing and debugging.</td>
292 <td class="name" nowrap><a href="#exec">exec</a> (command)</td>
295 Execute given commandline and gather stdout.</td>
299 <td class="name" nowrap><a href="#execi">execi</a> (command)</td>
302 Return a line-buffered iterator over the output of given command.</td>
306 <td class="name" nowrap><a href="#get_bytecode">get_bytecode</a> (val)</td>
309 Return the current runtime bytecode of the given data.</td>
313 <td class="name" nowrap><a href="#imatch">imatch</a> (val)</td>
316 Return a matching iterator for the given value.</td>
320 <td class="name" nowrap><a href="#instanceof">instanceof</a> (object, class)</td>
323 Test whether the given object is an instance of the given class.</td>
327 <td class="name" nowrap><a href="#keys">keys</a> (t)</td>
330 Retrieve all keys of given associative table.</td>
334 <td class="name" nowrap><a href="#kspairs">kspairs</a> (t)</td>
337 Return a key, value iterator for the given table.</td>
341 <td class="name" nowrap><a href="#libpath">libpath</a> ()</td>
344 Returns the absolute path to LuCI base directory.</td>
348 <td class="name" nowrap><a href="#parse_units">parse_units</a> (ustr)</td>
351 Parse certain units from the given string and return the canonical integer
353 value or 0 if the unit is unknown.</td>
357 <td class="name" nowrap><a href="#pcdata">pcdata</a> (value)</td>
360 Create valid XML PCDATA from given string.</td>
364 <td class="name" nowrap><a href="#perror">perror</a> (obj)</td>
367 Write given object to stderr.</td>
371 <td class="name" nowrap><a href="#restore_data">restore_data</a> (str)</td>
374 Restore data previously serialized with serialize_data().</td>
378 <td class="name" nowrap><a href="#serialize_data">serialize_data</a> (val)</td>
381 Recursively serialize given data to lua code, suitable for restoring
383 with loadstring().</td>
387 <td class="name" nowrap><a href="#serialize_json">serialize_json</a> (data, writer)</td>
390 Convert data structure to JSON
395 <td class="name" nowrap><a href="#spairs">spairs</a> (t, f)</td>
398 Return a key, value iterator which returns the values sorted according to
400 the provided callback function.</td>
404 <td class="name" nowrap><a href="#split">split</a> (str, pat, max, regex)</td>
407 Splits given string on a defined separator sequence and return a table
409 containing the resulting substrings.</td>
413 <td class="name" nowrap><a href="#strip_bytecode">strip_bytecode</a> (code)</td>
416 Strips unnescessary lua bytecode from given string.</td>
420 <td class="name" nowrap><a href="#striptags">striptags</a> (value)</td>
423 Strip HTML tags from given string.</td>
427 <td class="name" nowrap><a href="#threadlocal">threadlocal</a> ()</td>
430 Create a new or get an already existing thread local store associated with
432 the current active coroutine.</td>
436 <td class="name" nowrap><a href="#trim">trim</a> (str)</td>
439 Remove leading and trailing whitespace from given string value.</td>
443 <td class="name" nowrap><a href="#ubus">ubus</a> (object, method, values)</td>
446 Issue an ubus call.</td>
450 <td class="name" nowrap><a href="#update">update</a> (t, updates)</td>
453 Update values in given table with the values from the second given table.</td>
457 <td class="name" nowrap><a href="#vspairs">vspairs</a> (t)</td>
460 Return a key, value iterator for the given table.</td>
474 <h2><a name="functions"></a>Functions</h2>
475 <dl class="function">
479 <dt><a name="append"></a><strong>append</strong> (src, ...)</dt>
483 Appends numerically indexed tables or single objects to a given table.
495 ...: Objects to insert
505 <h3>Return value:</h3>
515 <dt><a name="bigendian"></a><strong>bigendian</strong> ()</dt>
519 Test whether the current system is operating in big endian mode.
528 <h3>Return value:</h3>
529 Boolean value indicating whether system is big endian
538 <dt><a name="class"></a><strong>class</strong> (base)</dt>
542 Create a Class object (Python-style object model).
544 The class object can be instantiated by calling itself.
545 Any class functions or shared parameters can be attached to this object.
546 Attaching a table to the class object makes this table shared between
547 all instances of this class. For object parameters use the __init__ function.
548 Classes can inherit member functions and values from a base class.
549 Class can be instantiated by calling them. All parameters will be passed
550 to the __init__ function of this class - if such a function exists.
551 The __init__ function must be used to set any object parameters that are not shared
552 with other objects of this class. Any return values will be ignored.
559 base: The base class to inherit from (optional)
569 <h3>Return value:</h3>
577 <li><a href="#instanceof">
581 <li><a href="#clone">
592 <dt><a name="clone"></a><strong>clone</strong> (object, deep)</dt>
596 Clones the given object and return it's copy.
604 object: Table value to clone
608 deep: Boolean indicating whether to do recursive cloning
618 <h3>Return value:</h3>
628 <dt><a name="cmatch"></a><strong>cmatch</strong> (str, pattern)</dt>
632 Count the occurrences of given substring in given string.
640 str: String to search in
644 pattern: String containing pattern to find
654 <h3>Return value:</h3>
655 Number of found occurrences
664 <dt><a name="combine"></a><strong>combine</strong> (tbl1, tbl2, ...)</dt>
668 Combines two or more numerically indexed tables and single objects into one table.
676 tbl1: Table value to combine
680 tbl2: Table value to combine
684 ...: More tables to combine
694 <h3>Return value:</h3>
695 Table value containing all values of given tables
704 <dt><a name="contains"></a><strong>contains</strong> (table, value)</dt>
708 Checks whether the given table contains the given value.
720 value: Value to search within the given table
730 <h3>Return value:</h3>
731 number indicating the first index at which the given value occurs
732 within table or false.
741 <dt><a name="copcall"></a><strong>copcall</strong> (f, ...)</dt>
745 This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
753 f: Lua function to be called protected
757 ...: Parameters passed to the function
767 <h3>Return value:</h3>
768 A boolean whether the function call succeeded and the returns
769 values of the function or the error object
778 <dt><a name="coxpcall"></a><strong>coxpcall</strong> (f, err, ...)</dt>
782 This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
790 f: Lua function to be called protected
794 err: Custom error handler
798 ...: Parameters passed to the function
808 <h3>Return value:</h3>
809 A boolean whether the function call succeeded and the return
810 values of either the function or the error handler
819 <dt><a name="dtable"></a><strong>dtable</strong> ()</dt>
823 Create a dynamic table which automatically creates subtables.
832 <h3>Return value:</h3>
842 <dt><a name="dumptable"></a><strong>dumptable</strong> (t, maxdepth)</dt>
846 Recursively dumps a table to stdout, useful for testing and debugging.
854 t: Table value to dump
858 maxdepth: Maximum depth
868 <h3>Return value:</h3>
878 <dt><a name="exec"></a><strong>exec</strong> (command)</dt>
882 Execute given commandline and gather stdout.
890 command: String containing command to execute
900 <h3>Return value:</h3>
901 String containing the command's stdout
910 <dt><a name="execi"></a><strong>execi</strong> (command)</dt>
914 Return a line-buffered iterator over the output of given command.
922 command: String containing the command to execute
932 <h3>Return value:</h3>
942 <dt><a name="get_bytecode"></a><strong>get_bytecode</strong> (val)</dt>
946 Return the current runtime bytecode of the given data. The byte code
948 will be stripped before it is returned.
955 val: Value to return as bytecode
965 <h3>Return value:</h3>
966 String value containing the bytecode of the given data
975 <dt><a name="imatch"></a><strong>imatch</strong> (val)</dt>
979 Return a matching iterator for the given value. The iterator will return
981 one token per invocation, the tokens are separated by whitespace. If the
982 input value is a table, it is transformed into a string first. A nil value
983 will result in a valid interator which aborts with the first invocation.
990 val: The value to scan (table, string or nil)
1000 <h3>Return value:</h3>
1001 Iterator which returns one token per call
1010 <dt><a name="instanceof"></a><strong>instanceof</strong> (object, class)</dt>
1014 Test whether the given object is an instance of the given class.
1022 object: Object instance
1026 class: Class object to test against
1036 <h3>Return value:</h3>
1037 Boolean indicating whether the object is an instance
1044 <li><a href="#class">
1048 <li><a href="#clone">
1059 <dt><a name="keys"></a><strong>keys</strong> (t)</dt>
1063 Retrieve all keys of given associative table.
1071 t: Table to extract keys from
1081 <h3>Return value:</h3>
1082 Sorted table containing the keys
1091 <dt><a name="kspairs"></a><strong>kspairs</strong> (t)</dt>
1095 Return a key, value iterator for the given table.
1097 The table pairs are sorted by key.
1104 t: The table to iterate
1114 <h3>Return value:</h3>
1115 Function value containing the corresponding iterator
1124 <dt><a name="libpath"></a><strong>libpath</strong> ()</dt>
1128 Returns the absolute path to LuCI base directory.
1137 <h3>Return value:</h3>
1138 String containing the directory path
1147 <dt><a name="parse_units"></a><strong>parse_units</strong> (ustr)</dt>
1151 Parse certain units from the given string and return the canonical integer
1153 value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
1154 Recognized units are:
1155 o "y" - one year (60*60*24*366)
1156 o "m" - one month (60*60*24*31)
1157 o "w" - one week (60*60*24*7)
1158 o "d" - one day (60*60*24)
1159 o "h" - one hour (60*60)
1160 o "min" - one minute (60)
1161 o "kb" - one kilobyte (1024)
1162 o "mb" - one megabyte (1024*1024)
1163 o "gb" - one gigabyte (1024*1024*1024)
1164 o "kib" - one si kilobyte (1000)
1165 o "mib" - one si megabyte (1000*1000)
1166 o "gib" - one si gigabyte (1000*1000*1000)
1173 ustr: String containing a numerical value with trailing unit
1183 <h3>Return value:</h3>
1184 Number containing the canonical value
1193 <dt><a name="pcdata"></a><strong>pcdata</strong> (value)</dt>
1197 Create valid XML PCDATA from given string.
1205 value: String value containing the data to escape
1215 <h3>Return value:</h3>
1216 String value containing the escaped data
1225 <dt><a name="perror"></a><strong>perror</strong> (obj)</dt>
1229 Write given object to stderr.
1237 obj: Value to write to stderr
1247 <h3>Return value:</h3>
1248 Boolean indicating whether the write operation was successful
1257 <dt><a name="restore_data"></a><strong>restore_data</strong> (str)</dt>
1261 Restore data previously serialized with serialize_data().
1269 str: String containing the data to restore
1279 <h3>Return value:</h3>
1280 Value containing the restored data structure
1287 <li><a href="#serialize_data">
1291 <li><a href="#get_bytecode">
1302 <dt><a name="serialize_data"></a><strong>serialize_data</strong> (val)</dt>
1306 Recursively serialize given data to lua code, suitable for restoring
1315 val: Value containing the data to serialize
1325 <h3>Return value:</h3>
1326 String value containing the serialized code
1333 <li><a href="#restore_data">
1337 <li><a href="#get_bytecode">
1348 <dt><a name="serialize_json"></a><strong>serialize_json</strong> (data, writer)</dt>
1352 Convert data structure to JSON
1360 data: The data to serialize
1364 writer: A function to write a chunk of JSON data (optional)
1374 <h3>Return value:</h3>
1375 String containing the JSON if called without write callback
1384 <dt><a name="spairs"></a><strong>spairs</strong> (t, f)</dt>
1388 Return a key, value iterator which returns the values sorted according to
1390 the provided callback function.
1397 t: The table to iterate
1401 f: A callback function to decide the order of elements
1411 <h3>Return value:</h3>
1412 Function value containing the corresponding iterator
1421 <dt><a name="split"></a><strong>split</strong> (str, pat, max, regex)</dt>
1425 Splits given string on a defined separator sequence and return a table
1427 containing the resulting substrings. The optional max parameter specifies
1428 the number of bytes to process, regardless of the actual length of the given
1429 string. The optional last parameter, regex, specifies whether the separator
1430 sequence is interpreted as regular expression.
1437 str: String value containing the data to split up
1441 pat: String with separator pattern (optional, defaults to "\n")
1445 max: Maximum times to split (optional)
1449 regex: Boolean indicating whether to interpret the separator
1450 pattern as regular expression (optional, default is false)
1460 <h3>Return value:</h3>
1461 Table containing the resulting substrings
1470 <dt><a name="strip_bytecode"></a><strong>strip_bytecode</strong> (code)</dt>
1474 Strips unnescessary lua bytecode from given string. Information like line
1476 numbers and debugging numbers will be discarded. Original version by
1477 Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
1484 code: String value containing the original lua byte code
1494 <h3>Return value:</h3>
1495 String value containing the stripped lua byte code
1504 <dt><a name="striptags"></a><strong>striptags</strong> (value)</dt>
1508 Strip HTML tags from given string.
1516 value: String containing the HTML text
1526 <h3>Return value:</h3>
1527 String with HTML tags stripped of
1536 <dt><a name="threadlocal"></a><strong>threadlocal</strong> ()</dt>
1540 Create a new or get an already existing thread local store associated with
1542 the current active coroutine. A thread local store is private a table object
1543 whose values can't be accessed from outside of the running coroutine.
1551 <h3>Return value:</h3>
1552 Table value representing the corresponding thread local store
1561 <dt><a name="trim"></a><strong>trim</strong> (str)</dt>
1565 Remove leading and trailing whitespace from given string value.
1573 str: String value containing whitespace padded data
1583 <h3>Return value:</h3>
1584 String value with leading and trailing space removed
1593 <dt><a name="ubus"></a><strong>ubus</strong> (object, method, values)</dt>
1605 object: String containing the ubus object to call
1609 method: String containing the ubus method to call
1613 values: Table containing the values to pass
1623 <h3>Return value:</h3>
1624 Table containin the ubus result
1633 <dt><a name="update"></a><strong>update</strong> (t, updates)</dt>
1637 Update values in given table with the values from the second given table.
1639 Both table are - in fact - merged together.
1646 t: Table which should be updated
1650 updates: Table containing the values to update
1660 <h3>Return value:</h3>
1670 <dt><a name="vspairs"></a><strong>vspairs</strong> (t)</dt>
1674 Return a key, value iterator for the given table.
1676 The table pairs are sorted by value.
1683 t: The table to iterate
1693 <h3>Return value:</h3>
1694 Function value containing the corresponding iterator
1707 </div> <!-- id="content" -->
1709 </div> <!-- id="main" -->
1712 <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
1713 </div> <!-- id="about" -->
1715 </div> <!-- id="container" -->