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