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 os.execute(conf.uci_oncommit[config])
  62 end
  63
  64 --- Delete all sections of a given type that match certain criteria.
  65 -- @param config                UCI config
  66 -- @param type                  UCI section type
  67 -- @param comparator    Function that will be called for each section and
  68 -- returns a boolean whether to delete the current section (optional)
  69 function Cursor.delete_all(self, config, type, comparator)
  70         local del = {}
  71         local function helper (section)
  72                 if not comparator or comparator(section) then
  73                         table.insert(del, section[".name"])
  74                 end
  75         end
  76
  77         self:foreach(config, type, helper)
  78
  79         for i, j in ipairs(del) do
  80                 self:delete(config, j)
  81         end
  82 end
  83
  84 --- Create a new section and initialize it with data.
  85 -- @param config        UCI config
  86 -- @param type          UCI section type
  87 -- @param name          UCI section name (optional)
  88 -- @param values        Table of key - value pairs to initialize the section with
  89 -- @return                      Name of created section
  90 function Cursor.section(self, config, type, name, values)
  91         local stat = true
  92         if name then
  93                 stat = self:set(config, name, type)
  94         else
  95                 name = self:add(config, type)
  96                 stat = name and true
  97         end
  98
  99         if stat and values then
 100                 stat = self:tset(config, name, values)
 101         end
 102
 103         return stat and name
 104 end
 105
 106 --- Updated the data of a section using data from a table.
 107 -- @param config        UCI config
 108 -- @param section       UCI section name (optional)
 109 -- @param values        Table of key - value pairs to update the section with
 110 function Cursor.tset(self, config, section, values)
 111         local stat = true
 112         for k, v in pairs(values) do
 113                 if k:sub(1, 1) ~= "." then
 114                         stat = stat and self:set(config, section, k, v)
 115                 end
 116         end
 117         return stat
 118 end
 119
 120 --- Get an option or list and return values as table.
 121 -- @param config        UCI config
 122 -- @param section       UCI section name
 123 -- @param option        UCI option
 124 -- @return                      UCI value
 125 function Cursor.get_list(self, config, section, option)
 126         if config and section and option then
 127                 local val = self:get(config, section, option)
 128                 return ( type(val) == "table" and val or { val } )
 129         end
 130         return nil
 131 end
 132
 133 --- Set given values as list.
 134 -- @param config        UCI config
 135 -- @param section       UCI section name
 136 -- @param option        UCI option
 137 -- @param value         UCI value
 138 -- @return                      Boolean whether operation succeeded
 139 function Cursor.set_list(self, config, section, option, value)
 140         if config and section and option then
 141                 return self:set(
 142                         config, section, option,
 143                         ( type(value) == "table" and value or { value } )
 144                 )
 145         end
 146         return false
 147 end
 148
 149
 150 --- Add an anonymous section.
 151 -- @class function
 152 -- @name Cursor.add
 153 -- @param config        UCI config
 154 -- @param type          UCI section type
 155 -- @return                      Name of created section
 156
 157 --- Get a table of unsaved changes.
 158 -- @class function
 159 -- @name Cursor.changes
 160 -- @param config        UCI config
 161 -- @return                      Table of changes
 162
 163 --- Commit unsaved changes.
 164 -- @class function
 165 -- @name Cursor.commit
 166 -- @param config        UCI config
 167 -- @return                      Boolean whether operation succeeded
 168 -- @see Cursor.revert
 169
 170 --- Deletes a section or an option.
 171 -- @class function
 172 -- @name Cursor.delete
 173 -- @param config        UCI config
 174 -- @param section       UCI section name
 175 -- @param option        UCI option (optional)
 176 -- @return                      Boolean whether operation succeeded
 177
 178 --- Call a function for every section of a certain type.
 179 -- @class function
 180 -- @name Cursor.foreach
 181 -- @param config        UCI config
 182 -- @param type          UCI section type
 183 -- @param callback      Function to be called
 184 -- @return                      Boolean whether operation succeeded
 185
 186 --- Get a section type or an option
 187 -- @class function
 188 -- @name Cursor.get
 189 -- @param config        UCI config
 190 -- @param section       UCI section name
 191 -- @param option        UCI option (optional)
 192 -- @return                      UCI value
 193
 194 --- Get all sections of a config or all values of a section.
 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 --- Manually load a config.
 202 -- @class function
 203 -- @name Cursor.load
 204 -- @param config        UCI config
 205 -- @return                      Boolean whether operation succeeded
 206 -- @see Cursor.save
 207 -- @see Cursor.unload
 208
 209 --- Revert unsaved changes.
 210 -- @class function
 211 -- @name Cursor.revert
 212 -- @param config        UCI config
 213 -- @return                      Boolean whether operation succeeded
 214 -- @see Cursor.commit
 215
 216 --- Saves changes made to a config to make them committable.
 217 -- @class function
 218 -- @name Cursor.save
 219 -- @param config        UCI config
 220 -- @return                      Boolean whether operation succeeded
 221 -- @see Cursor.load
 222 -- @see Cursor.unload
 223
 224 --- Set a value or create a named section.
 225 -- @class function
 226 -- @name Cursor.set
 227 -- @param config        UCI config
 228 -- @param section       UCI section name
 229 -- @param option        UCI option or UCI section type
 230 -- @param value         UCI value or nil if you want to create a section
 231 -- @return                      Boolean whether operation succeeded
 232
 233 --- Get the configuration directory.
 234 -- @class function
 235 -- @name Cursor.get_confdir
 236 -- @return                      Configuration directory
 237
 238 --- Get the directory for uncomitted changes.
 239 -- @class function
 240 -- @name Cursor.get_savedir
 241 -- @return                      Save directory
 242
 243 --- Set the configuration directory.
 244 -- @class function
 245 -- @name Cursor.set_confdir
 246 -- @param directory     UCI configuration directory
 247 -- @return                      Boolean whether operation succeeded
 248
 249 --- Set the directory for uncommited changes.
 250 -- @class function
 251 -- @name Cursor.set_savedir
 252 -- @param directory     UCI changes directory
 253 -- @return                      Boolean whether operation succeeded
 254
 255 --- Discard changes made to a config.
 256 -- @class function
 257 -- @name Cursor.unload
 258 -- @param config        UCI config
 259 -- @return                      Boolean whether operation succeeded
 260 -- @see Cursor.load
 261 -- @see Cursor.save