modules/luci-base/luasrc/util.luadoc

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