path: root/modules/luci-base/luasrc/model/uci.luadoc

---[[
LuCI UCI model library.

The typical workflow for UCI is:  Get a cursor instance from the
cursor factory, modify data (via Cursor.add, Cursor.delete, etc.),
save the changes to the staging area via Cursor.save and finally
Cursor.commit the data to the actual config files.
LuCI then needs to Cursor.apply the changes so deamons etc. are
reloaded.
@cstyle	instance
]]
module "luci.model.uci"

---[[
Create a new UCI-Cursor.

@class function
@name cursor
@return	UCI-Cursor
]]

---[[
Create a new Cursor initialized to the state directory.

@class function
@name cursor_state
@return UCI cursor
]]

---[[
Applies UCI configuration changes

@class function
@name Cursor.apply
@param configlist		List of UCI configurations
@param command			Don't apply only return the command
]]

---[[
Delete all sections of a given type that match certain criteria.

@class function
@name Cursor.delete_all
@param config		UCI config
@param type			UCI section type
@param comparator	Function that will be called for each section and
returns a boolean whether to delete the current section (optional)
]]

---[[
Create a new section and initialize it with data.

@class function
@name Cursor.section
@param config	UCI config
@param type		UCI section type
@param name		UCI section name (optional)
@param values	Table of key - value pairs to initialize the section with
@return			Name of created section
]]

---[[
Updated the data of a section using data from a table.

@class function
@name Cursor.tset
@param config	UCI config
@param section	UCI section name (optional)
@param values	Table of key - value pairs to update the section with
]]

---[[
Get a boolean option and return it's value as true or false.

@class function
@name Cursor.get_bool
@param config	UCI config
@param section	UCI section name
@param option	UCI option
@return			Boolean
]]

---[[
Get an option or list and return values as table.

@class function
@name Cursor.get_list
@param config	UCI config
@param section	UCI section name
@param option	UCI option
@return		table.  If the option was not found, you will simply get
--		an empty table.
]]

---[[
Get the given option from the first section with the given type.

@class function
@name Cursor.get_first
@param config	UCI config
@param type		UCI section type
@param option	UCI option (optional)
@param default	Default value (optional)
@return			UCI value
]]

---[[
Set given values as list. Setting a list option to an empty list
has the same effect as deleting the option.

@class function
@name Cursor.set_list
@param config	UCI config
@param section	UCI section name
@param option	UCI option
@param value	value or table. Raw values will become a single item table.
@return			Boolean whether operation succeeded
]]

---[[
Create a sub-state of this cursor. The sub-state is tied to the parent

curser, means it the parent unloads or loads configs, the sub state will
do so as well.
@class function
@name Cursor.substate
@return			UCI state cursor tied to the parent cursor
]]

---[[
Add an anonymous section.

@class function
@name Cursor.add
@param config	UCI config
@param type		UCI section type
@return			Name of created section
]]

---[[
Get a table of saved but uncommitted changes.

@class function
@name Cursor.changes
@param config	UCI config
@return			Table of changes
@see Cursor.save
]]

---[[
Commit saved changes.

@class function
@name Cursor.commit
@param config	UCI config
@return			Boolean whether operation succeeded
@see Cursor.revert
@see Cursor.save
]]

---[[
Deletes a section or an option.

@class function
@name Cursor.delete
@param config	UCI config
@param section	UCI section name
@param option	UCI option (optional)
@return			Boolean whether operation succeeded
]]

---[[
Call a function for every section of a certain type.

@class function
@name Cursor.foreach
@param config	UCI config
@param type		UCI section type
@param callback	Function to be called
@return			Boolean whether operation succeeded
]]

---[[
Get a section type or an option

@class function
@name Cursor.get
@param config	UCI config
@param section	UCI section name
@param option	UCI option (optional)
@return			UCI value
]]

---[[
Get all sections of a config or all values of a section.

@class function
@name Cursor.get_all
@param config	UCI config
@param section	UCI section name (optional)
@return			Table of UCI sections or table of UCI values
]]

---[[
Manually load a config.

@class function
@name Cursor.load
@param config	UCI config
@return			Boolean whether operation succeeded
@see Cursor.save
@see Cursor.unload
]]

---[[
Revert saved but uncommitted changes.

@class function
@name Cursor.revert
@param config	UCI config
@return			Boolean whether operation succeeded
@see Cursor.commit
@see Cursor.save
]]

---[[
Saves changes made to a config to make them committable.

@class function
@name Cursor.save
@param config	UCI config
@return			Boolean whether operation succeeded
@see Cursor.load
@see Cursor.unload
]]

---[[
Set a value or create a named section.

When invoked with three arguments `config`, `sectionname`, `sectiontype`,
then a named section of the given type is created.

When invoked with four arguments `config`, `sectionname`, `optionname` and
`optionvalue` then the value of the specified option is set to the given value.

@class function
@name Cursor.set
@param config	UCI config
@param section	UCI section name
@param option	UCI option or UCI section type
@param value		UCI value or nothing if you want to create a section
@return			Boolean whether operation succeeded
]]

---[[
Get the configuration directory.

@class function
@name Cursor.get_confdir
@return			Configuration directory
]]

---[[
Get the directory for uncomitted changes.

@class function
@name Cursor.get_savedir
@return			Save directory
]]

---[[
Set the configuration directory.

@class function
@name Cursor.set_confdir
@param directory	UCI configuration directory
@return			Boolean whether operation succeeded
]]

---[[
Set the directory for uncommited changes.

@class function
@name Cursor.set_savedir
@param directory	UCI changes directory
@return			Boolean whether operation succeeded
]]

---[[
Discard changes made to a config.

@class function
@name Cursor.unload
@param config	UCI config
@return			Boolean whether operation succeeded
@see Cursor.load
@see Cursor.save
]]