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
  47 returns 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
  92 --              an empty 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. Raw values will become a single item table.
 117 @return                 Boolean whether operation succeeded
 118 ]]
 119
 120 ---[[
 121 Create a sub-state of this cursor. The sub-state is tied to the parent
 122
 123 curser, means it the parent unloads or loads configs, the sub state will
 124 do so as well.
 125 @class function
 126 @name Cursor.substate
 127 @return                 UCI state cursor tied to the parent cursor
 128 ]]
 129
 130 ---[[
 131 Add an anonymous section.
 132
 133 @class function
 134 @name Cursor.add
 135 @param config   UCI config
 136 @param type             UCI section type
 137 @return                 Name of created section
 138 ]]
 139
 140 ---[[
 141 Get a table of saved but uncommitted changes.
 142
 143 @class function
 144 @name Cursor.changes
 145 @param config   UCI config
 146 @return                 Table of changes
 147 @see Cursor.save
 148 ]]
 149
 150 ---[[
 151 Commit saved changes.
 152
 153 @class function
 154 @name Cursor.commit
 155 @param config   UCI config
 156 @return                 Boolean whether operation succeeded
 157 @see Cursor.revert
 158 @see Cursor.save
 159 ]]
 160
 161 ---[[
 162 Deletes a section or an option.
 163
 164 @class function
 165 @name Cursor.delete
 166 @param config   UCI config
 167 @param section  UCI section name
 168 @param option   UCI option (optional)
 169 @return                 Boolean whether operation succeeded
 170 ]]
 171
 172 ---[[
 173 Call a function for every section of a certain type.
 174
 175 @class function
 176 @name Cursor.foreach
 177 @param config   UCI config
 178 @param type             UCI section type
 179 @param callback Function to be called
 180 @return                 Boolean whether operation succeeded
 181 ]]
 182
 183 ---[[
 184 Get a section type or an option
 185
 186 @class function
 187 @name Cursor.get
 188 @param config   UCI config
 189 @param section  UCI section name
 190 @param option   UCI option (optional)
 191 @return                 UCI value
 192 ]]
 193
 194 ---[[
 195 Get all sections of a config or all values of a section.
 196
 197 @class function
 198 @name Cursor.get_all
 199 @param config   UCI config
 200 @param section  UCI section name (optional)
 201 @return                 Table of UCI sections or table of UCI values
 202 ]]
 203
 204 ---[[
 205 Manually load a config.
 206
 207 @class function
 208 @name Cursor.load
 209 @param config   UCI config
 210 @return                 Boolean whether operation succeeded
 211 @see Cursor.save
 212 @see Cursor.unload
 213 ]]
 214
 215 ---[[
 216 Revert saved but uncommitted changes.
 217
 218 @class function
 219 @name Cursor.revert
 220 @param config   UCI config
 221 @return                 Boolean whether operation succeeded
 222 @see Cursor.commit
 223 @see Cursor.save
 224 ]]
 225
 226 ---[[
 227 Saves changes made to a config to make them committable.
 228
 229 @class function
 230 @name Cursor.save
 231 @param config   UCI config
 232 @return                 Boolean whether operation succeeded
 233 @see Cursor.load
 234 @see Cursor.unload
 235 ]]
 236
 237 ---[[
 238 Set a value or create a named section.
 239
 240 When invoked with three arguments `config`, `sectionname`, `sectiontype`,
 241 then a named section of the given type is created.
 242
 243 When invoked with four arguments `config`, `sectionname`, `optionname` and
 244 `optionvalue` then the value of the specified option is set to the given value.
 245
 246 @class function
 247 @name Cursor.set
 248 @param config   UCI config
 249 @param section  UCI section name
 250 @param option   UCI option or UCI section type
 251 @param value            UCI value or nothing if you want to create a section
 252 @return                 Boolean whether operation succeeded
 253 ]]
 254
 255 ---[[
 256 Get the configuration directory.
 257
 258 @class function
 259 @name Cursor.get_confdir
 260 @return                 Configuration directory
 261 ]]
 262
 263 ---[[
 264 Get the directory for uncomitted changes.
 265
 266 @class function
 267 @name Cursor.get_savedir
 268 @return                 Save directory
 269 ]]
 270
 271 ---[[
 272 Set the configuration directory.
 273
 274 @class function
 275 @name Cursor.set_confdir
 276 @param directory        UCI configuration directory
 277 @return                 Boolean whether operation succeeded
 278 ]]
 279
 280 ---[[
 281 Set the directory for uncommited changes.
 282
 283 @class function
 284 @name Cursor.set_savedir
 285 @param directory        UCI changes directory
 286 @return                 Boolean whether operation succeeded
 287 ]]
 288
 289 ---[[
 290 Discard changes made to a config.
 291
 292 @class function
 293 @name Cursor.unload
 294 @param config   UCI config
 295 @return                 Boolean whether operation succeeded
 296 @see Cursor.load
 297 @see Cursor.save
 298 ]]
 299