modules/luci-base/luasrc/util.luadoc

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