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