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 iterator 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 Recursively serialize given data to lua code, suitable for restoring
 260 with loadstring().
 261
 262 @class                          function
 263 @name                           serialize_data
 264 @param val                      Value containing the data to serialize
 265 @return                         String value containing the serialized code
 266 @see                            restore_data
 267 @see                            get_bytecode
 268 ]]
 269
 270 ---[[
 271 Restore data previously serialized with serialize_data().
 272
 273 @class                          function
 274 @name                           restore_data
 275 @param str                      String containing the data to restore
 276 @return                         Value containing the restored data structure
 277 @see                            serialize_data
 278 @see                            get_bytecode
 279 ]]
 280
 281 ---[[
 282 Return the current runtime bytecode of the given data. The byte code
 283 will be stripped before it is returned.
 284
 285 @class                          function
 286 @name                           get_bytecode
 287 @param val                      Value to return as bytecode
 288 @return                         String value containing the bytecode of the given data
 289 ]]
 290
 291 ---[[
 292 Strips unnecessary lua bytecode from given string.
 293
 294 Information like line numbers and debugging numbers will be discarded.
 295 Original version by Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
 296
 297 @class                          function
 298 @name                           strip_bytecode
 299 @param code                     String value containing the original lua byte code
 300 @return                         String value containing the stripped lua byte code
 301 ]]
 302
 303 ---[[
 304 Return a key, value iterator which returns the values sorted according to
 305 the provided callback function.
 306
 307 @class                          function
 308 @name                           spairs
 309 @param t                        The table to iterate
 310 @param f                        A callback function to decide the order of elements
 311 @return                         Function value containing the corresponding iterator
 312 ]]
 313
 314 ---[[
 315 Return a key, value iterator for the given table.
 316
 317 The table pairs are sorted by key.
 318
 319 @class                          function
 320 @name                           kspairs
 321 @param t                        The table to iterate
 322 @return                         Function value containing the corresponding iterator
 323 ]]
 324
 325 ---[[
 326 Return a key, value iterator for the given table.
 327
 328 The table pairs are sorted by value.
 329
 330 @class                          function
 331 @name                           vspairs
 332 @param t                        The table to iterate
 333 @return                         Function value containing the corresponding iterator
 334 ]]
 335
 336 ---[[
 337 Test whether the current system is operating in big endian mode.
 338
 339 @class                          function
 340 @name                           bigendian
 341 @return                         Boolean value indicating whether system is big endian
 342 ]]
 343
 344 ---[[
 345 Execute given commandline and gather stdout.
 346
 347 @class                          function
 348 @name                           exec
 349 @param command          String containing command to execute
 350 @return                         String containing the command's stdout
 351 ]]
 352
 353 ---[[
 354 Return a line-buffered iterator over the output of given command.
 355
 356 @class                          function
 357 @name                           execi
 358 @param command          String containing the command to execute
 359 @return                         Iterator
 360 ]]
 361
 362 ---[[
 363 Issue an ubus call.
 364
 365 @class                          function
 366 @name                           ubus
 367 @param object           String containing the ubus object to call
 368 @param method           String containing the ubus method to call
 369 @param values           Table containing the values to pass
 370 @return                         Table containin the ubus result
 371 ]]
 372
 373 ---[[
 374 Convert data structure to JSON
 375
 376 @class                          function
 377 @name                           serialize_json
 378 @param data                     The data to serialize
 379 @param writer           A function to write a chunk of JSON data (optional)
 380 @return                         String containing the JSON if called without write callback
 381 ]]
 382
 383 ---[[
 384 Returns the absolute path to LuCI base directory.
 385
 386 @class                          function
 387 @name                           libpath
 388 @return                         String containing the directory path
 389 ]]
 390
 391 ---[[
 392 This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
 393
 394 @class                          function
 395 @name                           coxpcall
 396 @param f                        Lua function to be called protected
 397 @param err                      Custom error handler
 398 @param ...                      Parameters passed to the function
 399 @return                         A boolean whether the function call succeeded and the return
 400 --                                      values of either the function or the error handler
 401 ]]
 402
 403 ---[[
 404 This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
 405
 406 @class                          function
 407 @name                           copcall
 408 @param f                        Lua function to be called protected
 409 @param ...                      Parameters passed to the function
 410 @return                         A boolean whether the function call succeeded and the returns
 411 --                                      values of the function or the error object
 412 ]]
 413