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