From e068351a3f5bf63ed85cd5d67a4a71048c5c0f60 Mon Sep 17 00:00:00 2001 From: Steven Barth Date: Fri, 29 Aug 2008 15:47:56 +0000 Subject: [PATCH] Cleanup and documentation --- libs/core/luasrc/ltn12.lua | 109 +++++++++++++++++++++++---- libs/ipkg/luasrc/model/ipkg.lua | 158 +++++++++++++++++++++------------------- libs/uci/luasrc/model/uci.lua | 6 +- 3 files changed, 180 insertions(+), 93 deletions(-) diff --git a/libs/core/luasrc/ltn12.lua b/libs/core/luasrc/ltn12.lua index a6ce11bf1..c9b663463 100644 --- a/libs/core/luasrc/ltn12.lua +++ b/libs/core/luasrc/ltn12.lua @@ -20,6 +20,11 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ]]-- +--[[ + Changes made by LuCI project: + * Renamed to luci.ltn12 to avoid collisions with luasocket + * Added inline documentation +]]-- ----------------------------------------------------------------------------- -- LTN12 - Filters, sources, sinks and pumps. -- LuaSocket toolkit. @@ -33,6 +38,9 @@ DEALINGS IN THE SOFTWARE. local string = require("string") local table = require("table") local base = _G + +--- Diego Nehab's LTN12 - Filters, sources, sinks and pumps. +-- See http://lua-users.org/wiki/FiltersSourcesAndSinks for design concepts module("luci.ltn12") filter = {} @@ -47,7 +55,17 @@ _VERSION = "LTN12 1.0.1" ----------------------------------------------------------------------------- -- Filter stuff ----------------------------------------------------------------------------- --- returns a high level filter that cycles a low-level filter + +--- LTN12 Filter constructors +-- @class module +-- @name luci.ltn12.filter + +--- Return a high level filter that cycles a low-level filter +-- by passing it each chunk and updating a context between calls. +-- @param low Low-level filter +-- @param ctx Context +-- @param extra Extra argument passed to the low-level filter +-- @return LTN12 filter function filter.cycle(low, ctx, extra) base.assert(low) return function(chunk) @@ -57,8 +75,10 @@ function filter.cycle(low, ctx, extra) end end --- chains a bunch of filters together +--- Chain a bunch of filters together. -- (thanks to Wim Couwenberg) +-- @param ... filters to be chained +-- @return LTN12 filter function filter.chain(...) local n = table.getn(arg) local top, index = 1, 1 @@ -91,23 +111,35 @@ end ----------------------------------------------------------------------------- -- Source stuff ----------------------------------------------------------------------------- + +--- LTN12 Source constructors +-- @class module +-- @name luci.ltn12.source + -- create an empty source local function empty() return nil end +--- Create an empty source. +-- @return LTN12 source function source.empty() return empty end --- returns a source that just outputs an error +--- Return a source that just outputs an error. +-- @param err Error object +-- @return LTN12 source function source.error(err) return function() return nil, err end end --- creates a file source +--- Create a file source. +-- @param handle File handle ready for reading +-- @param io_err IO error object +-- @return LTN12 source function source.file(handle, io_err) if handle then return function() @@ -118,7 +150,9 @@ function source.file(handle, io_err) else return source.error(io_err or "unable to open file") end end --- turns a fancy source into a simple source +--- Turn a fancy source into a simple source. +-- @param src fancy source +-- @return LTN12 source function source.simplify(src) base.assert(src) return function() @@ -129,7 +163,9 @@ function source.simplify(src) end end --- creates string source +--- Create a string source. +-- @param s Data +-- @return LTN12 source function source.string(s) if s then local i = 1 @@ -142,7 +178,9 @@ function source.string(s) else return source.empty() end end --- creates rewindable source +--- Creates rewindable source. +-- @param src LTN12 source to be made rewindable +-- @return LTN12 source function source.rewind(src) base.assert(src) local t = {} @@ -157,6 +195,10 @@ function source.rewind(src) end end +--- Chain a source and a filter together. +-- @param src LTN12 source +-- @param f LTN12 filter +-- @return LTN12 source function source.chain(src, f) base.assert(src and f) local last_in, last_out = "", "" @@ -204,9 +246,11 @@ function source.chain(src, f) end end --- creates a source that produces contents of several sources, one after the --- other, as if they were concatenated +--- Create a source that produces contents of several sources. +-- Sources will be used one after the other, as if they were concatenated -- (thanks to Wim Couwenberg) +-- @param ... LTN12 sources +-- @return LTN12 source function source.cat(...) local src = table.remove(arg, 1) return function() @@ -222,7 +266,14 @@ end ----------------------------------------------------------------------------- -- Sink stuff ----------------------------------------------------------------------------- --- creates a sink that stores into a table + +--- LTN12 sink constructors +-- @class module +-- @name luci.ltn12.sink + +--- Create a sink that stores into a table. +-- @param t output table to store into +-- @return LTN12 sink function sink.table(t) t = t or {} local f = function(chunk, err) @@ -232,7 +283,9 @@ function sink.table(t) return f, t end --- turns a fancy sink into a simple sink +--- Turn a fancy sink into a simple sink. +-- @param snk fancy sink +-- @return LTN12 sink function sink.simplify(snk) base.assert(snk) return function(chunk, err) @@ -243,7 +296,10 @@ function sink.simplify(snk) end end --- creates a file sink +--- Create a file sink. +-- @param handle file handle to write to +-- @param io_err IO error +-- @return LTN12 sink function sink.file(handle, io_err) if handle then return function(chunk, err) @@ -260,18 +316,25 @@ local function null() return 1 end +--- Create a sink that discards data. +-- @return LTN12 sink function sink.null() return null end --- creates a sink that just returns an error +--- Create a sink that just returns an error. +-- @param err Error object +-- @return LTN12 sink function sink.error(err) return function() return nil, err end end --- chains a sink with a filter +--- Chain a sink with a filter. +-- @param f LTN12 filter +-- @param snk LTN12 sink +-- @return LTN12 sink function sink.chain(f, snk) base.assert(f and snk) return function(chunk, err) @@ -291,7 +354,16 @@ end ----------------------------------------------------------------------------- -- Pump stuff ----------------------------------------------------------------------------- --- pumps one chunk from the source to the sink + +--- LTN12 pump functions +-- @class module +-- @name luci.ltn12.pump + +--- Pump one chunk from the source to the sink. +-- @param src LTN12 source +-- @param snk LTN12 sink +-- @return Chunk of data or nil if an error occured +-- @return Error object function pump.step(src, snk) local chunk, src_err = src() local ret, snk_err = snk(chunk, src_err) @@ -299,7 +371,12 @@ function pump.step(src, snk) else return nil, src_err or snk_err end end --- pumps all data from a source to a sink, using a step function +--- Pump all data from a source to a sink, using a step function. +-- @param src LTN12 source +-- @param snk LTN12 sink +-- @param step step function (optional) +-- @return 1 if the operation succeeded otherwise nil +-- @return Error object function pump.all(src, snk, step) base.assert(src and snk) step = step or pump.step diff --git a/libs/ipkg/luasrc/model/ipkg.lua b/libs/ipkg/luasrc/model/ipkg.lua index 4c2716a38..97d0c1932 100644 --- a/libs/ipkg/luasrc/model/ipkg.lua +++ b/libs/ipkg/luasrc/model/ipkg.lua @@ -1,75 +1,33 @@ --[[ -LuCI - IPKG wrapper library +LuCI - Lua Configuration Interface -Description: -Wrapper for the ipkg Package manager - -Any return value of false or nil can be interpreted as an error - -FileId: -$Id$ - -License: -Copyright 2008 Steven Barth +(c) 2008 Jo-Philipp Wich +(c) 2008 Steven Barth Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 +You may obtain a copy of the License at -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +http://www.apache.org/licenses/LICENSE-2.0 +$Id$ ]]-- -module("luci.model.ipkg", package.seeall) -require("luci.util") -require("luci.fs") - -ipkg = luci.fs.access("/bin/opkg") and "opkg" or "ipkg" - --- Returns repository information -function info(pkg) - return _lookup("info", pkg) -end - --- Returns a table with status information -function status(pkg) - return _lookup("status", pkg) -end - --- Installs packages -function install(...) - return _action("install", ...) -end --- Returns whether a package is installed -function installed(pkg, ...) - local p = status(...)[pkg] - return (p and p.Status and p.Status.installed) -end +local os = require "os" +local util = require "luci.util" --- Removes packages -function remove(...) - return _action("remove", ...) -end +local type = type +local pairs = pairs +local error = error --- Updates package lists -function update() - return _action("update") -end +local ipkg = "opkg" --- Upgrades installed packages -function upgrade() - return _action("upgrade") -end +--- LuCI IPKG/OPKG call abstraction library +module "luci.model.ipkg" -- Internal action function -function _action(cmd, ...) +local function _action(cmd, ...) local pkg = "" arg.n = nil for k, v in pairs(arg) do @@ -81,39 +39,29 @@ function _action(cmd, ...) return (r == 0), r end --- Internal lookup function -function _lookup(act, pkg) - local cmd = ipkg .. " " .. act - if pkg then - cmd = cmd .. " '" .. pkg:gsub("'", "") .. "'" - end - - return _parselist(luci.util.exec(cmd .. " 2>/dev/null")) -end - -- Internal parser function -function _parselist(rawdata) +local function _parselist(rawdata) if type(rawdata) ~= "string" then error("IPKG: Invalid rawdata given") end - rawdata = luci.util.split(rawdata) + rawdata = util.split(rawdata) local data = {} local c = {} local l = nil for k, line in pairs(rawdata) do if line:sub(1, 1) ~= " " then - local split = luci.util.split(line, ":", 1) + local split = util.split(line, ":", 1) local key = nil local val = nil if split[1] then - key = luci.util.trim(split[1]) + key = util.trim(split[1]) end if split[2] then - val = luci.util.trim(split[2]) + val = util.trim(split[2]) end if key and val then @@ -137,4 +85,68 @@ function _parselist(rawdata) end return data -end \ No newline at end of file +end + +-- Internal lookup function +local function _lookup(act, pkg) + local cmd = ipkg .. " " .. act + if pkg then + cmd = cmd .. " '" .. pkg:gsub("'", "") .. "'" + end + + return _parselist(util.exec(cmd .. " 2>/dev/null")) +end + + +--- Return information about installed and available packages. +-- @param pkg Limit output to a (set of) packages +-- @return Table containing package information +function info(pkg) + return _lookup("info", pkg) +end + +--- Return the package status of one or more packages. +-- @param pkg Limit output to a (set of) packages +-- @return Table containing package status information +function status(pkg) + return _lookup("status", pkg) +end + +--- Install one or more packages. +-- @param ... List of packages to install +-- @return Boolean indicating the status of the action +-- @return IPKG return code +function install(...) + return _action("install", ...) +end + +--- Determine whether a given package is installed. +-- @param pkg Package +-- @return Boolean +function installed(pkg) + local p = status(pkg)[pkg] + return (p and p.Status and p.Status.installed) +end + +--- Remove one or more packages. +-- @param ... List of packages to install +-- @return Boolean indicating the status of the action +-- @return IPKG return code +function remove(...) + return _action("remove", ...) +end + +--- Update package lists. +-- @return Boolean indicating the status of the action +-- @return IPKG return code +function update() + return _action("update") +end + +--- Upgrades all installed packages. +-- @return Boolean indicating the status of the action +-- @return IPKG return code +function upgrade() + return _action("upgrade") +end + diff --git a/libs/uci/luasrc/model/uci.lua b/libs/uci/luasrc/model/uci.lua index 7fc0c79fd..3b135c532 100644 --- a/libs/uci/luasrc/model/uci.lua +++ b/libs/uci/luasrc/model/uci.lua @@ -34,6 +34,7 @@ local error, pairs, ipairs, tostring = error, pairs, ipairs, tostring local require, getmetatable = require, getmetatable --- LuCI UCI model library. +-- @cstyle instance module("luci.model.uci") --- Create a new UCI-Cursor. @@ -50,10 +51,7 @@ function cursor_state() return cursor(nil, "/var/state") end ---- UCI-Cursor --- @class module --- @cstyle instance --- @name luci.model.uci.Cursor + local Cursor = getmetatable(cursor()) --- Applies the new config -- 2.11.0