docs/api/modules/luci.util.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html>
   4 <head>
   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"/-->
   8 </head>
   9
  10 <body>
  11 <div id="container">
  12
  13 <div id="product">
  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" -->
  18
  19 <div id="main">
  20
  21 <div id="navigation">
  22
  23
  24 <h1>LuaDoc</h1>
  25 <ul>
  26
  27         <li><a href="../index.html">Index</a></li>
  28
  29 </ul>
  30
  31
  32 <!-- Module list -->
  33
  34 <h1>Modules</h1>
  35 <ul>
  36
  37         <li>
  38                 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
  39         </li>
  40
  41         <li>
  42                 <a href="../modules/luci.http.html">luci.http</a>
  43         </li>
  44
  45         <li>
  46                 <a href="../modules/luci.http.conditionals.html">luci.http.conditionals</a>
  47         </li>
  48
  49         <li>
  50                 <a href="../modules/luci.http.date.html">luci.http.date</a>
  51         </li>
  52
  53         <li>
  54                 <a href="../modules/luci.http.mime.html">luci.http.mime</a>
  55         </li>
  56
  57         <li>
  58                 <a href="../modules/luci.i18n.html">luci.i18n</a>
  59         </li>
  60
  61         <li>
  62                 <a href="../modules/luci.ip.html">luci.ip</a>
  63         </li>
  64
  65         <li>
  66                 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
  67         </li>
  68
  69         <li>
  70                 <a href="../modules/luci.json.html">luci.json</a>
  71         </li>
  72
  73         <li>
  74                 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
  75         </li>
  76
  77         <li>
  78                 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
  79         </li>
  80
  81         <li>
  82                 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
  83         </li>
  84
  85         <li>
  86                 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
  87         </li>
  88
  89         <li>
  90                 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
  91         </li>
  92
  93         <li>
  94                 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
  95         </li>
  96
  97         <li>
  98                 <a href="../modules/luci.sys.html">luci.sys</a>
  99         </li>
 100
 101         <li>
 102                 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
 103         </li>
 104
 105         <li>
 106                 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
 107         </li>
 108
 109         <li>
 110                 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
 111         </li>
 112
 113         <li>
 114                 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
 115         </li>
 116
 117         <li>
 118                 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
 119         </li>
 120
 121         <li>
 122                 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
 123         </li>
 124
 125         <li><strong>luci.util</strong></li>
 126
 127         <li>
 128                 <a href="../modules/luci.xml.html">luci.xml</a>
 129         </li>
 130
 131         <li>
 132                 <a href="../modules/nixio.html">nixio</a>
 133         </li>
 134
 135         <li>
 136                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
 137         </li>
 138
 139         <li>
 140                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
 141         </li>
 142
 143         <li>
 144                 <a href="../modules/nixio.File.html">nixio.File</a>
 145         </li>
 146
 147         <li>
 148                 <a href="../modules/nixio.README.html">nixio.README</a>
 149         </li>
 150
 151         <li>
 152                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
 153         </li>
 154
 155         <li>
 156                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
 157         </li>
 158
 159         <li>
 160                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
 161         </li>
 162
 163         <li>
 164                 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
 165         </li>
 166
 167         <li>
 168                 <a href="../modules/nixio.bin.html">nixio.bin</a>
 169         </li>
 170
 171         <li>
 172                 <a href="../modules/nixio.bit.html">nixio.bit</a>
 173         </li>
 174
 175         <li>
 176                 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
 177         </li>
 178
 179         <li>
 180                 <a href="../modules/nixio.fs.html">nixio.fs</a>
 181         </li>
 182
 183 </ul>
 184
 185
 186
 187 <!-- File list -->
 188
 189
 190
 191
 192
 193
 194
 195 </div><!-- id="navigation" -->
 196
 197 <div id="content">
 198
 199 <h1>Class <code>luci.util</code></h1>
 200
 201 <p></p>
 202
 203
 204
 205
 206
 207
 208
 209 <h2>Functions</h2>
 210 <table class="function_list">
 211
 212         <tr>
 213         <td class="name" nowrap><a href="#append">append</a>&nbsp;(src, ...)</td>
 214         <td class="summary">
 215
 216 Appends numerically indexed tables or single objects to a given table.</td>
 217         </tr>
 218
 219         <tr>
 220         <td class="name" nowrap><a href="#bigendian">bigendian</a>&nbsp;()</td>
 221         <td class="summary">
 222
 223 Test whether the current system is operating in big endian mode.</td>
 224         </tr>
 225
 226         <tr>
 227         <td class="name" nowrap><a href="#class">class</a>&nbsp;(base)</td>
 228         <td class="summary">
 229
 230 Create a Class object (Python-style object model).</td>
 231         </tr>
 232
 233         <tr>
 234         <td class="name" nowrap><a href="#clone">clone</a>&nbsp;(object, deep)</td>
 235         <td class="summary">
 236
 237 Clones the given object and return it's copy.</td>
 238         </tr>
 239
 240         <tr>
 241         <td class="name" nowrap><a href="#cmatch">cmatch</a>&nbsp;(str, pattern)</td>
 242         <td class="summary">
 243
 244 Count the occurrences of given substring in given string.</td>
 245         </tr>
 246
 247         <tr>
 248         <td class="name" nowrap><a href="#combine">combine</a>&nbsp;(tbl1, tbl2, ...)</td>
 249         <td class="summary">
 250
 251 Combines two or more numerically indexed tables and single objects into one table.</td>
 252         </tr>
 253
 254         <tr>
 255         <td class="name" nowrap><a href="#contains">contains</a>&nbsp;(table, value)</td>
 256         <td class="summary">
 257
 258 Checks whether the given table contains the given value.</td>
 259         </tr>
 260
 261         <tr>
 262         <td class="name" nowrap><a href="#copcall">copcall</a>&nbsp;(f, ...)</td>
 263         <td class="summary">
 264
 265 This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
 266  </td>
 267         </tr>
 268
 269         <tr>
 270         <td class="name" nowrap><a href="#coxpcall">coxpcall</a>&nbsp;(f, err, ...)</td>
 271         <td class="summary">
 272
 273 This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
 274  </td>
 275         </tr>
 276
 277         <tr>
 278         <td class="name" nowrap><a href="#dumptable">dumptable</a>&nbsp;(t, maxdepth)</td>
 279         <td class="summary">
 280
 281 Recursively dumps a table to stdout, useful for testing and debugging.</td>
 282         </tr>
 283
 284         <tr>
 285         <td class="name" nowrap><a href="#exec">exec</a>&nbsp;(command)</td>
 286         <td class="summary">
 287
 288 Execute given commandline and gather stdout.</td>
 289         </tr>
 290
 291         <tr>
 292         <td class="name" nowrap><a href="#execi">execi</a>&nbsp;(command)</td>
 293         <td class="summary">
 294
 295 Return a line-buffered iterator over the output of given command.</td>
 296         </tr>
 297
 298         <tr>
 299         <td class="name" nowrap><a href="#get_bytecode">get_bytecode</a>&nbsp;(val)</td>
 300         <td class="summary">
 301
 302 Return the current runtime bytecode of the given data.</td>
 303         </tr>
 304
 305         <tr>
 306         <td class="name" nowrap><a href="#imatch">imatch</a>&nbsp;(val)</td>
 307         <td class="summary">
 308
 309 Return a matching iterator for the given value.</td>
 310         </tr>
 311
 312         <tr>
 313         <td class="name" nowrap><a href="#instanceof">instanceof</a>&nbsp;(object, class)</td>
 314         <td class="summary">
 315
 316 Test whether the given object is an instance of the given class.</td>
 317         </tr>
 318
 319         <tr>
 320         <td class="name" nowrap><a href="#keys">keys</a>&nbsp;(t)</td>
 321         <td class="summary">
 322
 323 Retrieve all keys of given associative table.</td>
 324         </tr>
 325
 326         <tr>
 327         <td class="name" nowrap><a href="#kspairs">kspairs</a>&nbsp;(t)</td>
 328         <td class="summary">
 329
 330 Return a key, value iterator for the given table.</td>
 331         </tr>
 332
 333         <tr>
 334         <td class="name" nowrap><a href="#libpath">libpath</a>&nbsp;()</td>
 335         <td class="summary">
 336
 337 Returns the absolute path to LuCI base directory.</td>
 338         </tr>
 339
 340         <tr>
 341         <td class="name" nowrap><a href="#parse_units">parse_units</a>&nbsp;(ustr)</td>
 342         <td class="summary">
 343
 344 Parse certain units from the given string and return the canonical integer
 345 value or 0 if the unit is unknown.</td>
 346         </tr>
 347
 348         <tr>
 349         <td class="name" nowrap><a href="luci.xml.html#pcdata">pcdata</a>&nbsp;(value)</td>
 350         <td class="summary">
 351
 352 Create valid XML PCDATA from given string.
 353 This is a wrapper for <a href="luci.xml.html#pcdata">luci.xml.pcdata()</a>.</td>
 354         </tr>
 355
 356         <tr>
 357         <td class="name" nowrap><a href="#perror">perror</a>&nbsp;(obj)</td>
 358         <td class="summary">
 359
 360 Write given object to stderr.</td>
 361         </tr>
 362
 363         <tr>
 364         <td class="name" nowrap><a href="#restore_data">restore_data</a>&nbsp;(str)</td>
 365         <td class="summary">
 366
 367 Restore data previously serialized with serialize_data().</td>
 368         </tr>
 369
 370         <tr>
 371         <td class="name" nowrap><a href="#serialize_data">serialize_data</a>&nbsp;(val)</td>
 372         <td class="summary">
 373
 374 Recursively serialize given data to lua code, suitable for restoring
 375 with loadstring().</td>
 376         </tr>
 377
 378         <tr>
 379         <td class="name" nowrap><a href="#serialize_json">serialize_json</a>&nbsp;(data, writer)</td>
 380         <td class="summary">
 381
 382 Convert data structure to JSON
 383  </td>
 384         </tr>
 385
 386         <tr>
 387         <td class="name" nowrap><a href="#shellquote">shellquote</a>&nbsp;(value)</td>
 388         <td class="summary">
 389
 390 Safely quote value for use in shell commands.</td>
 391         </tr>
 392
 393         <tr>
 394         <td class="name" nowrap><a href="#spairs">spairs</a>&nbsp;(t, f)</td>
 395         <td class="summary">
 396
 397 Return a key, value iterator which returns the values sorted according to
 398 the provided callback function.</td>
 399         </tr>
 400
 401         <tr>
 402         <td class="name" nowrap><a href="#split">split</a>&nbsp;(str, pat, max, regex)</td>
 403         <td class="summary">
 404
 405 Splits given string on a defined separator sequence and return a table
 406 containing the resulting substrings.</td>
 407         </tr>
 408
 409         <tr>
 410         <td class="name" nowrap><a href="#strip_bytecode">strip_bytecode</a>&nbsp;(code)</td>
 411         <td class="summary">
 412
 413 Strips unnecessary lua bytecode from given string.</td>
 414         </tr>
 415
 416         <tr>
 417         <td class="name" nowrap><a href="luci.xml.html#striptags">striptags</a>&nbsp;(value)</td>
 418         <td class="summary">
 419
 420 Strip HTML tags from given string.
 421 This is a wrapper for <a href="luci.xml.html#striptags">luci.xml.striptags()</a>.</td>
 422         </tr>
 423
 424         <tr>
 425         <td class="name" nowrap><a href="#threadlocal">threadlocal</a>&nbsp;()</td>
 426         <td class="summary">
 427
 428 Create a new or get an already existing thread local store associated with
 429 the current active coroutine.</td>
 430         </tr>
 431
 432         <tr>
 433         <td class="name" nowrap><a href="#trim">trim</a>&nbsp;(str)</td>
 434         <td class="summary">
 435
 436 Remove leading and trailing whitespace from given string value.</td>
 437         </tr>
 438
 439         <tr>
 440         <td class="name" nowrap><a href="#ubus">ubus</a>&nbsp;(object, method, values)</td>
 441         <td class="summary">
 442
 443 Issue an ubus call.</td>
 444         </tr>
 445
 446         <tr>
 447         <td class="name" nowrap><a href="#update">update</a>&nbsp;(t, updates)</td>
 448         <td class="summary">
 449
 450 Update values in given table with the values from the second given table.</td>
 451         </tr>
 452
 453         <tr>
 454         <td class="name" nowrap><a href="#urldecode">urldecode</a>&nbsp;(str, decode_plus)</td>
 455         <td class="summary">
 456
 457 Decode an URL-encoded string - optionally decoding the "+" sign to space.</td>
 458         </tr>
 459
 460         <tr>
 461         <td class="name" nowrap><a href="#urlencode">urlencode</a>&nbsp;(str)</td>
 462         <td class="summary">
 463
 464 URL-encode given string.</td>
 465         </tr>
 466
 467         <tr>
 468         <td class="name" nowrap><a href="#vspairs">vspairs</a>&nbsp;(t)</td>
 469         <td class="summary">
 470
 471 Return a key, value iterator for the given table.</td>
 472         </tr>
 473
 474 </table>
 475
 476
 477
 478
 479
 480
 481 <br/>
 482 <br/>
 483
 484
 485 <h2><a name="functions"></a>Functions</h2>
 486 <dl class="function">
 487
 488
 489
 490 <dt><a name="append"></a><strong>append</strong>&nbsp;(src, ...)</dt>
 491 <dd>
 492
 493
 494 Appends numerically indexed tables or single objects to a given table.
 495
 496
 497
 498 <h3>Parameters</h3>
 499 <ul>
 500
 501         <li>
 502           src: Target table
 503         </li>
 504
 505         <li>
 506           ...: Objects to insert
 507         </li>
 508
 509 </ul>
 510
 511
 512
 513
 514
 515
 516 <h3>Return value:</h3>
 517 Target table
 518
 519
 520
 521 </dd>
 522
 523
 524
 525
 526 <dt><a name="bigendian"></a><strong>bigendian</strong>&nbsp;()</dt>
 527 <dd>
 528
 529
 530 Test whether the current system is operating in big endian mode.
 531
 532
 533
 534
 535
 536
 537
 538
 539 <h3>Return value:</h3>
 540 Boolean value indicating whether system is big endian
 541
 542
 543
 544 </dd>
 545
 546
 547
 548
 549 <dt><a name="class"></a><strong>class</strong>&nbsp;(base)</dt>
 550 <dd>
 551
 552
 553 Create a Class object (Python-style object model).
 554
 555 The class object can be instantiated by calling itself.
 556 Any class functions or shared parameters can be attached to this object.
 557 Attaching a table to the class object makes this table shared between
 558 all instances of this class. For object parameters use the __init__ function.
 559 Classes can inherit member functions and values from a base class.
 560 Class can be instantiated by calling them. All parameters will be passed
 561 to the __init__ function of this class - if such a function exists.
 562 The __init__ function must be used to set any object parameters that are not shared
 563 with other objects of this class. Any return values will be ignored.
 564
 565
 566
 567 <h3>Parameters</h3>
 568 <ul>
 569
 570         <li>
 571           base: The base class to inherit from (optional)
 572         </li>
 573
 574 </ul>
 575
 576
 577
 578
 579
 580
 581 <h3>Return value:</h3>
 582 A class object
 583
 584
 585
 586 <h3>See also:</h3>
 587 <ul>
 588
 589         <li><a href="#instanceof">
 590                 instanceof
 591         </a>
 592
 593         <li><a href="#clone">
 594                 clone
 595         </a>
 596
 597 </ul>
 598
 599 </dd>
 600
 601
 602
 603
 604 <dt><a name="clone"></a><strong>clone</strong>&nbsp;(object, deep)</dt>
 605 <dd>
 606
 607
 608 Clones the given object and return it's copy.
 609
 610
 611
 612 <h3>Parameters</h3>
 613 <ul>
 614
 615         <li>
 616           object: Table value to clone
 617         </li>
 618
 619         <li>
 620           deep: Boolean indicating whether to do recursive cloning
 621         </li>
 622
 623 </ul>
 624
 625
 626
 627
 628
 629
 630 <h3>Return value:</h3>
 631 Cloned table value
 632
 633
 634
 635 </dd>
 636
 637
 638
 639
 640 <dt><a name="cmatch"></a><strong>cmatch</strong>&nbsp;(str, pattern)</dt>
 641 <dd>
 642
 643
 644 Count the occurrences of given substring in given string.
 645
 646
 647
 648 <h3>Parameters</h3>
 649 <ul>
 650
 651         <li>
 652           str: String to search in
 653         </li>
 654
 655         <li>
 656           pattern: String containing pattern to find
 657         </li>
 658
 659 </ul>
 660
 661
 662
 663
 664
 665
 666 <h3>Return value:</h3>
 667 Number of found occurrences
 668
 669
 670
 671 </dd>
 672
 673
 674
 675
 676 <dt><a name="combine"></a><strong>combine</strong>&nbsp;(tbl1, tbl2, ...)</dt>
 677 <dd>
 678
 679
 680 Combines two or more numerically indexed tables and single objects into one table.
 681
 682
 683
 684 <h3>Parameters</h3>
 685 <ul>
 686
 687         <li>
 688           tbl1: Table value to combine
 689         </li>
 690
 691         <li>
 692           tbl2: Table value to combine
 693         </li>
 694
 695         <li>
 696           ...: More tables to combine
 697         </li>
 698
 699 </ul>
 700
 701
 702
 703
 704
 705
 706 <h3>Return value:</h3>
 707 Table value containing all values of given tables
 708
 709
 710
 711 </dd>
 712
 713
 714
 715
 716 <dt><a name="contains"></a><strong>contains</strong>&nbsp;(table, value)</dt>
 717 <dd>
 718
 719
 720 Checks whether the given table contains the given value.
 721
 722
 723
 724 <h3>Parameters</h3>
 725 <ul>
 726
 727         <li>
 728           table: Table value
 729         </li>
 730
 731         <li>
 732           value: Value to search within the given table
 733         </li>
 734
 735 </ul>
 736
 737
 738
 739
 740
 741
 742 <h3>Return value:</h3>
 743 Number indicating the first index at which the given value occurs
 744                                         within table or false.
 745
 746
 747
 748 </dd>
 749
 750
 751
 752
 753 <dt><a name="copcall"></a><strong>copcall</strong>&nbsp;(f, ...)</dt>
 754 <dd>
 755
 756
 757 This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
 758
 759
 760
 761 <h3>Parameters</h3>
 762 <ul>
 763
 764         <li>
 765           f: Lua function to be called protected
 766         </li>
 767
 768         <li>
 769           ...: Parameters passed to the function
 770         </li>
 771
 772 </ul>
 773
 774
 775
 776
 777
 778
 779 <h3>Return value:</h3>
 780 A boolean whether the function call succeeded and the returns
 781                                         values of the function or the error object
 782
 783
 784
 785 </dd>
 786
 787
 788
 789
 790 <dt><a name="coxpcall"></a><strong>coxpcall</strong>&nbsp;(f, err, ...)</dt>
 791 <dd>
 792
 793
 794 This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
 795
 796
 797
 798 <h3>Parameters</h3>
 799 <ul>
 800
 801         <li>
 802           f: Lua function to be called protected
 803         </li>
 804
 805         <li>
 806           err: Custom error handler
 807         </li>
 808
 809         <li>
 810           ...: Parameters passed to the function
 811         </li>
 812
 813 </ul>
 814
 815
 816
 817
 818
 819
 820 <h3>Return value:</h3>
 821 A boolean whether the function call succeeded and the return
 822                                         values of either the function or the error handler
 823
 824
 825
 826 </dd>
 827
 828
 829
 830
 831 <dt><a name="dumptable"></a><strong>dumptable</strong>&nbsp;(t, maxdepth)</dt>
 832 <dd>
 833
 834
 835 Recursively dumps a table to stdout, useful for testing and debugging.
 836
 837
 838
 839 <h3>Parameters</h3>
 840 <ul>
 841
 842         <li>
 843           t: Table value to dump
 844         </li>
 845
 846         <li>
 847           maxdepth: Maximum depth
 848         </li>
 849
 850 </ul>
 851
 852
 853
 854
 855
 856
 857 <h3>Return value:</h3>
 858 Always nil
 859
 860
 861
 862 </dd>
 863
 864
 865
 866
 867 <dt><a name="exec"></a><strong>exec</strong>&nbsp;(command)</dt>
 868 <dd>
 869
 870
 871 Execute given commandline and gather stdout.
 872
 873
 874
 875 <h3>Parameters</h3>
 876 <ul>
 877
 878         <li>
 879           command: String containing command to execute
 880         </li>
 881
 882 </ul>
 883
 884
 885
 886
 887
 888
 889 <h3>Return value:</h3>
 890 String containing the command's stdout
 891
 892
 893
 894 </dd>
 895
 896
 897
 898
 899 <dt><a name="execi"></a><strong>execi</strong>&nbsp;(command)</dt>
 900 <dd>
 901
 902
 903 Return a line-buffered iterator over the output of given command.
 904
 905
 906
 907 <h3>Parameters</h3>
 908 <ul>
 909
 910         <li>
 911           command: String containing the command to execute
 912         </li>
 913
 914 </ul>
 915
 916
 917
 918
 919
 920
 921 <h3>Return value:</h3>
 922 Iterator
 923
 924
 925
 926 </dd>
 927
 928
 929
 930
 931 <dt><a name="get_bytecode"></a><strong>get_bytecode</strong>&nbsp;(val)</dt>
 932 <dd>
 933
 934
 935 Return the current runtime bytecode of the given data. The byte code
 936 will be stripped before it is returned.
 937
 938
 939
 940 <h3>Parameters</h3>
 941 <ul>
 942
 943         <li>
 944           val: Value to return as bytecode
 945         </li>
 946
 947 </ul>
 948
 949
 950
 951
 952
 953
 954 <h3>Return value:</h3>
 955 String value containing the bytecode of the given data
 956
 957
 958
 959 </dd>
 960
 961
 962
 963
 964 <dt><a name="imatch"></a><strong>imatch</strong>&nbsp;(val)</dt>
 965 <dd>
 966
 967
 968 Return a matching iterator for the given value.
 969
 970 The iterator will return one token per invocation, the tokens are separated by
 971 whitespace. If the input value is a table, it is transformed into a string first.
 972 A nil value will result in a valid iterator which aborts with the first invocation.
 973
 974
 975
 976 <h3>Parameters</h3>
 977 <ul>
 978
 979         <li>
 980           val: The value to scan (table, string or nil)
 981         </li>
 982
 983 </ul>
 984
 985
 986
 987
 988
 989
 990 <h3>Return value:</h3>
 991 Iterator which returns one token per call
 992
 993
 994
 995 </dd>
 996
 997
 998
 999
1000 <dt><a name="instanceof"></a><strong>instanceof</strong>&nbsp;(object, class)</dt>
1001 <dd>
1002
1003
1004 Test whether the given object is an instance of the given class.
1005
1006
1007
1008 <h3>Parameters</h3>
1009 <ul>
1010
1011         <li>
1012           object: Object instance
1013         </li>
1014
1015         <li>
1016           class: Class object to test against
1017         </li>
1018
1019 </ul>
1020
1021
1022
1023
1024
1025
1026 <h3>Return value:</h3>
1027 Boolean indicating whether the object is an instance
1028
1029
1030
1031 <h3>See also:</h3>
1032 <ul>
1033
1034         <li><a href="#class">
1035                 class
1036         </a>
1037
1038         <li><a href="#clone">
1039                 clone
1040         </a>
1041
1042 </ul>
1043
1044 </dd>
1045
1046
1047
1048
1049 <dt><a name="keys"></a><strong>keys</strong>&nbsp;(t)</dt>
1050 <dd>
1051
1052
1053 Retrieve all keys of given associative table.
1054
1055
1056
1057 <h3>Parameters</h3>
1058 <ul>
1059
1060         <li>
1061           t: Table to extract keys from
1062         </li>
1063
1064 </ul>
1065
1066
1067
1068
1069
1070
1071 <h3>Return value:</h3>
1072 Sorted table containing the keys
1073
1074
1075
1076 </dd>
1077
1078
1079
1080
1081 <dt><a name="kspairs"></a><strong>kspairs</strong>&nbsp;(t)</dt>
1082 <dd>
1083
1084
1085 Return a key, value iterator for the given table.
1086
1087 The table pairs are sorted by key.
1088
1089
1090
1091 <h3>Parameters</h3>
1092 <ul>
1093
1094         <li>
1095           t: The table to iterate
1096         </li>
1097
1098 </ul>
1099
1100
1101
1102
1103
1104
1105 <h3>Return value:</h3>
1106 Function value containing the corresponding iterator
1107
1108
1109
1110 </dd>
1111
1112
1113
1114
1115 <dt><a name="libpath"></a><strong>libpath</strong>&nbsp;()</dt>
1116 <dd>
1117
1118
1119 Returns the absolute path to LuCI base directory.
1120
1121
1122
1123
1124
1125
1126
1127
1128 <h3>Return value:</h3>
1129 String containing the directory path
1130
1131
1132
1133 </dd>
1134
1135
1136
1137
1138 <dt><a name="parse_units"></a><strong>parse_units</strong>&nbsp;(ustr)</dt>
1139 <dd>
1140
1141
1142 Parse certain units from the given string and return the canonical integer
1143 value or 0 if the unit is unknown.
1144
1145 Upper- or lower case is irrelevant.
1146 Recognized units are:
1147
1148         o "y"   - one year   (60*60*24*366)
1149  o "m"  - one month  (60*60*24*31)
1150  o "w"  - one week   (60*60*24*7)
1151  o "d"  - one day    (60*60*24)
1152  o "h"  - one hour       (60*60)
1153  o "min"        - one minute (60)
1154  o "kb"  - one kilobyte (1024)
1155  o "mb" - one megabyte (1024*1024)
1156  o "gb" - one gigabyte (1024*1024*1024)
1157  o "kib" - one si kilobyte (1000)
1158  o "mib"        - one si megabyte (1000*1000)
1159  o "gib"        - one si gigabyte (1000*1000*1000)
1160
1161
1162
1163 <h3>Parameters</h3>
1164 <ul>
1165
1166         <li>
1167           ustr: String containing a numerical value with trailing unit
1168         </li>
1169
1170 </ul>
1171
1172
1173
1174
1175
1176
1177 <h3>Return value:</h3>
1178 Number containing the canonical value
1179
1180
1181
1182 </dd>
1183
1184
1185
1186
1187 <dt><a name="perror"></a><strong>perror</strong>&nbsp;(obj)</dt>
1188 <dd>
1189
1190
1191 Write given object to stderr.
1192
1193
1194
1195 <h3>Parameters</h3>
1196 <ul>
1197
1198         <li>
1199           obj: Value to write to stderr
1200         </li>
1201
1202 </ul>
1203
1204
1205
1206
1207
1208
1209 <h3>Return value:</h3>
1210 Boolean indicating whether the write operation was successful
1211
1212
1213
1214 </dd>
1215
1216
1217
1218
1219 <dt><a name="restore_data"></a><strong>restore_data</strong>&nbsp;(str)</dt>
1220 <dd>
1221
1222
1223 Restore data previously serialized with serialize_data().
1224
1225
1226
1227 <h3>Parameters</h3>
1228 <ul>
1229
1230         <li>
1231           str: String containing the data to restore
1232         </li>
1233
1234 </ul>
1235
1236
1237
1238
1239
1240
1241 <h3>Return value:</h3>
1242 Value containing the restored data structure
1243
1244
1245
1246 <h3>See also:</h3>
1247 <ul>
1248
1249         <li><a href="#serialize_data">
1250                 serialize_data
1251         </a>
1252
1253         <li><a href="#get_bytecode">
1254                 get_bytecode
1255         </a>
1256
1257 </ul>
1258
1259 </dd>
1260
1261
1262
1263
1264 <dt><a name="serialize_data"></a><strong>serialize_data</strong>&nbsp;(val)</dt>
1265 <dd>
1266
1267
1268 Recursively serialize given data to lua code, suitable for restoring
1269 with loadstring().
1270
1271
1272
1273 <h3>Parameters</h3>
1274 <ul>
1275
1276         <li>
1277           val: Value containing the data to serialize
1278         </li>
1279
1280 </ul>
1281
1282
1283
1284
1285
1286
1287 <h3>Return value:</h3>
1288 String value containing the serialized code
1289
1290
1291
1292 <h3>See also:</h3>
1293 <ul>
1294
1295         <li><a href="#restore_data">
1296                 restore_data
1297         </a>
1298
1299         <li><a href="#get_bytecode">
1300                 get_bytecode
1301         </a>
1302
1303 </ul>
1304
1305 </dd>
1306
1307
1308
1309
1310 <dt><a name="serialize_json"></a><strong>serialize_json</strong>&nbsp;(data, writer)</dt>
1311 <dd>
1312
1313
1314 Convert data structure to JSON
1315
1316
1317
1318 <h3>Parameters</h3>
1319 <ul>
1320
1321         <li>
1322           data: The data to serialize
1323         </li>
1324
1325         <li>
1326           writer: A function to write a chunk of JSON data (optional)
1327         </li>
1328
1329 </ul>
1330
1331
1332
1333
1334
1335
1336 <h3>Return value:</h3>
1337 String containing the JSON if called without write callback
1338
1339
1340
1341 </dd>
1342
1343
1344
1345
1346 <dt><a name="shellquote"></a><strong>shellquote</strong>&nbsp;(value)</dt>
1347 <dd>
1348
1349
1350 Safely quote value for use in shell commands.
1351
1352
1353
1354 <h3>Parameters</h3>
1355 <ul>
1356
1357         <li>
1358           value: String containing the value to quote
1359         </li>
1360
1361 </ul>
1362
1363
1364
1365
1366
1367
1368 <h3>Return value:</h3>
1369 Single-quote enclosed string with embedded quotes escaped
1370
1371
1372
1373 </dd>
1374
1375
1376
1377
1378 <dt><a name="spairs"></a><strong>spairs</strong>&nbsp;(t, f)</dt>
1379 <dd>
1380
1381
1382 Return a key, value iterator which returns the values sorted according to
1383 the provided callback function.
1384
1385
1386
1387 <h3>Parameters</h3>
1388 <ul>
1389
1390         <li>
1391           t: The table to iterate
1392         </li>
1393
1394         <li>
1395           f: A callback function to decide the order of elements
1396         </li>
1397
1398 </ul>
1399
1400
1401
1402
1403
1404
1405 <h3>Return value:</h3>
1406 Function value containing the corresponding iterator
1407
1408
1409
1410 </dd>
1411
1412
1413
1414
1415 <dt><a name="split"></a><strong>split</strong>&nbsp;(str, pat, max, regex)</dt>
1416 <dd>
1417
1418
1419 Splits given string on a defined separator sequence and return a table
1420 containing the resulting substrings.
1421
1422 The optional max parameter specifies the number of bytes to process,
1423 regardless of the actual length of the given string. The optional last
1424 parameter, regex, specifies whether the separator sequence is
1425 nterpreted as regular expression.
1426
1427
1428
1429 <h3>Parameters</h3>
1430 <ul>
1431
1432         <li>
1433           str: String value containing the data to split up
1434         </li>
1435
1436         <li>
1437           pat: String with separator pattern (optional, defaults to "\n")
1438         </li>
1439
1440         <li>
1441           max: Maximum times to split (optional)
1442         </li>
1443
1444         <li>
1445           regex: Boolean indicating whether to interpret the separator
1446                                         pattern as regular expression (optional, default is false)
1447         </li>
1448
1449 </ul>
1450
1451
1452
1453
1454
1455
1456 <h3>Return value:</h3>
1457 Table containing the resulting substrings
1458
1459
1460
1461 </dd>
1462
1463
1464
1465
1466 <dt><a name="strip_bytecode"></a><strong>strip_bytecode</strong>&nbsp;(code)</dt>
1467 <dd>
1468
1469
1470 Strips unnecessary lua bytecode from given string.
1471
1472 Information like line numbers and debugging numbers will be discarded.
1473 Original version by Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
1474
1475
1476
1477 <h3>Parameters</h3>
1478 <ul>
1479
1480         <li>
1481           code: String value containing the original lua byte code
1482         </li>
1483
1484 </ul>
1485
1486
1487
1488
1489
1490
1491 <h3>Return value:</h3>
1492 String value containing the stripped lua byte code
1493
1494
1495
1496 </dd>
1497
1498
1499
1500
1501 <dt><a name="threadlocal"></a><strong>threadlocal</strong>&nbsp;()</dt>
1502 <dd>
1503
1504
1505 Create a new or get an already existing thread local store associated with
1506 the current active coroutine.
1507
1508 A thread local store is private a table object
1509 whose values can't be accessed from outside of the running coroutine.
1510
1511
1512
1513
1514
1515
1516
1517
1518 <h3>Return value:</h3>
1519 Table value representing the corresponding thread local store
1520
1521
1522
1523 </dd>
1524
1525
1526
1527
1528 <dt><a name="trim"></a><strong>trim</strong>&nbsp;(str)</dt>
1529 <dd>
1530
1531
1532 Remove leading and trailing whitespace from given string value.
1533
1534
1535
1536 <h3>Parameters</h3>
1537 <ul>
1538
1539         <li>
1540           str: String value containing whitespace padded data
1541         </li>
1542
1543 </ul>
1544
1545
1546
1547
1548
1549
1550 <h3>Return value:</h3>
1551 String value with leading and trailing space removed
1552
1553
1554
1555 </dd>
1556
1557
1558
1559
1560 <dt><a name="ubus"></a><strong>ubus</strong>&nbsp;(object, method, values)</dt>
1561 <dd>
1562
1563
1564 Issue an ubus call.
1565
1566
1567
1568 <h3>Parameters</h3>
1569 <ul>
1570
1571         <li>
1572           object: String containing the ubus object to call
1573         </li>
1574
1575         <li>
1576           method: String containing the ubus method to call
1577         </li>
1578
1579         <li>
1580           values: Table containing the values to pass
1581         </li>
1582
1583 </ul>
1584
1585
1586
1587
1588
1589
1590 <h3>Return value:</h3>
1591 Table containin the ubus result
1592
1593
1594
1595 </dd>
1596
1597
1598
1599
1600 <dt><a name="update"></a><strong>update</strong>&nbsp;(t, updates)</dt>
1601 <dd>
1602
1603
1604 Update values in given table with the values from the second given table.
1605
1606 Both table are - in fact - merged together.
1607
1608
1609
1610 <h3>Parameters</h3>
1611 <ul>
1612
1613         <li>
1614           t: Table which should be updated
1615         </li>
1616
1617         <li>
1618           updates: Table containing the values to update
1619         </li>
1620
1621 </ul>
1622
1623
1624
1625
1626
1627
1628 <h3>Return value:</h3>
1629 Always nil
1630
1631
1632
1633 </dd>
1634
1635
1636
1637
1638 <dt><a name="urldecode"></a><strong>urldecode</strong>&nbsp;(str, decode_plus)</dt>
1639 <dd>
1640
1641
1642 Decode an URL-encoded string - optionally decoding the "+" sign to space.
1643
1644
1645
1646 <h3>Parameters</h3>
1647 <ul>
1648
1649         <li>
1650           str: Input string in x-www-urlencoded format
1651         </li>
1652
1653         <li>
1654           decode_plus: Decode "+" signs to spaces if true (optional)
1655         </li>
1656
1657 </ul>
1658
1659
1660
1661
1662
1663
1664 <h3>Return value:</h3>
1665 The decoded string
1666
1667
1668
1669 <h3>See also:</h3>
1670 <ul>
1671
1672         <li><a href="#urlencode">
1673                 urlencode
1674         </a>
1675
1676 </ul>
1677
1678 </dd>
1679
1680
1681
1682
1683 <dt><a name="urlencode"></a><strong>urlencode</strong>&nbsp;(str)</dt>
1684 <dd>
1685
1686
1687 URL-encode given string.
1688
1689
1690
1691 <h3>Parameters</h3>
1692 <ul>
1693
1694         <li>
1695           str: String to encode
1696         </li>
1697
1698 </ul>
1699
1700
1701
1702
1703
1704
1705 <h3>Return value:</h3>
1706 String containing the encoded data
1707
1708
1709
1710 <h3>See also:</h3>
1711 <ul>
1712
1713         <li><a href="#urldecode">
1714                 urldecode
1715         </a>
1716
1717 </ul>
1718
1719 </dd>
1720
1721
1722
1723
1724 <dt><a name="vspairs"></a><strong>vspairs</strong>&nbsp;(t)</dt>
1725 <dd>
1726
1727
1728 Return a key, value iterator for the given table.
1729
1730 The table pairs are sorted by value.
1731
1732
1733
1734 <h3>Parameters</h3>
1735 <ul>
1736
1737         <li>
1738           t: The table to iterate
1739         </li>
1740
1741 </ul>
1742
1743
1744
1745
1746
1747
1748 <h3>Return value:</h3>
1749 Function value containing the corresponding iterator
1750
1751
1752
1753 </dd>
1754
1755
1756 </dl>
1757
1758
1759
1760
1761
1762 </div> <!-- id="content" -->
1763
1764 </div> <!-- id="main" -->
1765
1766 <div id="about">
1767         <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>
1768 </div> <!-- id="about" -->
1769
1770 </div> <!-- id="container" -->
1771 </body>
1772 </html>