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

Created libraries from commonly used functions. Moved official/debug-helpers.lua into lib/dtutils/debug.lua. Created a logging library to provide various levels of logging. Documented all libraries and functions. Created tools to extract documentation in text, man page, and pdf formats.

Browse Source
This commit is contained in:
Bill Ferguson
2016-10-15 01:47:43 -04:00
parent e74b253f64
commit a254ac87f7
10 changed files with 2160 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
lib/dtutils/de_DE/LC_MESSAGES/dtutils.processor.po Normal file
View File

@@ -0,0 +1,23 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2016-10-01 00:36-0400\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: de_DE\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#: dtutils.processor.lua:42
#, lua-format
msgid "Export Image %i/%i"
msgstr "Exportiere Bild %i/%i"

219
lib/dtutils/debug.lua Normal file
View File

@@ -0,0 +1,219 @@
--[[
This file is part of darktable,
copyright (c) 2014 Jérémy Rosen
darktable 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.
darktable 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 darktable. If not, see <http://www.gnu.org/licenses/>.
]]
--[[
DEBUG HELPERS
A collection of helper functions to help debugging lua scripts.
require it as
dhelpers = require "official/debug-helpers"
Each function is documented in its own header
]]
local dt = require "darktable"
local io = require "io"
local table = require "table"
require "darktable.debug"
local log = require "lib/libLog"
local M = {} -- The actual content of the module
M.libdoc = {
Sections = {"Name", "Synopsis", "Description", "License"},
Name = [[dtutils.debug - debugging helpers used in developing darktable lua scripts]],
Synopsis = [[local dd = require "lib/dtutils.debug"]],
Description = [[dtutils.debug provides an interface to the darktable debugging routines.]],
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
(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/>.]],
functions = {}
}
--[[
NAME
tracepoint - print out a tracepoint and dump the arguments
SYNOPSIS
local dd = require "lib/dtutils.debug"
local result = tracepoint(name, ...)
name - string - the name of the tracepoint to print out
... - arguments - variables to dump the contents of
DESCRIPTION
tracepoint prints its name and dumps its parameters using
dt.debug
RETURN VALUE
result - ... - the supplied argument list
]]
M.libdoc.functions[#M.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[tracepoint - print out a tracepoint and dump the arguments]],
Synopsis = [[local dd = require "lib/dtutils.debug"
local result = tracepoint(name, ...)
name - string - the name of the tracepoint to print out
... - arguments - variables to dump the contents of]],
Description = [[tracepoint prints its name and dumps its parameters using
dt.debug]],
Return_Value = [[result - ... - the supplied argument list]],
}
function M.tracepoint(name,...)
log.always(4, "***** "..name.." ****")
params = {...}
print(dt.debug.dump(params,"parameters"))
return ...;
end
--[[
NAME
new_tracepoint - create a function returning a tracepoint
SYNOPSIS
local dd = require "lib/dtutils.debug"
local result = new_tracepoint(name, ...)
name - string - the name of the tracepoint to print out
... - arguments - variables to dump the contents of
DESCRIPTION
A function that returns a tracepoint function with the given name
This is mainly used to debug callbacks.
RETURN VALUE
result - function - a function that returns the result of a tracepoint
EXAMPLE
register_event(event, dd.new_tracepoint("hit callback"))
will print the following each time the callback is called
**** hit callback ****
<all the callback's parameters dumped>
]]
M.libdoc.functions[#M.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value", "Example"},
Name = [[new_tracepoint - create a function returning a tracepoint]],
Synopsis = [[local dd = require "lib/dtutils.debug"
local result = new_tracepoint(name, ...)
name - string - the name of the tracepoint to print out
... - arguments - variables to dump the contents of]],
Description = [[A function that returns a tracepoint function with the given name
This is mainly used to debug callbacks.]],
Return_Value = [[result - function - a function that returns the result of a tracepoint]],
Example = [[register_event(event, dd.new_tracepoint("hit callback"))
will print the following each time the callback is called
**** hit callback ****
<all the callback's parameters dumped>]],
}
function M.new_tracepoint(name)
return function(...) return M.tracepoint(name,...) end
end
--[[
NAME
dprint - pass a variable to dt.debug.dump and print the results to stdout
SYNOPSIS
local dd = require "lib/dtutils.debug"
dd.dprint(var)
var - variable - any variable that you want to see the contents of
DESCRIPTION
Wrapper around debug.dump, will directly print to stdout,
same calling convention
]]
M.libdoc.functions[#M.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description"},
Name = [[dprint - pass a variable to dt.debug.dump and print the results to stdout]],
Synopsis = [[local dd = require "lib/dtutils.debug"
dd.dprint(var)
var - variable - any variable that you want to see the contents of]],
Description = [[Wrapper around debug.dump, will directly print to stdout,
same calling convention]],
}
function M.dprint(...)
log.always(4, dt.debug.dump(...))
end
--[[
NAME
terse_dump - set dt.debug.known to shorten all image dumps to a single line
SYNOPSIS
local dd = require "lib/dtutils.debug"
dd.terse_dump()
DESCRIPTION
terse_dump sets dt.debug.known to shorten all images to a single line.
If you don't need to debug the content of images, this will avoid them flooding your logs
]]
M.libdoc.functions[#M.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description"},
Name = [[terse_dump - set dt.debug.known to shorten all image dumps to a single line]],
Synopsis = [[local dd = require "lib/dtutils.debug"
dd.terse_dump()]],
Description = [[terse_dump sets dt.debug.known to shorten all images to a single line.
If you don't need to debug the content of images, this will avoid them flooding your logs]],
}
function M.terse_dump()
for _,v in ipairs(dt.database) do
dt.debug.known[v] = tostring(v)
end
end
return M
-- vim: shiftwidth=2 expandtab tabstop=2 cindent
-- kate: tab-indents: off; indent-width 2; replace-tabs on; remove-trailing-space on;

185
lib/dtutils/extensions.lua Normal file
View File

@@ -0,0 +1,185 @@
--[[
NAME
dtutils/extensions.lua - a library of extenstions to the lua libraries
SYNOPSIS
require "lib/dtutils.extensions"
DESCRIPTION
This library contains extensions to the lua libraries.
]]
local dtutils_extensions = {}
dtutils_extensions.libdoc = {
Sections = {"Name", "Synopsis", "Description", "License"},
Name = "dtutils.extensions - a library of extenstions to the lua libraries",
Synopsis = [[require "lib/dtutils.extensions"]],
Description = [[This library contains extensions to the lua libraries.]],
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
(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/>.]],
functions = {}
}
--[[
NAME
string.strip_accents - strip accents from characters
SYNOPSIS
require "lib/dtutils.extensions"
result = string.strip_accents(str)
str - string - the string with characters that need accents removed
DESCRIPTION
strip_accents removes accents from accented characters returning the
unaccented character.
RETURN VALUE
result - string - the string containing unaccented characters
]]
dtutils_extensions.libdoc.functions[#dtutils_extensions.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[string.strip_accents - strip accents from characters]],
Synopsis = [[require "lib/dtutils.extensions"
result = string.strip_accents(str)
str - string - the string with characters that need accents removed]],
Description = [[strip_accents removes accents from accented characters returning the
unaccented character.]],
Return_Value = [[result - string - the string containing unaccented characters]],
}
-- Strip accents from a string
-- Copied from https://forums.coronalabs.com/topic/43048-remove-special-characters-from-string/
function string.strip_accents( str )
local tableAccents = {}
tableAccents["à"] = "a"
tableAccents["á"] = "a"
tableAccents["â"] = "a"
tableAccents["ã"] = "a"
tableAccents["ä"] = "a"
tableAccents["ç"] = "c"
tableAccents["è"] = "e"
tableAccents["é"] = "e"
tableAccents["ê"] = "e"
tableAccents["ë"] = "e"
tableAccents["ì"] = "i"
tableAccents["í"] = "i"
tableAccents["î"] = "i"
tableAccents["ï"] = "i"
tableAccents["ñ"] = "n"
tableAccents["ò"] = "o"
tableAccents["ó"] = "o"
tableAccents["ô"] = "o"
tableAccents["õ"] = "o"
tableAccents["ö"] = "o"
tableAccents["ù"] = "u"
tableAccents["ú"] = "u"
tableAccents["û"] = "u"
tableAccents["ü"] = "u"
tableAccents["ý"] = "y"
tableAccents["ÿ"] = "y"
tableAccents["À"] = "A"
tableAccents["Á"] = "A"
tableAccents["Â"] = "A"
tableAccents["Ã"] = "A"
tableAccents["Ä"] = "A"
tableAccents["Ç"] = "C"
tableAccents["È"] = "E"
tableAccents["É"] = "E"
tableAccents["Ê"] = "E"
tableAccents["Ë"] = "E"
tableAccents["Ì"] = "I"
tableAccents["Í"] = "I"
tableAccents["Î"] = "I"
tableAccents["Ï"] = "I"
tableAccents["Ñ"] = "N"
tableAccents["Ò"] = "O"
tableAccents["Ó"] = "O"
tableAccents["Ô"] = "O"
tableAccents["Õ"] = "O"
tableAccents["Ö"] = "O"
tableAccents["Ù"] = "U"
tableAccents["Ú"] = "U"
tableAccents["Û"] = "U"
tableAccents["Ü"] = "U"
tableAccents["Ý"] = "Y"
local normalizedString = ""
for strChar in string.gmatch(str, "([%z\1-\127\194-\244][\128-\191]*)") do
if tableAccents[strChar] ~= nil then
normalizedString = normalizedString..tableAccents[strChar]
else
normalizedString = normalizedString..strChar
end
end
return normalizedString
end
--[[
NAME
string.escape_xml_characters - escape characters for xml documents
SYNOPSIS
require "lib/dtutils.extensions"
result = string.escape_xml_characters(str)
str - string - the string that needs escaped
DESCRIPTION
escape_xml_characters provides the escape sequences for
"&", '"', "'", "<", and ">" with the corresponding "&amp;",
"&quot;", "&apos;", "&lt;", and "&gt;".
RETURNN VALUE
result - string - the string containing escapes for the xml characters
]]
dtutils_extensions.libdoc.functions[#dtutils_extensions.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = "string.escape_xml_characters - escape characters for xml documents",
Synopsis = [[ require "lib/dtutils.extensions"
result = string.escape_xml_characters(str)
str - string - the string that needs escaped]],
Description = [[escape_xml_characters provides the escape sequences for
"&", '"', "'", "<", and ">" with the corresponding "&amp;",
"&quot;", "&apos;", "&lt;", and "&gt;".]],
Return_Value = [[result - string - the string containing escapes for the xml characters]],
}
-- Escape XML characters
-- Keep &amp; first, otherwise it will double escape other characters
-- https://stackoverflow.com/questions/1091945/what-characters-do-i-need-to-escape-in-xml-documents
function string.escape_xml_characters( str )
str = string.gsub(str,"&", "&amp;")
str = string.gsub(str,"\"", "&quot;")
str = string.gsub(str,"'", "&apos;")
str = string.gsub(str,"<", "&lt;")
str = string.gsub(str,">", "&gt;")
return str
end
return dtutils_extensions

523
lib/dtutils/file.lua Normal file
View File

@@ -0,0 +1,523 @@
--[[
dtutils/file.lua - common darktable lua file 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_file = {}
dtutils_file.libdoc = {
Sections = {"Name", "Synopsis", "Description", "License"},
Name = [[dtutils.file - common darktable lua file functions]],
Synopsis = [[local df = require "lib/dtutils.file"]],
Description = [[dtutils.file provides common file manipulation functions used in
constructing Darktable lua scripts]],
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
(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/>.]],
functions = {}
}
local dt = require "darktable"
local log = require "lib/libLog"
local gettext = dt.gettext
dt.configuration.check_version(...,{3,0,0})
-- Tell gettext where to find the .mo file translating messages for a particular domain
gettext.bindtextdomain("dtutils.file",dt.configuration.config_dir.."/lua/locale/")
local function _(msgid)
return gettext.dgettext("dtutils.file", msgid)
end
--[[
NAME
check_if_bin_exists - check if an executable is in the path
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.check_if_bin_exists(bin)
bin - string - the binary to check for
DESCRIPTION
check_if_bin_exists checks to see if the specified binary executable is
in the path.
RETURN VALUE
result - boolean - true if the executable was found, false if not
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[check_if_bin_exists - check if an executable is in the path]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.check_if_bin_exists(bin)
bin - string - the binary to check for]],
Description = [[check_if_bin_exists checks to see if the specified binary executable is
in the path.]],
Return_Value = [[result - boolean - true if the executable was found, false if not]],
}
function dtutils_file.check_if_bin_exists(bin)
local result = os.execute("which " .. bin)
if not result then
result = false
end
return result
end
--[[
NAME
split_filepath - split a filepath into parts
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.split_filepath(filepath)
filepath - string - path and filename
DESCRIPTION
split_filepath splits a filepath into the path, filename, basename and filetype and puts
that in a table
RETURN VALUE
result - table - a table containing the path, filename, basename, and filetype
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[split_filepath - split a filepath into parts]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.split_filepath(filepath)
filepath - string - path and filename]],
Description = [[split_filepath splits a filepath into the path, filename, basename and filetype and puts
that in a table]],
Return_Value = [[result - table - a table containing the path, filename, basename, and filetype]],
}
function dtutils_file.split_filepath(str)
local result = {}
-- Thank you Tobias Jakobs for the awesome regular expression, which I tweaked a little
result["path"], result["filename"], result["basename"], result["filetype"] = string.match(str, "(.-)(([^\\/]-)%.?([^%.\\/]*))$")
return result
end
--[[
NAME
get_path - get the path from a file path
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.get_path(filepath)
filepath - string - path and filename
DESCRIPTION
get_path strips the filename and filetype from a path and returns the path
RETURN VALUE
result - string - the path
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[get_path - get the path from a file path]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.get_path(filepath)
filepath - string - path and filename]],
Description = [[get_path strips the filename and filetype from a path and returns the path]],
Return_Value = [[result - string - the path]],
}
function dtutils_file.get_path(str)
local parts = dtutils_file.split_filepath(str)
return parts["path"]
end
--[[
NAME
get_filename - get the filename and extension from a file path
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.get_filename(filepath)
filepath - string - path and filename
DESCRIPTION
get_filename strips the path from a filepath and returns the filename
RETURN VALUE
result - string - the file name and type
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[get_filename - get the filename and extension from a file path]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.get_filename(filepath)
filepath - string - path and filename]],
Description = [[get_filename strips the path from a filepath and returns the filename]],
Return_Value = [[result - string - the file name and type]],
}
function dtutils_file.get_filename(str)
local parts = dtutils_file.split_filepath(str)
return parts["filename"]
end
--[[
NAME
get_basename - get the filename without the path or extension
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.get_basename(filepath)
filepath - string - path and filename
DESCRIPTION
get_basename returns the name of the file without the path or filetype
RETURN VALUE
result - string - the basename of the file
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[get_basename - get the filename without the path or extension]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.get_basename(filepath)
filepath - string - path and filename]],
Description = [[get_basename returns the name of the file without the path or filetype]],
Return_Value = [[result - string - the basename of the file]],
}
function dtutils_file.get_basename(str)
local parts = dtutils_file.split_filepath(str)
return parts["basename"]
end
--[[
NAME
get_filetype - get the filetype from a filename
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.get_filetype(filepath)
filepath - string - path and filename
DESCRIPTION
get_filetype returns the filetype from the supplied filepath
RETURN VALUE
result - string - the filetype
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[get_filetype - get the filetype from a filename]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.get_filetype(filepath)
filepath - string - path and filename]],
Description = [[get_filetype returns the filetype from the supplied filepath]],
Return_Value = [[result - string - the filetype]],
}
function dtutils_file.get_filetype(str)
local parts = dtutils_file.split_filepath(str)
return parts["filetype"]
end
--[[
NAME
check_if_file_exists - check if a file or path exist
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.check_if_file_exists(filepath)
filepath - string - a file or path to check
DESCRIPTION
check_if_file_exists checks to see if a file or path exists
RETURN VALUE
result - boolean - true if the file or path exists, false if it doesn't
]]
-- Thanks Tobias Jakobs for the idea
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[check_if_file_exists - check if a file or path exist]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.check_if_file_exists(filepath)
filepath - string - a file or path to check]],
Description = [[check_if_file_exists checks to see if a file or path exists]],
Return_Value = [[result - boolean - true if the file or path exists, false if it doesn't]],
}
function dtutils_file.check_if_file_exists(filepath)
local result = os.execute("test -e " .. filepath)
if not result then
result = false
end
return result
end
--[[
NAME
chop_filetype - remove a filetype from a filename
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.chop_filetype(path)
path - string - a filename with or without a path
DESCRIPTION
chop_filetype removes the filetype from the filename
RETURN VALUE
result - string - the path and filename without the filetype
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[chop_filetype - remove a filetype from a filename]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.chop_filetype(path)
path - string - a filename with or without a path]],
Description = [[chop_filetype removes the filetype from the filename]],
Return_Value = [[result - string - the path and filename without the filetype]],
}
function dtutils_file.chop_filetype(path)
local length = dtutils_file.get_filetype(path):len() + 2
return string.sub(path, 1, -length)
end
--[[
NAME
file_copy - copy a file to another name/location
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.file_copy(fromFile, toFile)
fromFile - string - name of file to copy from
toFile - string - name of file to copy to
DESCRIPTION
copy a file using a succession of methods from operating system
to a pure lua solution
RETURN VALUE
result - boolean - nil on error, true on success
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[file_copy - copy a file to another name/location]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.file_copy(fromFile, toFile)
fromFile - string - name of file to copy from
toFile - string - name of file to copy to]],
Description = [[copy a file using a succession of methods from operating system
to a pure lua solution]],
Return_Value = [[result - boolean - nil on error, true on success]],
}
function dtutils_file.file_copy(fromFile, toFile)
local result = nil
-- if cp exists, use it
if dtutils_file.check_if_bin_exists("cp") then
result = os.execute("cp '" .. fromFile .. "' '" .. toFile .. "'")
end
-- if cp was not present, or if cp failed, then a pure lua solution
if not result then
local fileIn, err = io.open(fromFile, 'rb')
if fileIn then
local fileOut, errr = io.open(toFile, 'w')
if fileOut then
local content = fileIn:read(4096)
while content do
fileOut:write(content)
content = fileIn:read(4096)
end
result = true
fileIn:close()
fileOut:close()
else
log.msg(log.error, errr)
end
else
log.msg(log.error, err)
end
end
return result
end
--[[
NAME
file_move - move a file from one directory to another
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.file_move(fromFile, toFile)
fromFile - string - name of the original file
toFile - string - the new file location and name
DESCRIPTION
Move a file from one place to another. Try a succession of methods from
builtin to operating system to a pure lua solution.
RETURN VALUE
result - boolean - nil on error, some value on success
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[file_move - move a file from one directory to another]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.file_move(fromFile, toFile)
fromFile - string - name of the original file
toFile - string - the new file location and name]],
Description = [[Move a file from one place to another. Try a succession of methods from
builtin to operating system to a pure lua solution.]],
Return_Value = [[result - boolean - nil on error, some value on success]],
}
function dtutils_file.file_move(fromFile, toFile)
local success = os.rename(fromFile, toFile)
if not success then
-- an error occurred, so let's try using the operating system function
if dtutils_file.check_if_bin_exists("mv") then
success = os.execute("mv '" .. fromFile .. "' '" .. toFile .. "'")
end
-- if the mv didn't exist or succeed, then...
if not success then
-- pure lua solution
success = dtutils_file.file_copy(fromFile, toFile)
if success then
os.remove(fromFile)
else
log.msg(log.error, "Unable to move " .. fromFile .. " to " .. toFile .. ". Leaving " .. fromFile .. " in place.")
end
end
end
return success -- nil on error, some value if success
end
--[[
NAME
filename_increment - add a two digit increment to a filename
SYNOPSIS
local df = require "lib/dtutils.file"
local result = df.filename_increment(filepath)
filepath - string - filename to increment
DESCRIPTION
filename_increment solves the problem of filename confllict by adding an
increment to the filename. If the supplied filename has no increment then
"01" is added to the basename. If the filename already has an increment, then
1 is added to it and the filename returned.
RETURN VALUE
result - string - the incremented filename
]]
dtutils_file.libdoc.functions[#dtutils_file.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[filename_increment - add a two digit increment to a filename]],
Synopsis = [[local df = require "lib/dtutils.file"
local result = df.filename_increment(filepath)
filepath - string - filename to increment]],
Description = [[filename_increment solves the problem of filename confllict by adding an
increment to the filename. If the supplied filename has no increment then
"01" is added to the basename. If the filename already has an increment, then
1 is added to it and the filename returned.]],
Return_Value = [[result - string - the incremented filename]],
}
function dtutils_file.filename_increment(filepath)
-- break up the filepath into parts
local path = dtutils_file.get_path(filepath)
local basename = dtutils_file.get_basename(filepath)
local filetype = dtutils_file.get_filetype(filepath)
-- check to see if we've incremented before
local increment = string.match(basename, "_(%d-)$")
if increment then
-- we do 2 digit increments so make sure we didn't grab part of the filename
if string.len(increment) > 2 then
-- we got the filename so set the increment to 01
increment = "01"
else
increment = string.format("%02d", tonumber(increment) + 1)
basename = string.gsub(basename, "_(%d-)$", "")
end
else
increment = "01"
end
local incremented_filepath = path .. basename .. "_" .. increment .. "." .. filetype
return incremented_filepath
end
return dtutils_file

266
lib/dtutils/processor.lua Normal file
View File

@@ -0,0 +1,266 @@
--[[
This file is part of darktable,
copyright (c) 2016 Bill Ferguson
darktable 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.
darktable 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 darktable. If not, see <http://www.gnu.org/licenses/>.
]]
local dtutils_processor = {}
dtutils_processor.libdoc = {
Sections = {"Name", "Synopsis", "Description", "License"},
Name = [[dtutils.processor - Darktable lua functions for building processor scripts]],
Synopsis = [[local dp = require "lib/dtutils.processor"]],
Description = [[dtutils.processor provides common functions used for building scripts
that send images out to an external process, process them, and return the result (i.e. processors).]],
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
(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/>.]],
functions = {}
}
local dt = require "darktable"
local dtutils = require "lib/dtutils"
local df = require "lib/dtutils.file"
local log = require "lib/libLog"
local gettext = dt.gettext
dt.configuration.check_version(...,{3,0,0})
-- Tell gettext where to find the .mo file translating messages for a particular domain
-- This should be $HOME/.config/darktable/lua/locale/
gettext.bindtextdomain("dtutils",dt.configuration.config_dir.."/lua/locale/")
local function _(msgid)
return gettext.dgettext("dtutils.processor", msgid)
end
--[[
NAME
exporter_status - show the status while exporting images
SYNOPSIS
local dp = require "lib/dtutils.processor"
local result = dp.exporter_status(storage, image, format, filename, number, total, high_quality, extra_data)
storage - dt_imageio_module_storage_t - the storage that the status is being shown for
image - dt_lua_image_t - the current image
format - dt_imageio_module_format_t - the format of the export image
filename - string - the filename being exported to
number - integer - the number of this image in the sequence
total - integer - the total number of images being exported
high_quality - boolean
extra_data - extra data from the storage
DESCRIPTION
exporter_status runs prior to each image being exported and prints out a status that lets the user
know how many images, out of the total, have been exported
RETURN VALUE
none
]]
dtutils_processor.libdoc.functions[#dtutils_processor.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[exporter_status - show the status while exporting images]],
Synopsis = [[local dp = require "lib/dtutils.processor"
local result = dp.exporter_status(storage, image, format, filename, number, total, high_quality, extra_data)
storage - dt_imageio_module_storage_t - the storage that the status is being shown for
image - dt_lua_image_t - the current image
format - dt_imageio_module_format_t - the format of the export image
filename - string - the filename being exported to
number - integer - the number of this image in the sequence
total - integer - the total number of images being exported
high_quality - boolean
extra_data - extra data from the storage]],
Description = [[exporter_status runs prior to each image being exported and prints out a status that lets the user
know how many images, out of the total, have been exported]],
Return_Value = [[none]],
}
function dtutils_processor.exporter_status(storage, image, format, filename,
number, total, high_quality, extra_data)
dt.print(string.format(_("Export Image %i/%i"), number, total))
end
--[[
NAME
extract_image_list - assemble the exported image filenames from an image_table into a string
SYNOPSIS
local dp = require "lib/dtutils.processor"
result = dp.extract_image_list(image_table)
image_table - table - a table of images such as supplied by the exporter or by libPlugin.build_image_table
DESCRIPTION
extract_image_list concatenates the exported image names into a space separated string suitable for
passing as an argument to a processor. Each filename is bracketed with single quotes to protect against
spaces and special characters in the filepath
RETURN VALUE
result - string - the assembled image list on success, or an empty image list on error
]]
dtutils_processor.libdoc.functions[#dtutils_processor.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[extract_image_list - assemble the exported image filenames from an image_table into a string]],
Synopsis = [[local dp = require "lib/dtutils.processor"
result = dp.extract_image_list(image_table)
image_table - table - a table of images such as supplied by the exporter or by libPlugin.build_image_table]],
Description = [[extract_image_list concatenates the exported image names into a space separated string suitable for
passing as an argument to a processor. Each filename is bracketed with single quotes to protect against
spaces and special characters in the filepath]],
Return_Value = [[result - string - the assembled image list on success, or an empty image list on error]],
}
function dtutils_processor.extract_image_list(image_table)
local img_list = ""
for _,exp_img in pairs(image_table) do
img_list = img_list .. " " .. "'" .. exp_img .. "'"
end
return img_list
end
--[[
NAME
extract_collection_path - extract the collection path from an image table
SYNOPSIS
local dp = require "lib/dtutils.processor"
local result = dp.extract_collection_path(image_table)
image_table - table - a table of images such as supplied by the exporter or by libPlugin.build_image_table
DESCRIPTION
extract_collection_path looks at the first image in the image_table and returns the path
RETURN VALUE
result - string - the collection path on success, or nil if there was an error
LIMITATIONS
The collection path is determined from the first image. If the table consists of images from different
collections, then only the first collection is used.
]]
dtutils_processor.libdoc.functions[#dtutils_processor.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value", "Limitations"},
Name = [[extract_collection_path - extract the collection path from an image table]],
Synopsis = [[local dp = require "lib/dtutils.processor"
local result = dp.extract_collection_path(image_table)
image_table - table - a table of images such as supplied by the exporter or by libPlugin.build_image_table]],
Description = [[extract_collection_path looks at the first image in the image_table and returns the path]],
Return_Value = [[result - string - the collection path on success, or nil if there was an error]],
Limitations = [[The collection path is determined from the first image. If the table consists of images from different
collections, then only the first collection is used.]],
}
function dtutils_processor.extract_collection_path(image_table)
collection_path = nil
for i,_ in pairs(image_table) do
collection_path = i.path
break
end
return collection_path
end
--[[
NAME
make_output_filename- make an output filename from an image list
SYNOPSIS
local dp = require "lib/dtutils.processor"
local result = dtutils.make_output_filename(img_list)
img_list - string - a space separated list of filenames
DESCRIPTION
make_output_filename takes a string of filenames, breaks them apart, then
combines them in a way that makes some sense. This is useful in routines
that do panoramas, hdr, or focus stacks. The returned filename is a representation
of the files used to construct the image. If there are 3 or fewer images, then the file
basenames are concatenated with a separator. If there is more than 3 images, the first and
last file basenames are concatenated with a separator.
RETURN VALUE
result - string - the constructed filename on success, nil on error
]]
dtutils_processor.libdoc.functions[#dtutils_processor.libdoc.functions + 1] = {
Sections = {"Name", "Synopsis", "Description", "Return_Value"},
Name = [[make_output_filename- make an output filename from an image list]],
Synopsis = [[local dp = require "lib/dtutils.processor"
local result = dtutils.make_output_filename(img_list)
img_list - string - a space separated list of filenames]],
Description = [[make_output_filename takes a string of filenames, breaks them apart, then
combines them in a way that makes some sense. This is useful in routines
that do panoramas, hdr, or focus stacks. The returned filename is a representation
of the files used to construct the image. If there are 3 or fewer images, then the file
basenames are concatenated with a separator. If there is more than 3 images, the first and
last file basenames are concatenated with a separator.]],
Return_Value = [[result - string - the constructed filename on success, nil on error]],
}
function dtutils_processor.make_output_filename(img_list)
local images = {}
local cnt = 1
local max_distinct_names = 3
local name_separator = "-"
local outputFileName = nil
log.msg(log.debug, "img_list is ", img_list)
local result = dtutils.split(img_list, " ")
table.sort(result)
for _,img in pairs(result) do
images[cnt] = df.get_basename(img)
cnt = cnt + 1
end
cnt = cnt - 1
if cnt > 1 then
if cnt > max_distinct_names then
-- take the first and last
outputFileName = images[1] .. name_separator .. images[cnt]
else
-- join them
outputFileName = dtutils.join(images, name_separator)
end
else
-- return the single name
outputFileName = images[cnt]
end
return outputFileName
end
return dtutils_processor