modules/luci-base/luasrc/model/uci.luadoc

   1 ---[[
   2 LuCI UCI model library.
   3
   4 The typical workflow for UCI is:  Get a cursor instance from the
   5 cursor factory, modify data (via Cursor.add, Cursor.delete, etc.),
   6 save the changes to the staging area via Cursor.save and finally
   7 Cursor.commit the data to the actual config files.
   8 LuCI then needs to Cursor.apply the changes so daemons etc. are
   9 reloaded.
  10 @cstyle instance
  11 ]]
  12 module "luci.model.uci"
  13
  14 ---[[
  15 Create a new UCI-Cursor.
  16
  17 @class                          function
  18 @name                           cursor
  19 @return                         UCI-Cursor
  20 ]]
  21
  22 ---[[
  23 Create a new Cursor initialized to the state directory.
  24
  25 @class                          function
  26 @name                           cursor_state
  27 @return                         UCI cursor
  28 ]]
  29
  30 ---[[
  31 Applies UCI configuration changes.
  32
  33 If the rollback parameter is set to true, the apply function will invoke the
  34 rollback mechanism which causes the configuration to be automatically reverted
  35 if no confirm() call occurs within a certain timeout.
  36
  37 The current default timeout is 30s and can be increased using the
  38 "luci.apply.timeout" uci configuration key.
  39
  40 @class                          function
  41 @name                           Cursor.apply
  42 @param rollback         Enable rollback mechanism
  43 @return                         Boolean whether operation succeeded
  44 ]]
  45
  46 ---[[
  47 Confirms UCI apply process.
  48
  49 If a previous UCI apply with rollback has been invoked using apply(true),
  50 this function confirms the process and cancels the pending rollback timer.
  51
  52 If no apply with rollback session is active, the function has no effect and
  53 returns with a "No data" error.
  54
  55 @class                          function
  56 @name                           Cursor.confirm
  57 @return                         Boolean whether operation succeeded
  58 ]]
  59
  60 ---[[
  61 Cancels UCI apply process.
  62
  63 If a previous UCI apply with rollback has been invoked using apply(true),
  64 this function cancels the process and rolls back the configuration to the
  65 pre-apply state.
  66
  67 If no apply with rollback session is active, the function has no effect and
  68 returns with a "No data" error.
  69
  70 @class                          function
  71 @name                           Cursor.rollback
  72 @return                         Boolean whether operation succeeded
  73 ]]
  74
  75 ---[[
  76 Checks whether a pending rollback is scheduled.
  77
  78 If a previous UCI apply with rollback has been invoked using apply(true),
  79 and has not been confirmed or rolled back yet, this function returns true
  80 and the remaining time until rollback in seconds. If no rollback is pending,
  81 the function returns false. On error, the function returns false and an
  82 additional string describing the error.
  83
  84 @class                          function
  85 @name                           Cursor.rollback_pending
  86 @return                         Boolean whether rollback is pending
  87 @return                         Remaining time in seconds
  88 ]]
  89
  90 ---[[
  91 Delete all sections of a given type that match certain criteria.
  92
  93 @class                          function
  94 @name                           Cursor.delete_all
  95 @param config           UCI config
  96 @param type                     UCI section type
  97 @param comparator       Function that will be called for each section and returns
  98                                         a boolean whether to delete the current section (optional)
  99 ]]
 100
 101 ---[[
 102 Create a new section and initialize it with data.
 103
 104 @class                          function
 105 @name                           Cursor.section
 106 @param config           UCI config
 107 @param type                     UCI section type
 108 @param name                     UCI section name (optional)
 109 @param values           Table of key - value pairs to initialize the section with
 110 @return                         Name of created section
 111 ]]
 112
 113 ---[[
 114 Updated the data of a section using data from a table.
 115
 116 @class                          function
 117 @name                           Cursor.tset
 118 @param config           UCI config
 119 @param section          UCI section name (optional)
 120 @param values           Table of key - value pairs to update the section with
 121 ]]
 122
 123 ---[[
 124 Get a boolean option and return it's value as true or false.
 125
 126 @class                          function
 127 @name                           Cursor.get_bool
 128 @param config           UCI config
 129 @param section          UCI section name
 130 @param option           UCI option
 131 @return                         Boolean
 132 ]]
 133
 134 ---[[
 135 Get an option or list and return values as table.
 136
 137 @class                          function
 138 @name                           Cursor.get_list
 139 @param config           UCI config
 140 @param section          UCI section name
 141 @param option           UCI option
 142 @return table.          If the option was not found, you will simply get an empty
 143                                         table.
 144 ]]
 145
 146 ---[[
 147 Get the given option from the first section with the given type.
 148
 149 @class                          function
 150 @name                           Cursor.get_first
 151 @param config           UCI config
 152 @param type                     UCI section type
 153 @param option           UCI option (optional)
 154 @param default          Default value (optional)
 155 @return                         UCI value
 156 ]]
 157
 158 ---[[
 159 Set given values as list. Setting a list option to an empty list
 160 has the same effect as deleting the option.
 161
 162 @class                          function
 163 @name                           Cursor.set_list
 164 @param config           UCI config
 165 @param section          UCI section name
 166 @param option           UCI option
 167 @param value            Value or table. Non-table values will be set as single
 168                                         item UCI list.
 169 @return                         Boolean whether operation succeeded
 170 ]]
 171
 172 ---[[
 173 Create a sub-state of this cursor.
 174
 175 The sub-state is tied to the parent cursor, means it the parent unloads or
 176 loads configs, the sub state will do so as well.
 177
 178 @class                          function
 179 @name                           Cursor.substate
 180 @return                         UCI state cursor tied to the parent cursor
 181 ]]
 182
 183 ---[[
 184 Add an anonymous section.
 185
 186 @class                          function
 187 @name                           Cursor.add
 188 @param config           UCI config
 189 @param type                     UCI section type
 190 @return                         Name of created section
 191 ]]
 192
 193 ---[[
 194 Get a table of saved but uncommitted changes.
 195
 196 @class                          function
 197 @name                           Cursor.changes
 198 @param config           UCI config
 199 @return                         Table of changes
 200 @see                            Cursor.save
 201 ]]
 202
 203 ---[[
 204 Commit saved changes.
 205
 206 @class                          function
 207 @name                           Cursor.commit
 208 @param config           UCI config
 209 @return                         Boolean whether operation succeeded
 210 @see                            Cursor.revert
 211 @see                            Cursor.save
 212 ]]
 213
 214 ---[[
 215 Deletes a section or an option.
 216
 217 @class                          function
 218 @name                           Cursor.delete
 219 @param config           UCI config
 220 @param section          UCI section name
 221 @param option           UCI option (optional)
 222 @return                         Boolean whether operation succeeded
 223 ]]
 224
 225 ---[[
 226 Call a function for every section of a certain type.
 227
 228 @class                          function
 229 @name                           Cursor.foreach
 230 @param config           UCI config
 231 @param type                     UCI section type
 232 @param callback         Function to be called
 233 @return                         Boolean whether operation succeeded
 234 ]]
 235
 236 ---[[
 237 Get a section type or an option
 238
 239 @class                          function
 240 @name                           Cursor.get
 241 @param config           UCI config
 242 @param section          UCI section name
 243 @param option           UCI option (optional)
 244 @return                         UCI value
 245 ]]
 246
 247 ---[[
 248 Get all sections of a config or all values of a section.
 249
 250 @class                          function
 251 @name                           Cursor.get_all
 252 @param config           UCI config
 253 @param section          UCI section name (optional)
 254 @return                         Table of UCI sections or table of UCI values
 255 ]]
 256
 257 ---[[
 258 Manually load a config.
 259
 260 @class                          function
 261 @name                           Cursor.load
 262 @param config           UCI config
 263 @return                         Boolean whether operation succeeded
 264 @see                            Cursor.save
 265 @see                            Cursor.unload
 266 ]]
 267
 268 ---[[
 269 Revert saved but uncommitted changes.
 270
 271 @class                          function
 272 @name                           Cursor.revert
 273 @param config           UCI config
 274 @return                         Boolean whether operation succeeded
 275 @see                            Cursor.commit
 276 @see                            Cursor.save
 277 ]]
 278
 279 ---[[
 280 Saves changes made to a config to make them committable.
 281
 282 @class                          function
 283 @name                           Cursor.save
 284 @param config           UCI config
 285 @return                         Boolean whether operation succeeded
 286 @see                            Cursor.load
 287 @see                            Cursor.unload
 288 ]]
 289
 290 ---[[
 291 Set a value or create a named section.
 292
 293 When invoked with three arguments `config`, `sectionname`, `sectiontype`,
 294 then a named section of the given type is created.
 295
 296 When invoked with four arguments `config`, `sectionname`, `optionname` and
 297 `optionvalue` then the value of the specified option is set to the given value.
 298
 299 @class                          function
 300 @name                           Cursor.set
 301 @param config           UCI config
 302 @param section          UCI section name
 303 @param option           UCI option or UCI section type
 304 @param value            UCI value or nothing if you want to create a section
 305 @return                         Boolean whether operation succeeded
 306 ]]
 307
 308 ---[[
 309 Get the configuration directory.
 310
 311 @class                          function
 312 @name                           Cursor.get_confdir
 313 @return                         Configuration directory
 314 ]]
 315
 316 ---[[
 317 Get the directory for uncomitted changes.
 318
 319 @class                          function
 320 @name                           Cursor.get_savedir
 321 @return                         Save directory
 322 ]]
 323
 324 ---[[
 325 Get the effective session ID.
 326
 327 @class                          function
 328 @name                           Cursor.get_session_id
 329 @return                         String containing the session ID
 330 ]]
 331
 332 ---[[
 333 Set the configuration directory.
 334
 335 @class                          function
 336 @name                           Cursor.set_confdir
 337 @param directory        UCI configuration directory
 338 @return                         Boolean whether operation succeeded
 339 ]]
 340
 341 ---[[
 342 Set the directory for uncommitted changes.
 343
 344 @class                          function
 345 @name                           Cursor.set_savedir
 346 @param directory        UCI changes directory
 347 @return                         Boolean whether operation succeeded
 348 ]]
 349
 350 ---[[
 351 Set the effective session ID.
 352
 353 @class                          function
 354 @name                           Cursor.set_session_id
 355 @param id                       String containing the session ID to set
 356 @return                         Boolean whether operation succeeded
 357 ]]
 358
 359 ---[[
 360 Discard changes made to a config.
 361
 362 @class                          function
 363 @name                           Cursor.unload
 364 @param config           UCI config
 365 @return                         Boolean whether operation succeeded
 366 @see                            Cursor.load
 367 @see                            Cursor.save
 368 ]]
 369