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.conditionals.html">luci.http.conditionals</a>
50 <a href="../modules/luci.http.date.html">luci.http.date</a>
54 <a href="../modules/luci.http.mime.html">luci.http.mime</a>
58 <a href="../modules/luci.i18n.html">luci.i18n</a>
62 <a href="../modules/luci.ip.html">luci.ip</a>
66 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
70 <a href="../modules/luci.json.html">luci.json</a>
74 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
78 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
82 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
86 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
90 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
94 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
98 <a href="../modules/luci.sys.html">luci.sys</a>
102 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
106 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
110 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
114 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
118 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
122 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
125 <li><strong>luci.util</strong></li>
128 <a href="../modules/nixio.html">nixio</a>
132 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
136 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
140 <a href="../modules/nixio.File.html">nixio.File</a>
144 <a href="../modules/nixio.README.html">nixio.README</a>
148 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
152 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
156 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
160 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
164 <a href="../modules/nixio.bin.html">nixio.bin</a>
168 <a href="../modules/nixio.bit.html">nixio.bit</a>
172 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
176 <a href="../modules/nixio.fs.html">nixio.fs</a>
191 </div><!-- id="navigation" -->
195 <h1>Class <code>luci.util</code></h1>
206 <table class="function_list">
209 <td class="name" nowrap><a href="#append">append</a> (src, ...)</td>
212 Appends numerically indexed tables or single objects to a given table.</td>
216 <td class="name" nowrap><a href="#bigendian">bigendian</a> ()</td>
219 Test whether the current system is operating in big endian mode.</td>
223 <td class="name" nowrap><a href="#class">class</a> (base)</td>
226 Create a Class object (Python-style object model).</td>
230 <td class="name" nowrap><a href="#clone">clone</a> (object, deep)</td>
233 Clones the given object and return it's copy.</td>
237 <td class="name" nowrap><a href="#cmatch">cmatch</a> (str, pattern)</td>
240 Count the occurrences of given substring in given string.</td>
244 <td class="name" nowrap><a href="#combine">combine</a> (tbl1, tbl2, ...)</td>
247 Combines two or more numerically indexed tables and single objects into one table.</td>
251 <td class="name" nowrap><a href="#contains">contains</a> (table, value)</td>
254 Checks whether the given table contains the given value.</td>
258 <td class="name" nowrap><a href="#copcall">copcall</a> (f, ...)</td>
261 This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
266 <td class="name" nowrap><a href="#coxpcall">coxpcall</a> (f, err, ...)</td>
269 This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
274 <td class="name" nowrap><a href="#dumptable">dumptable</a> (t, maxdepth)</td>
277 Recursively dumps a table to stdout, useful for testing and debugging.</td>
281 <td class="name" nowrap><a href="#exec">exec</a> (command)</td>
284 Execute given commandline and gather stdout.</td>
288 <td class="name" nowrap><a href="#execi">execi</a> (command)</td>
291 Return a line-buffered iterator over the output of given command.</td>
295 <td class="name" nowrap><a href="#get_bytecode">get_bytecode</a> (val)</td>
298 Return the current runtime bytecode of the given data.</td>
302 <td class="name" nowrap><a href="#imatch">imatch</a> (val)</td>
305 Return a matching iterator for the given value.</td>
309 <td class="name" nowrap><a href="#instanceof">instanceof</a> (object, class)</td>
312 Test whether the given object is an instance of the given class.</td>
316 <td class="name" nowrap><a href="#keys">keys</a> (t)</td>
319 Retrieve all keys of given associative table.</td>
323 <td class="name" nowrap><a href="#kspairs">kspairs</a> (t)</td>
326 Return a key, value iterator for the given table.</td>
330 <td class="name" nowrap><a href="#libpath">libpath</a> ()</td>
333 Returns the absolute path to LuCI base directory.</td>
337 <td class="name" nowrap><a href="#parse_units">parse_units</a> (ustr)</td>
340 Parse certain units from the given string and return the canonical integer
341 value or 0 if the unit is unknown.</td>
345 <td class="name" nowrap><a href="#pcdata">pcdata</a> (value)</td>
348 Create valid XML PCDATA from given string.</td>
352 <td class="name" nowrap><a href="#perror">perror</a> (obj)</td>
355 Write given object to stderr.</td>
359 <td class="name" nowrap><a href="#restore_data">restore_data</a> (str)</td>
362 Restore data previously serialized with serialize_data().</td>
366 <td class="name" nowrap><a href="#serialize_data">serialize_data</a> (val)</td>
369 Recursively serialize given data to lua code, suitable for restoring
370 with loadstring().</td>
374 <td class="name" nowrap><a href="#serialize_json">serialize_json</a> (data, writer)</td>
377 Convert data structure to JSON
382 <td class="name" nowrap><a href="#shellquote">shellquote</a> (value)</td>
385 Safely quote value for use in shell commands.</td>
389 <td class="name" nowrap><a href="#spairs">spairs</a> (t, f)</td>
392 Return a key, value iterator which returns the values sorted according to
393 the provided callback function.</td>
397 <td class="name" nowrap><a href="#split">split</a> (str, pat, max, regex)</td>
400 Splits given string on a defined separator sequence and return a table
401 containing the resulting substrings.</td>
405 <td class="name" nowrap><a href="#strip_bytecode">strip_bytecode</a> (code)</td>
408 Strips unnescessary lua bytecode from given string.</td>
412 <td class="name" nowrap><a href="#striptags">striptags</a> (value)</td>
415 Strip HTML tags from given string.</td>
419 <td class="name" nowrap><a href="#threadlocal">threadlocal</a> ()</td>
422 Create a new or get an already existing thread local store associated with
423 the current active coroutine.</td>
427 <td class="name" nowrap><a href="#trim">trim</a> (str)</td>
430 Remove leading and trailing whitespace from given string value.</td>
434 <td class="name" nowrap><a href="#ubus">ubus</a> (object, method, values)</td>
437 Issue an ubus call.</td>
441 <td class="name" nowrap><a href="#update">update</a> (t, updates)</td>
444 Update values in given table with the values from the second given table.</td>
448 <td class="name" nowrap><a href="#urldecode">urldecode</a> (str, decode_plus)</td>
451 Decode an URL-encoded string - optionally decoding the "+" sign to space.</td>
455 <td class="name" nowrap><a href="#urlencode">urlencode</a> (str)</td>
458 URL-encode given string.</td>
462 <td class="name" nowrap><a href="#vspairs">vspairs</a> (t)</td>
465 Return a key, value iterator for the given table.</td>
479 <h2><a name="functions"></a>Functions</h2>
480 <dl class="function">
484 <dt><a name="append"></a><strong>append</strong> (src, ...)</dt>
488 Appends numerically indexed tables or single objects to a given table.
500 ...: Objects to insert
510 <h3>Return value:</h3>
520 <dt><a name="bigendian"></a><strong>bigendian</strong> ()</dt>
524 Test whether the current system is operating in big endian mode.
533 <h3>Return value:</h3>
534 Boolean value indicating whether system is big endian
543 <dt><a name="class"></a><strong>class</strong> (base)</dt>
547 Create a Class object (Python-style object model).
549 The class object can be instantiated by calling itself.
550 Any class functions or shared parameters can be attached to this object.
551 Attaching a table to the class object makes this table shared between
552 all instances of this class. For object parameters use the __init__ function.
553 Classes can inherit member functions and values from a base class.
554 Class can be instantiated by calling them. All parameters will be passed
555 to the __init__ function of this class - if such a function exists.
556 The __init__ function must be used to set any object parameters that are not shared
557 with other objects of this class. Any return values will be ignored.
565 base: The base class to inherit from (optional)
575 <h3>Return value:</h3>
583 <li><a href="#instanceof">
587 <li><a href="#clone">
598 <dt><a name="clone"></a><strong>clone</strong> (object, deep)</dt>
602 Clones the given object and return it's copy.
610 object: Table value to clone
614 deep: Boolean indicating whether to do recursive cloning
624 <h3>Return value:</h3>
634 <dt><a name="cmatch"></a><strong>cmatch</strong> (str, pattern)</dt>
638 Count the occurrences of given substring in given string.
646 str: String to search in
650 pattern: String containing pattern to find
660 <h3>Return value:</h3>
661 Number of found occurrences
670 <dt><a name="combine"></a><strong>combine</strong> (tbl1, tbl2, ...)</dt>
674 Combines two or more numerically indexed tables and single objects into one table.
682 tbl1: Table value to combine
686 tbl2: Table value to combine
690 ...: More tables to combine
700 <h3>Return value:</h3>
701 Table value containing all values of given tables
710 <dt><a name="contains"></a><strong>contains</strong> (table, value)</dt>
714 Checks whether the given table contains the given value.
726 value: Value to search within the given table
736 <h3>Return value:</h3>
737 Number indicating the first index at which the given value occurs
738 within table or false.
747 <dt><a name="copcall"></a><strong>copcall</strong> (f, ...)</dt>
751 This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
759 f: Lua function to be called protected
763 ...: Parameters passed to the function
773 <h3>Return value:</h3>
774 A boolean whether the function call succeeded and the returns
775 values of the function or the error object
784 <dt><a name="coxpcall"></a><strong>coxpcall</strong> (f, err, ...)</dt>
788 This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
796 f: Lua function to be called protected
800 err: Custom error handler
804 ...: Parameters passed to the function
814 <h3>Return value:</h3>
815 A boolean whether the function call succeeded and the return
816 values of either the function or the error handler
825 <dt><a name="dumptable"></a><strong>dumptable</strong> (t, maxdepth)</dt>
829 Recursively dumps a table to stdout, useful for testing and debugging.
837 t: Table value to dump
841 maxdepth: Maximum depth
851 <h3>Return value:</h3>
861 <dt><a name="exec"></a><strong>exec</strong> (command)</dt>
865 Execute given commandline and gather stdout.
873 command: String containing command to execute
883 <h3>Return value:</h3>
884 String containing the command's stdout
893 <dt><a name="execi"></a><strong>execi</strong> (command)</dt>
897 Return a line-buffered iterator over the output of given command.
905 command: String containing the command to execute
915 <h3>Return value:</h3>
925 <dt><a name="get_bytecode"></a><strong>get_bytecode</strong> (val)</dt>
929 Return the current runtime bytecode of the given data. The byte code
930 will be stripped before it is returned.
938 val: Value to return as bytecode
948 <h3>Return value:</h3>
949 String value containing the bytecode of the given data
958 <dt><a name="imatch"></a><strong>imatch</strong> (val)</dt>
962 Return a matching iterator for the given value.
964 The iterator will return one token per invocation, the tokens are separated by
965 whitespace. If the input value is a table, it is transformed into a string first.
966 A nil value will result in a valid interator which aborts with the first invocation.
974 val: The value to scan (table, string or nil)
984 <h3>Return value:</h3>
985 Iterator which returns one token per call
994 <dt><a name="instanceof"></a><strong>instanceof</strong> (object, class)</dt>
998 Test whether the given object is an instance of the given class.
1006 object: Object instance
1010 class: Class object to test against
1020 <h3>Return value:</h3>
1021 Boolean indicating whether the object is an instance
1028 <li><a href="#class">
1032 <li><a href="#clone">
1043 <dt><a name="keys"></a><strong>keys</strong> (t)</dt>
1047 Retrieve all keys of given associative table.
1055 t: Table to extract keys from
1065 <h3>Return value:</h3>
1066 Sorted table containing the keys
1075 <dt><a name="kspairs"></a><strong>kspairs</strong> (t)</dt>
1079 Return a key, value iterator for the given table.
1081 The table pairs are sorted by key.
1089 t: The table to iterate
1099 <h3>Return value:</h3>
1100 Function value containing the corresponding iterator
1109 <dt><a name="libpath"></a><strong>libpath</strong> ()</dt>
1113 Returns the absolute path to LuCI base directory.
1122 <h3>Return value:</h3>
1123 String containing the directory path
1132 <dt><a name="parse_units"></a><strong>parse_units</strong> (ustr)</dt>
1136 Parse certain units from the given string and return the canonical integer
1137 value or 0 if the unit is unknown.
1139 Upper- or lower case is irrelevant.
1140 Recognized units are:
1142 o "y" - one year (60*60*24*366)
1143 o "m" - one month (60*60*24*31)
1144 o "w" - one week (60*60*24*7)
1145 o "d" - one day (60*60*24)
1146 o "h" - one hour (60*60)
1147 o "min" - one minute (60)
1148 o "kb" - one kilobyte (1024)
1149 o "mb" - one megabyte (1024*1024)
1150 o "gb" - one gigabyte (1024*1024*1024)
1151 o "kib" - one si kilobyte (1000)
1152 o "mib" - one si megabyte (1000*1000)
1153 o "gib" - one si gigabyte (1000*1000*1000)
1161 ustr: String containing a numerical value with trailing unit
1171 <h3>Return value:</h3>
1172 Number containing the canonical value
1181 <dt><a name="pcdata"></a><strong>pcdata</strong> (value)</dt>
1185 Create valid XML PCDATA from given string.
1193 value: String value containing the data to escape
1203 <h3>Return value:</h3>
1204 String value containing the escaped data
1213 <dt><a name="perror"></a><strong>perror</strong> (obj)</dt>
1217 Write given object to stderr.
1225 obj: Value to write to stderr
1235 <h3>Return value:</h3>
1236 Boolean indicating whether the write operation was successful
1245 <dt><a name="restore_data"></a><strong>restore_data</strong> (str)</dt>
1249 Restore data previously serialized with serialize_data().
1257 str: String containing the data to restore
1267 <h3>Return value:</h3>
1268 Value containing the restored data structure
1275 <li><a href="#serialize_data">
1279 <li><a href="#get_bytecode">
1290 <dt><a name="serialize_data"></a><strong>serialize_data</strong> (val)</dt>
1294 Recursively serialize given data to lua code, suitable for restoring
1303 val: Value containing the data to serialize
1313 <h3>Return value:</h3>
1314 String value containing the serialized code
1321 <li><a href="#restore_data">
1325 <li><a href="#get_bytecode">
1336 <dt><a name="serialize_json"></a><strong>serialize_json</strong> (data, writer)</dt>
1340 Convert data structure to JSON
1348 data: The data to serialize
1352 writer: A function to write a chunk of JSON data (optional)
1362 <h3>Return value:</h3>
1363 String containing the JSON if called without write callback
1372 <dt><a name="shellquote"></a><strong>shellquote</strong> (value)</dt>
1376 Safely quote value for use in shell commands.
1384 value: String containing the value to quote
1394 <h3>Return value:</h3>
1395 Single-quote enclosed string with embedded quotes escaped
1404 <dt><a name="spairs"></a><strong>spairs</strong> (t, f)</dt>
1408 Return a key, value iterator which returns the values sorted according to
1409 the provided callback function.
1417 t: The table to iterate
1421 f: A callback function to decide the order of elements
1431 <h3>Return value:</h3>
1432 Function value containing the corresponding iterator
1441 <dt><a name="split"></a><strong>split</strong> (str, pat, max, regex)</dt>
1445 Splits given string on a defined separator sequence and return a table
1446 containing the resulting substrings.
1448 The optional max parameter specifies the number of bytes to process,
1449 regardless of the actual length of the given string. The optional last
1450 parameter, regex, specifies whether the separator sequence is
1451 nterpreted as regular expression.
1459 str: String value containing the data to split up
1463 pat: String with separator pattern (optional, defaults to "\n")
1467 max: Maximum times to split (optional)
1471 regex: Boolean indicating whether to interpret the separator
1472 pattern as regular expression (optional, default is false)
1482 <h3>Return value:</h3>
1483 Table containing the resulting substrings
1492 <dt><a name="strip_bytecode"></a><strong>strip_bytecode</strong> (code)</dt>
1496 Strips unnescessary lua bytecode from given string.
1498 Information like line numbers and debugging numbers will be discarded.
1499 Original version by Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
1507 code: String value containing the original lua byte code
1517 <h3>Return value:</h3>
1518 String value containing the stripped lua byte code
1527 <dt><a name="striptags"></a><strong>striptags</strong> (value)</dt>
1531 Strip HTML tags from given string.
1539 value: String containing the HTML text
1549 <h3>Return value:</h3>
1550 String with HTML tags stripped of
1559 <dt><a name="threadlocal"></a><strong>threadlocal</strong> ()</dt>
1563 Create a new or get an already existing thread local store associated with
1564 the current active coroutine.
1566 A thread local store is private a table object
1567 whose values can't be accessed from outside of the running coroutine.
1576 <h3>Return value:</h3>
1577 Table value representing the corresponding thread local store
1586 <dt><a name="trim"></a><strong>trim</strong> (str)</dt>
1590 Remove leading and trailing whitespace from given string value.
1598 str: String value containing whitespace padded data
1608 <h3>Return value:</h3>
1609 String value with leading and trailing space removed
1618 <dt><a name="ubus"></a><strong>ubus</strong> (object, method, values)</dt>
1630 object: String containing the ubus object to call
1634 method: String containing the ubus method to call
1638 values: Table containing the values to pass
1648 <h3>Return value:</h3>
1649 Table containin the ubus result
1658 <dt><a name="update"></a><strong>update</strong> (t, updates)</dt>
1662 Update values in given table with the values from the second given table.
1664 Both table are - in fact - merged together.
1672 t: Table which should be updated
1676 updates: Table containing the values to update
1686 <h3>Return value:</h3>
1696 <dt><a name="urldecode"></a><strong>urldecode</strong> (str, decode_plus)</dt>
1700 Decode an URL-encoded string - optionally decoding the "+" sign to space.
1708 str: Input string in x-www-urlencoded format
1712 decode_plus: Decode "+" signs to spaces if true (optional)
1722 <h3>Return value:</h3>
1730 <li><a href="#urlencode">
1741 <dt><a name="urlencode"></a><strong>urlencode</strong> (str)</dt>
1745 URL-encode given string.
1753 str: String to encode
1763 <h3>Return value:</h3>
1764 String containing the encoded data
1771 <li><a href="#urldecode">
1782 <dt><a name="vspairs"></a><strong>vspairs</strong> (t)</dt>
1786 Return a key, value iterator for the given table.
1788 The table pairs are sorted by value.
1796 t: The table to iterate
1806 <h3>Return value:</h3>
1807 Function value containing the corresponding iterator
1820 </div> <!-- id="content" -->
1822 </div> <!-- id="main" -->
1825 <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>
1826 </div> <!-- id="about" -->
1828 </div> <!-- id="container" -->