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