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