libs/uci/luasrc/model/uci.lua

   1 --[[
   2 LuCI - UCI model
   3
   4 Description:
   5 Generalized UCI model
   6
   7 FileId:
   8 $Id$
   9
  10 License:
  11 Copyright 2008 Steven Barth <steven@midlink.org>
  12
  13 Licensed under the Apache License, Version 2.0 (the "License");
  14 you may not use this file except in compliance with the License.
  15 You may obtain a copy of the License at
  16
  17         http://www.apache.org/licenses/LICENSE-2.0
  18
  19 Unless required by applicable law or agreed to in writing, software
  20 distributed under the License is distributed on an "AS IS" BASIS,
  21 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  22 See the License for the specific language governing permissions and
  23 limitations under the License.
  24
  25 ]]--
  26 local os    = require "os"
  27 local uci   = require "uci"
  28 local util  = require "luci.util"
  29 local table = require "table"
  30
  31
  32 local setmetatable, rawget, rawset = setmetatable, rawget, rawset
  33 local error, pairs, ipairs, tostring = error, pairs, ipairs, tostring
  34 local require, getmetatable = require, getmetatable
  35
  36 --- LuCI UCI model library.
  37 -- @cstyle      instance
  38 module "luci.model.uci"
  39
  40 --- Create a new UCI-Cursor.
  41 -- @class function
  42 -- @name cursor
  43 -- @return      UCI-Cursor
  44 cursor = uci.cursor
  45
  46 APIVERSION = uci.APIVERSION
  47
  48 --- Create a new Cursor initialized to the state directory.
  49 -- @return UCI cursor
  50 function cursor_state()
  51         return cursor(nil, "/var/state")
  52 end
  53
  54
  55 local Cursor = getmetatable(cursor())
  56
  57 --- Applies the new config
  58 -- @param config                UCI config
  59 function Cursor.apply(self, config)
  60         local conf = require "luci.config"
  61         return conf.uci_oncommit[config] and
  62          os.execute(conf.uci_oncommit[config] .. " >/dev/null 2>&1")
  63 end
  64
  65 --- Delete all sections of a given type that match certain criteria.
  66 -- @param config                UCI config
  67 -- @param type                  UCI section type
  68 -- @param comparator    Function that will be called for each section and
  69 -- returns a boolean whether to delete the current section (optional)
  70 function Cursor.delete_all(self, config, type, comparator)
  71         local del = {}
  72         local function helper (section)
  73                 if not comparator or comparator(section) then
  74                         table.insert(del, section[".name"])
  75                 end
  76         end
  77
  78         self:foreach(config, type, helper)
  79
  80         for i, j in ipairs(del) do
  81                 self:delete(config, j)
  82         end
  83 end
  84
  85 --- Create a new section and initialize it with data.
  86 -- @param config        UCI config
  87 -- @param type          UCI section type
  88 -- @param name          UCI section name (optional)
  89 -- @param values        Table of key - value pairs to initialize the section with
  90 -- @return                      Name of created section
  91 function Cursor.section(self, config, type, name, values)
  92         local stat = true
  93         if name then
  94                 stat = self:set(config, name, type)
  95         else
  96                 name = self:add(config, type)
  97                 stat = name and true
  98         end
  99
 100         if stat and values then
 101                 stat = self:tset(config, name, values)
 102         end
 103
 104         return stat and name
 105 end
 106
 107 --- Updated the data of a section using data from a table.
 108 -- @param config        UCI config
 109 -- @param section       UCI section name (optional)
 110 -- @param values        Table of key - value pairs to update the section with
 111 function Cursor.tset(self, config, section, values)
 112         local stat = true
 113         for k, v in pairs(values) do
 114                 if k:sub(1, 1) ~= "." then
 115                         stat = stat and self:set(config, section, k, v)
 116                 end
 117         end
 118         return stat
 119 end
 120
 121 --- Get an option or list and return values as table.
 122 -- @param config        UCI config
 123 -- @param section       UCI section name
 124 -- @param option        UCI option
 125 -- @return                      UCI value
 126 function Cursor.get_list(self, config, section, option)
 127         if config and section and option then
 128                 local val = self:get(config, section, option)
 129                 return ( type(val) == "table" and val or { val } )
 130         end
 131         return nil
 132 end
 133
 134 --- Set given values as list.
 135 -- @param config        UCI config
 136 -- @param section       UCI section name
 137 -- @param option        UCI option
 138 -- @param value         UCI value
 139 -- @return                      Boolean whether operation succeeded
 140 function Cursor.set_list(self, config, section, option, value)
 141         if config and section and option then
 142                 return self:set(
 143                         config, section, option,
 144                         ( type(value) == "table" and value or { value } )
 145                 )
 146         end
 147         return false
 148 end
 149
 150
 151 Cursor._changes = Cursor.changes
 152 function Cursor.changes(self, config)
 153         if config then
 154                 return Cursor._changes(self, config)
 155         else
 156                 local changes = Cursor._changes(self)
 157                 util.copcall(function()
 158                         for k,v in pairs(require "luci.fs".dir(self:get_savedir())) do
 159                                 if v ~= "." and v ~= ".." then
 160                                         util.update(changes, Cursor._changes(self, v))
 161                                 end
 162                         end
 163                 end)
 164                 return changes
 165         end
 166 end
 167
 168
 169 --- Add an anonymous section.
 170 -- @class function
 171 -- @name Cursor.add
 172 -- @param config        UCI config
 173 -- @param type          UCI section type
 174 -- @return                      Name of created section
 175
 176 --- Get a table of unsaved changes.
 177 -- @class function
 178 -- @name Cursor.changes
 179 -- @param config        UCI config
 180 -- @return                      Table of changes
 181
 182 --- Commit unsaved changes.
 183 -- @class function
 184 -- @name Cursor.commit
 185 -- @param config        UCI config
 186 -- @return                      Boolean whether operation succeeded
 187 -- @see Cursor.revert
 188
 189 --- Deletes a section or an option.
 190 -- @class function
 191 -- @name Cursor.delete
 192 -- @param config        UCI config
 193 -- @param section       UCI section name
 194 -- @param option        UCI option (optional)
 195 -- @return                      Boolean whether operation succeeded
 196
 197 --- Call a function for every section of a certain type.
 198 -- @class function
 199 -- @name Cursor.foreach
 200 -- @param config        UCI config
 201 -- @param type          UCI section type
 202 -- @param callback      Function to be called
 203 -- @return                      Boolean whether operation succeeded
 204
 205 --- Get a section type or an option
 206 -- @class function
 207 -- @name Cursor.get
 208 -- @param config        UCI config
 209 -- @param section       UCI section name
 210 -- @param option        UCI option (optional)
 211 -- @return                      UCI value
 212
 213 --- Get all sections of a config or all values of a section.
 214 -- @class function
 215 -- @name Cursor.get_all
 216 -- @param config        UCI config
 217 -- @param section       UCI section name (optional)
 218 -- @return                      Table of UCI sections or table of UCI values
 219
 220 --- Manually load a config.
 221 -- @class function
 222 -- @name Cursor.load
 223 -- @param config        UCI config
 224 -- @return                      Boolean whether operation succeeded
 225 -- @see Cursor.save
 226 -- @see Cursor.unload
 227
 228 --- Revert unsaved changes.
 229 -- @class function
 230 -- @name Cursor.revert
 231 -- @param config        UCI config
 232 -- @return                      Boolean whether operation succeeded
 233 -- @see Cursor.commit
 234
 235 --- Saves changes made to a config to make them committable.
 236 -- @class function
 237 -- @name Cursor.save
 238 -- @param config        UCI config
 239 -- @return                      Boolean whether operation succeeded
 240 -- @see Cursor.load
 241 -- @see Cursor.unload
 242
 243 --- Set a value or create a named section.
 244 -- @class function
 245 -- @name Cursor.set
 246 -- @param config        UCI config
 247 -- @param section       UCI section name
 248 -- @param option        UCI option or UCI section type
 249 -- @param value         UCI value or nil if you want to create a section
 250 -- @return                      Boolean whether operation succeeded
 251
 252 --- Get the configuration directory.
 253 -- @class function
 254 -- @name Cursor.get_confdir
 255 -- @return                      Configuration directory
 256
 257 --- Get the directory for uncomitted changes.
 258 -- @class function
 259 -- @name Cursor.get_savedir
 260 -- @return                      Save directory
 261
 262 --- Set the configuration directory.
 263 -- @class function
 264 -- @name Cursor.set_confdir
 265 -- @param directory     UCI configuration directory
 266 -- @return                      Boolean whether operation succeeded
 267
 268 --- Set the directory for uncommited changes.
 269 -- @class function
 270 -- @name Cursor.set_savedir
 271 -- @param directory     UCI changes directory
 272 -- @return                      Boolean whether operation succeeded
 273
 274 --- Discard changes made to a config.
 275 -- @class function
 276 -- @name Cursor.unload
 277 -- @param config        UCI config
 278 -- @return                      Boolean whether operation succeeded
 279 -- @see Cursor.load
 280 -- @see Cursor.save