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