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