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 setmetatable, rawget, rawset = setmetatable, rawget, rawset
  29 local error, pairs, ipairs, tostring = error, pairs, ipairs, tostring
  30 local table = table
  31
  32 --- LuCI UCI model library.
  33 module("luci.model.uci", function(m) setmetatable(m, {__index = uci}) end)
  34
  35 savedir_default = "/tmp/.uci"
  36 confdir_default = "/etc/config"
  37
  38 savedir_state = "/var/state"
  39
  40 --- Delete all sections of a given type that match certain criteria.
  41 -- @param config                UCI config
  42 -- @param type                  UCI section type
  43 -- @param comparator    Function that will be called for each section and
  44 -- returns a boolean whether to delete the current section (optional)
  45 function delete_all(config, type, comparator)
  46         local del = {}
  47         local function helper (section)
  48                         if not comparator or comparator(section) then
  49                                 table.insert(del, section[".name"])
  50                         end
  51         end
  52
  53         foreach(config, type, helper)
  54
  55         for i, j in ipairs(del) do
  56                 delete(config, j)
  57         end
  58 end
  59
  60 --- Create a new section and initialize it with data.
  61 -- @param config        UCI config
  62 -- @param type          UCI section type
  63 -- @param name          UCI section name (optional)
  64 -- @param values        Table of key - value pairs to initialize the section with
  65 -- @return                      Name of created section
  66 function section(config, type, name, values)
  67         local stat = true
  68         if name then
  69                 stat = set(config, name, type)
  70         else
  71                 name = add(config, type)
  72                 stat = name and true
  73         end
  74
  75         if stat and values then
  76                 stat = tset(config, name, values)
  77         end
  78
  79         return stat and name
  80 end
  81
  82 --- Savely load the configuration.
  83 -- @param config        Configuration to load
  84 -- @return                      Sucess status
  85 -- @see                         load_state
  86 -- @see                         load
  87 function load_config(...)
  88         set_confdir(confdir_default)
  89         set_savedir(savedir_default)
  90         return load(...)
  91 end
  92
  93 --- Savely load state values.
  94 -- @param config        Configuration to load
  95 -- @return                      Sucess status
  96 -- @see                         load_config
  97 -- @see                         load
  98 function load_state(config)
  99         set_confdir(confdir_default)
 100         set_savedir(savedir_state)
 101         return load(config)
 102 end
 103
 104 --- Save changes to config values.
 105 -- @param config        Configuration to save
 106 -- @return                      Sucess status
 107 -- @see                         save_state
 108 -- @see                         save
 109 function save_config(config)
 110         set_savedir(savedir_default)
 111         return save(config)
 112 end
 113
 114 --- Save changes to state values.
 115 -- @param config        Configuration to save
 116 -- @return                      Sucess status
 117 -- @see                         save_config
 118 -- @see                         save
 119 function save_state(config)
 120         set_savedir(savedir_state)
 121         return save(config)
 122 end
 123
 124 --- Updated the data of a section using data from a table.
 125 -- @param config        UCI config
 126 -- @param section       UCI section name (optional)
 127 -- @param values        Table of key - value pairs to update the section with
 128 function tset(config, section, values)
 129         local stat = true
 130         for k, v in pairs(values) do
 131                 if k:sub(1, 1) ~= "." then
 132                         stat = stat and set(config, section, k, v)
 133                 end
 134         end
 135         return stat
 136 end
 137
 138 --- Get an option or list and return values as table.
 139 -- @param config        UCI config
 140 -- @param section       UCI section name
 141 -- @param option        UCI option
 142 -- @return                      UCI value
 143 function get_list(config, section, option)
 144         if config and section and option then
 145                 local val = get(config, section, option)
 146                 return ( type(val) == "table" and val or { val } )
 147         end
 148         return nil
 149 end
 150
 151 --- Set given values as list.
 152 -- Warning: This function is unsave! You should use save_config or save_state if possible.
 153 -- @param config        UCI config
 154 -- @param section       UCI section name
 155 -- @param option        UCI option
 156 -- @param value         UCI value
 157 -- @return                      Boolean whether operation succeeded
 158 function set_list(config, section, option, value)
 159         if config and section and option then
 160                 return set(
 161                         config, section, option,
 162                         ( type(value) == "table" and value or { value } )
 163                 )
 164         end
 165         return false
 166 end
 167
 168
 169 --- Add an anonymous section.
 170 -- @class function
 171 -- @name 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 changes
 179 -- @param config        UCI config
 180 -- @return                      Table of changes
 181
 182 --- Commit unsaved changes.
 183 -- @class function
 184 -- @name commit
 185 -- @param config        UCI config
 186 -- @return                      Boolean whether operation succeeded
 187 -- @see revert
 188
 189 --- Deletes a section or an option.
 190 -- @class function
 191 -- @name 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 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 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 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 -- Warning: This function is unsave! You should use load_config or load_state if possible.
 222 -- @class function
 223 -- @name load
 224 -- @param config        UCI config
 225 -- @return                      Boolean whether operation succeeded
 226 -- @see load_config
 227 -- @see load_state
 228 -- @see save
 229 -- @see unload
 230
 231 --- Revert unsaved changes.
 232 -- @class function
 233 -- @name revert
 234 -- @param config        UCI config
 235 -- @return                      Boolean whether operation succeeded
 236 -- @see commit
 237
 238 --- Saves changes made to a config to make them committable.
 239 -- @class function
 240 -- @name save
 241 -- @param config        UCI config
 242 -- @return                      Boolean whether operation succeeded
 243 -- @see load
 244 -- @see unload
 245
 246 --- Set a value or create a named section.
 247 -- Warning: This function is unsave! You should use save_config or save_state if possible.
 248 -- @class function
 249 -- @name set
 250 -- @param config        UCI config
 251 -- @param section       UCI section name
 252 -- @param option        UCI option or UCI section type
 253 -- @param value         UCI value or nil if you want to create a section
 254 -- @return                      Boolean whether operation succeeded
 255
 256 --- Set the configuration directory.
 257 -- @class function
 258 -- @name set_confdir
 259 -- @param directory     UCI configuration directory
 260 -- @return                      Boolean whether operation succeeded
 261
 262 --- Set the directory for uncommited changes.
 263 -- @class function
 264 -- @name set_savedir
 265 -- @param directory     UCI changes directory
 266 -- @return                      Boolean whether operation succeeded
 267
 268 --- Discard changes made to a config.
 269 -- @class function
 270 -- @name unload
 271 -- @param config        UCI config
 272 -- @return                      Boolean whether operation succeeded
 273 -- @see load
 274 -- @see save