libs/uci/luasrc/model/uci.lua

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