darktable/lua-scripts-w-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Moved lib/libLog.lua to lib/dtutils/log.lua. Rewrote most of it to make it more configurable and easier to use. Updated doc format to a fixed list of fields. Did away with the comment blocks and just relying on the libdoc comments. Update doc tools to use new formats. Moved dtutils/extensions.lua to dtutils/string.lua. Pulled dtutils/processor.lua back for now since there is no context for it. Removed unneeded functions and cleaned up others.

Browse Source
This commit is contained in:
Bill Ferguson
2016-10-20 01:19:54 -04:00
parent a254ac87f7
commit 564fd20f23
10 changed files with 654 additions and 1461 deletions
Download Patch File Download Diff File Expand all files Collapse all files

357
lib/dtutils.lua
View File

@@ -1,33 +1,16 @@
--[[
dtutils.lua - common darktable lua functions
Copyright (C) 2016 Bill Ferguson <wpferguson@gmail.com>.
Copyright (C) 2016 Tobias Jakobs
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
]]
local dtutils = {}
dtutils.libdoc = {
Sections = {"Name", "Synopsis", "Description", "See_Also", "License"},
Name = [[dtutils - A Darktable lua utilities library]],
Synopsis = [[local du = require "lib/dtutils"]],
Name = [[dtutils]],
Synopsis = [[A Darktable lua utilities library]],
Usage = [[local du = require "lib/dtutils"]],
Description = [[dtutils provides a common library of functions used to build
lua scripts. There are also sublibraries that provide more functions.]],
See_Also = [[dtutils.debug(3), dtutils.extensionts(3), dtutils.file(3), dtutils.processor(3)]],
Return_Value = [[du - library - the library of functions]],
Limitations = [[]],
Example = [[]],
See_Also = [[dtutils.debug(3), dtutils.file(3), dtutils.log(3), dtutils.string(3)]],
Reference = [[]],
License = [[This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
@@ -40,57 +23,40 @@ dtutils.libdoc = {
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.]],
Copyright = [[Copyright (C) 2016 Bill Ferguson <wpferguson@gmail.com>.
Copyright (C) 2016 Tobias Jakobs]],
functions = {}
}
local dt = require "darktable"
local log = require "lib/libLog"
local log = require "lib/dtutils.log"
dt.configuration.check_version(...,{3,0,0})
--[[
NAME
split - split a string on a specified separator
SYNOPSIS
local du = require "lib/dtutils"
local result = du.split(str, pat)
str - string - the string to split
pat - string - the pattern to split on
DESCRIPTION
split separates a string into a table of strings. The strings are separated at each
occurrence of the supplied pattern.
RETURN VALUE
result - a table of strings on success, or an empty table on error
EXAMPLE
split("/a/long/path/name/to/a/file.txt", "/") would return a table like
{"a", "long", "path", "name", "to", "a", "file.txt"}
]]
dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value", "Example"},
Name = [[split - split a string on a specified separator]],
Synopsis = [[local du = require "lib/dtutils"
dtutils.libdoc.functions["split"] = {
Name = [[split]],
Synopsis = [[split a string on a specified separator]],
Usage = [[local du = require "lib/dtutils"
local result = du.split(str, pat)
str - string - the string to split
pat - string - the pattern to split on]],
Description = [[split separates a string into a table of strings. The strings are separated at each
occurrence of the supplied pattern.]],
occurrence of the supplied pattern. The pattern may be any pattern as described in the lua docs.
Each match of the pattern is consumed and not returned.]],
Return_Value = [[result - a table of strings on success, or an empty table on error]],
Limitations = [[]],
Example = [[split("/a/long/path/name/to/a/file.txt", "/") would return a table like
{"a", "long", "path", "name", "to", "a", "file.txt"}]],
{a, "long", "path", "name", "to", a, "file.txt"}]],
See_Also = [[]],
Reference = [[http://lua-users.org/wiki/SplitJoin]],
License = [[]],
Copyright = [[]],
}
-- Thanks to http://lua-users.org/wiki/SplitJoin
function dtutils.split(str, pat)
local t = {} -- NOTE: use {n = 0} in Lua-5.0
local t = {}
local fpat = "(.-)" .. pat
local last_end = 1
local s, e, cap = str:find(fpat, 1)
@@ -108,46 +74,26 @@ function dtutils.split(str, pat)
return t
end
--[[
NAME
join - join a table of strings with a specified separator
SYNOPSIS
local du = require "lib/dtutils"
local result = du.join(tabl, pat)
tabl - a table of strings
pat - a separator
DESCRIPTION
join assembles a table of strings into a string with the specified pattern
in between each string
RETURN VALUE
result - the joined string on success, or an empty string on failure
EXAMPLE
join({"a", "long", "path", "name", "to", "a", "file.txt"}, " ") would return the string
"a long path name to a file.txt"
]]
dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value", "Example"},
Name = [[join - join a table of strings with a specified separator]],
Synopsis = [[local du = require "lib/dtutils"
dtutils.libdoc.functions["join"] = {
Name = [[join]],
Synopsis = [[join a table of strings with a specified separator]],
Usage = [[local du = require "lib/dtutils"
local result = du.join(tabl, pat)
tabl - a table of strings
pat - a separator]],
Description = [[join assembles a table of strings into a string with the specified pattern
in between each string]],
Return_Value = [[result - the joined string on success, or an empty string on failure]],
Example = [[join({"a", "long", "path", "name", "to", "a", "file.txt"}, " ") would return the string
Return_Value = [[result - string - the joined string on success, or an empty string on failure]],
Limitations = [[]],
Example = [[join({a, "long", "path", "name", "to", a, "file.txt"}, " ") would return the string
"a long path name to a file.txt"]],
See_Also = [[]],
Reference = [[http://lua-users.org/wiki/SplitJoin]],
License = [[]],
Copyright = [[]],
}
-- Thanks to http://lua-users.org/wiki/SplitJoin
function dtutils.join(tabl, pat)
returnstr = ""
for i,str in pairs(tabl) do
@@ -178,17 +124,24 @@ end
]]
dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value", "Example"},
Name = [[prequire - a protected lua require]],
Synopsis = [[local du = require "lib/dtutils"
dtutils.libdoc.functions["prequire"] = {
Name = [[prequire]],
Synopsis = [[a protected lua require]],
Usage = [[local du = require "lib/dtutils"
local result = du.prequire(req_name)
local status, lib = du.prequire(req_name)
req_name - the filename of the lua code to load without the ".lua" filetype]],
Description = [[prequire is a protected require that can survive an error in the code being loaded without
bringing down the calling routine.]],
Return_Value = [[result - the code or true on success, otherwise an error message]],
Example = [[prequire("lib/dtutils.file") which would load lib/dtutils/file.lua]],
Return_Value = [[status - boolean - true on success
lib - if status is true, then the code, otherwise an error message]],
Limitations = [[]],
Example = [[local status, lib = prequire("lib/dtutils.file") which would load lib/dtutils/file.lua which
would return a status of true and the reference to the library in lib.]],
See_Also = [[]],
Reference = [[]],
License = [[]],
Copyright = [[]],
}
function dtutils.prequire(req_name)
@@ -198,165 +151,13 @@ function dtutils.prequire(req_name)
else
log.msg(log.info, "Error loading " .. req_name)
end
return lib
return status, lib
end
--[[
NAME
push - push a value on a stack
SYNOPSIS
local du = require "lib/dtutils"
du.push(stack, value)
stack - table - a table being used as the stack
value - any type - the value to be put on the stack
DESCRIPTION
Push a value on a stack
RETURN VALUE
none
]]
dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[push - push a value on a stack]],
Synopsis = [[local du = require "lib/dtutils"
du.push(stack, value)
stack - table - a table being used as the stack
value - any type - the value to be put on the stack]],
Description = [[Push a value on a stack]],
Return_Value = [[none]],
}
dtutils.push = table.insert
--[[
NAME
pop - pop a value from a stack
SYNOPSIS
local du = require "lib/dtutils"
local result = du.pop(stack)
stack - table - a table being used as a stack
DESCRIPTION
Remove the last value pushed on the stack and return it
RETURN VALUE
result = nil if stack isn't a table or the stack is empty, otherwise the value removed from the stack
]]
dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[pop - pop a value from a stack]],
Synopsis = [[local du = require "lib/dtutils"
local result = du.pop(stack)
stack - table - a table being used as a stack]],
Description = [[Remove the last value pushed on the stack and return it]],
Return_Value = [[result = nil if stack isn't a table or the stack is empty, otherwise the value removed from the stack]],
}
dtutils.pop = table.remove
--[[
NAME
update_combobox_choices - change the list of choices in a combobox
SYNOPSIS
local du = require "lib/dtutils"
du.update_combobox_choices(combobox_widget, choice_table)
combobox_widget - lua_combobox - a combobox widget
choice_table - table - a table of strings for the combobox choices
DESCRIPTION
Set the combobox choices to the supplied list. Remove any extra choices from the end
RETURN VALUE
none
]]
dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[update_combobox_choices - change the list of choices in a combobox]],
Synopsis = [[local du = require "lib/dtutils"
du.update_combobox_choices(combobox_widget, choice_table)
combobox_widget - lua_combobox - a combobox widget
choice_table - table - a table of strings for the combobox choices]],
Description = [[Set the combobox choices to the supplied list. Remove any extra choices from the end]],
Return_Value = [[none]],
}
function dtutils.update_combobox_choices(combobox, choice_table)
local items = #combobox
local choices = #choice_table
for i, name in ipairs(choice_table) do
log.msg(log.debug, "Setting choice " .. i .. " to " .. name)
combobox[i] = name
end
if choices < items then
for j = items, choices + 1, -1 do
log.msg(log.debug, "Removing choice " .. j)
combobox[j] = nil
end
end
combobox.value = 1
end
--[[
NAME
spairs - an iterator that provides sorted pairs from a table
SYNOPSIS
local du = require "lib/dtutils"
for key, value in du.spairs(t, order) do
t - table - table of key, value pairs
order - function - an optional function to sort the pairs
if none is supplied, table.sort() is used
DESCIRPTION
spairs is an iterator that returns key, value pairs from a table in sorted
order. The sorting order is the result of table.sort() if no function is
supplied, otherwise sorting is done as specified in the function.
EXAMPLE
HighScore = { Robin = 8, Jon = 10, Max = 11 }
-- basic usage, just sort by the keys
for k,v in spairs(HighScore) do
print(k,v)
end
--> Jon 10
--> Max 11
--> Robin 8
-- this uses an custom sorting function ordering by score descending
for k,v in spairs(HighScore, function(t,a,b) return t[b] < t[a] end) do
print(k,v)
end
--> Max 11
--> Jon 10
--> Robin 8
REFERENCE
Code copied from http://stackoverflow.com/questions/15706270/sort-a-table-in-lua
]]
dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Example", "Reference"},
Name = [[spairs - an iterator that provides sorted pairs from a table]],
Synopsis = [[local du = require "lib/dtutils"
dtutils.libdoc.functions["spairs"] = {
Name = [[spairs]],
Synopsis = [[an iterator that provides sorted pairs from a table]],
Usage = [[local du = require "lib/dtutils"
for key, value in du.spairs(t, order) do
t - table - table of key, value pairs
@@ -365,6 +166,8 @@ dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Description = [[spairs is an iterator that returns key, value pairs from a table in sorted
order. The sorting order is the result of table.sort() if no function is
supplied, otherwise sorting is done as specified in the function.]],
Return_Value = [[]],
Limitations = [[]],
Example = [[HighScore = { Robin = 8, Jon = 10, Max = 11 }
-- basic usage, just sort by the keys
@@ -382,7 +185,10 @@ dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
--> Max 11
--> Jon 10
--> Robin 8]],
See_Also = [[]],
Reference = [[Code copied from http://stackoverflow.com/questions/15706270/sort-a-table-in-lua]],
License = [[]],
Copyright = [[]],
}
-- Sort a table
@@ -409,49 +215,4 @@ function dtutils.spairs(_table, order) -- Code copied from http://stackoverflow.
end
end
--[[
NAME
urlencode - encode a string in a websage manner
SYNOPOIS
local du = require "lib/dtutils"
local result = du.urlencode(str)
str - string - the string that needs to be made websafe
DESCRIPTION
urlencode converts a string into a websafe version suitable for
use in a web browser.
RETURN_VALUE
result - string - a websafe string
REFERENCE
https://forums.coronalabs.com/topic/43048-remove-special-characters-from-string/
]]
dtutils.libdoc.functions[#dtutils.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value", "Reference"},
Name = [[urlencode - encode a string in a websage manner]],
Synopsis = [[local du = require "lib/dtutils"
local result = du.urlencode(str)
str - string - the string that needs to be made websafe]],
Description = [[urlencode converts a string into a websafe version suitable for
use in a web browser.]],
Return_Value = [[result - string - a websafe string]],
Reference = [[https://forums.coronalabs.com/topic/43048-remove-special-characters-from-string/]],
}
function dtutils.urlencode(str)
if (str) then
str = string.gsub (str, "\n", "\r\n")
str = string.gsub (str, "([^%w ])", function () return string.format ("%%%02X", string.byte()) end)
str = string.gsub (str, " ", "+")
end
return str
end
return dtutils