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 deamons 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 @class                          function
  34 @name                           Cursor.apply
  35 @param configlist       List of UCI configurations
  36 @param command          Don't apply only return the command
  37 ]]
  38
  39 ---[[
  40 Delete all sections of a given type that match certain criteria.
  41
  42 @class                          function
  43 @name                           Cursor.delete_all
  44 @param config           UCI config
  45 @param type                     UCI section type
  46 @param comparator       Function that will be called for each section and returns
  47                                         a boolean whether to delete the current section (optional)
  48 ]]
  49
  50 ---[[
  51 Create a new section and initialize it with data.
  52
  53 @class                          function
  54 @name                           Cursor.section
  55 @param config           UCI config
  56 @param type                     UCI section type
  57 @param name                     UCI section name (optional)
  58 @param values           Table of key - value pairs to initialize the section with
  59 @return                         Name of created section
  60 ]]
  61
  62 ---[[
  63 Updated the data of a section using data from a table.
  64
  65 @class                          function
  66 @name                           Cursor.tset
  67 @param config           UCI config
  68 @param section          UCI section name (optional)
  69 @param values           Table of key - value pairs to update the section with
  70 ]]
  71
  72 ---[[
  73 Get a boolean option and return it's value as true or false.
  74
  75 @class                          function
  76 @name                           Cursor.get_bool
  77 @param config           UCI config
  78 @param section          UCI section name
  79 @param option           UCI option
  80 @return                         Boolean
  81 ]]
  82
  83 ---[[
  84 Get an option or list and return values as table.
  85
  86 @class                          function
  87 @name                           Cursor.get_list
  88 @param config           UCI config
  89 @param section          UCI section name
  90 @param option           UCI option
  91 @return table.          If the option was not found, you will simply get an empty
  92                                         table.
  93 ]]
  94
  95 ---[[
  96 Get the given option from the first section with the given type.
  97
  98 @class                          function
  99 @name                           Cursor.get_first
 100 @param config           UCI config
 101 @param type                     UCI section type
 102 @param option           UCI option (optional)
 103 @param default          Default value (optional)
 104 @return                         UCI value
 105 ]]
 106
 107 ---[[
 108 Set given values as list. Setting a list option to an empty list
 109 has the same effect as deleting the option.
 110
 111 @class                          function
 112 @name                           Cursor.set_list
 113 @param config           UCI config
 114 @param section          UCI section name
 115 @param option           UCI option
 116 @param value            Value or table. Non-table values will be set as single
 117                                         item UCI list.
 118 @return                         Boolean whether operation succeeded
 119 ]]
 120
 121 ---[[
 122 Create a sub-state of this cursor.
 123
 124 The sub-state is tied to the parent curser, means it the parent unloads or
 125 loads configs, the sub state will do so as well.
 126
 127 @class                          function
 128 @name                           Cursor.substate
 129 @return                         UCI state cursor tied to the parent cursor
 130 ]]
 131
 132 ---[[
 133 Add an anonymous section.
 134
 135 @class                          function
 136 @name                           Cursor.add
 137 @param config           UCI config
 138 @param type                     UCI section type
 139 @return                         Name of created section
 140 ]]
 141
 142 ---[[
 143 Get a table of saved but uncommitted changes.
 144
 145 @class                          function
 146 @name                           Cursor.changes
 147 @param config           UCI config
 148 @return                         Table of changes
 149 @see                            Cursor.save
 150 ]]
 151
 152 ---[[
 153 Commit saved changes.
 154
 155 @class                          function
 156 @name                           Cursor.commit
 157 @param config           UCI config
 158 @return                         Boolean whether operation succeeded
 159 @see                            Cursor.revert
 160 @see                            Cursor.save
 161 ]]
 162
 163 ---[[
 164 Deletes a section or an option.
 165
 166 @class                          function
 167 @name                           Cursor.delete
 168 @param config           UCI config
 169 @param section          UCI section name
 170 @param option           UCI option (optional)
 171 @return                         Boolean whether operation succeeded
 172 ]]
 173
 174 ---[[
 175 Call a function for every section of a certain type.
 176
 177 @class                          function
 178 @name                           Cursor.foreach
 179 @param config           UCI config
 180 @param type                     UCI section type
 181 @param callback         Function to be called
 182 @return                         Boolean whether operation succeeded
 183 ]]
 184
 185 ---[[
 186 Get a section type or an option
 187
 188 @class                          function
 189 @name                           Cursor.get
 190 @param config           UCI config
 191 @param section          UCI section name
 192 @param option           UCI option (optional)
 193 @return                         UCI value
 194 ]]
 195
 196 ---[[
 197 Get all sections of a config or all values of a section.
 198
 199 @class                          function
 200 @name                           Cursor.get_all
 201 @param config           UCI config
 202 @param section          UCI section name (optional)
 203 @return                         Table of UCI sections or table of UCI values
 204 ]]
 205
 206 ---[[
 207 Manually load a config.
 208
 209 @class                          function
 210 @name                           Cursor.load
 211 @param config           UCI config
 212 @return                         Boolean whether operation succeeded
 213 @see                            Cursor.save
 214 @see                            Cursor.unload
 215 ]]
 216
 217 ---[[
 218 Revert saved but uncommitted changes.
 219
 220 @class                          function
 221 @name                           Cursor.revert
 222 @param config           UCI config
 223 @return                         Boolean whether operation succeeded
 224 @see                            Cursor.commit
 225 @see                            Cursor.save
 226 ]]
 227
 228 ---[[
 229 Saves changes made to a config to make them committable.
 230
 231 @class                          function
 232 @name                           Cursor.save
 233 @param config           UCI config
 234 @return                         Boolean whether operation succeeded
 235 @see                            Cursor.load
 236 @see                            Cursor.unload
 237 ]]
 238
 239 ---[[
 240 Set a value or create a named section.
 241
 242 When invoked with three arguments `config`, `sectionname`, `sectiontype`,
 243 then a named section of the given type is created.
 244
 245 When invoked with four arguments `config`, `sectionname`, `optionname` and
 246 `optionvalue` then the value of the specified option is set to the given value.
 247
 248 @class                          function
 249 @name                           Cursor.set
 250 @param config           UCI config
 251 @param section          UCI section name
 252 @param option           UCI option or UCI section type
 253 @param value            UCI value or nothing if you want to create a section
 254 @return                         Boolean whether operation succeeded
 255 ]]
 256
 257 ---[[
 258 Get the configuration directory.
 259
 260 @class                          function
 261 @name                           Cursor.get_confdir
 262 @return                         Configuration directory
 263 ]]
 264
 265 ---[[
 266 Get the directory for uncomitted changes.
 267
 268 @class                          function
 269 @name                           Cursor.get_savedir
 270 @return                         Save directory
 271 ]]
 272
 273 ---[[
 274 Get the effective session ID.
 275
 276 @class                          function
 277 @name                           Cursor.get_session_id
 278 @return                         String containing the session ID
 279 ]]
 280
 281 ---[[
 282 Set the configuration directory.
 283
 284 @class                          function
 285 @name                           Cursor.set_confdir
 286 @param directory        UCI configuration directory
 287 @return                         Boolean whether operation succeeded
 288 ]]
 289
 290 ---[[
 291 Set the directory for uncommited changes.
 292
 293 @class                          function
 294 @name                           Cursor.set_savedir
 295 @param directory        UCI changes directory
 296 @return                         Boolean whether operation succeeded
 297 ]]
 298
 299 ---[[
 300 Set the effective session ID.
 301
 302 @class                          function
 303 @name                           Cursor.set_session_id
 304 @param id                       String containing the session ID to set
 305 @return                         Boolean whether operation succeeded
 306 ]]
 307
 308 ---[[
 309 Discard changes made to a config.
 310
 311 @class                          function
 312 @name                           Cursor.unload
 313 @param config           UCI config
 314 @return                         Boolean whether operation succeeded
 315 @see                            Cursor.load
 316 @see                            Cursor.save
 317 ]]
 318