From: Colin Clark Date: Thu, 5 May 2016 17:40:59 +0000 (+0100) Subject: Lua Documentation X-Git-Tag: v1.3~29^2 X-Git-Url: http://geeqie.org/cgi-bin/gitweb.cgi?p=geeqie.git;a=commitdiff_plain;h=db07c98328999549907492a4c78f82ee964d93c1 Lua Documentation Basic Lua documentation. Requires expansion and re-work. --- diff --git a/doc/docbook/GuideOptionsWindow.xml b/doc/docbook/GuideOptionsWindow.xml index 7f4b4fec..130ccec2 100644 --- a/doc/docbook/GuideOptionsWindow.xml +++ b/doc/docbook/GuideOptionsWindow.xml @@ -82,9 +82,9 @@ Overlay info format string syntax is: %tag[:max_length][:extra]% - Tag + Tag - Replaced by + Replaced by name @@ -141,17 +141,39 @@ Image comment from metadata + + <exif_tag> + + The exif tag from metadata + + + lua/<lua_script>/ + + The output of a Lua script file + + + lua//<lua_command> + + The output of a Lua command + - To access exif data use the exif name, for example: %Exif.Photo.DateTimeOriginal% to get the date of the original shot - + Examples of usage are: + +%keywords% +%Exif.Photo.DateTimeOriginal% +%lua/jpeg_comment.lua/:12% +%lua//return(os.date())% + + Refer to Lua Extensions for further information. + Pre-formatted exif data is also available: - Tag + Tag - Replaced by exif data + Replaced by exif data formatted.Camera diff --git a/doc/docbook/GuideReference.xml b/doc/docbook/GuideReference.xml index 58702ca1..66b0457b 100644 --- a/doc/docbook/GuideReference.xml +++ b/doc/docbook/GuideReference.xml @@ -8,5 +8,6 @@ + diff --git a/doc/docbook/GuideReferenceLua.xml b/doc/docbook/GuideReferenceLua.xml new file mode 100644 index 00000000..da764476 --- /dev/null +++ b/doc/docbook/GuideReferenceLua.xml @@ -0,0 +1,75 @@ + +
+ + Lua Extensions + Lua scripts allow the functionality of Geeqie to be extended. Lua scripts may only be used in conjunction with the Overlay Screen Display. + + Some knowledge of the Lua programming language is required. +
RequirementsUse of Lua within Geeqie requires Lua 5.1 to be installed. If you are compiling from sources, Lua functionality will be available if the development files dependencies are met. + If you are using a pre-compiled distribution, availability depends on the package maintainer.
+
How to use LuaLua scripts must be stored in a single folder: + ~/.config/geeqie/lua/ + A link to a Lua script must be inserted into the overlay template. Refer to the Overlay Screen Display section of Window Options. + The full extent of the Lua language is available.
+
Geeqie Lua built-in functions + The following functions are built in to Geeqie: + + Function + + Returns + + + Image:get_path() + + The full path of the file, including filename and extension + + + Image:get_name() + + The full filename including extension + + + Image:get_extension + + The file extension including preceeding dot + + + Image:get_date() + + The file date in Unix timestamp format. + + + Image:get_size() + + The file size in bytes + + + Image:get_exif() + + A data structure containing the entire exif data + + + <exif_str>:get_datum("<exif_tag>") + + A single exif tag extracted from a structure output by the above command + + + The keyword "Image" refers to the file currently being displayed by Geeqie.
+
Examples + The following example, which outputs the jpeg comment of a file, demonstrates the use of a built-in function and how to call a system command from a Lua script: +--Retrieve the jpeg comment of a file +path=Image:get_path() +commentfile=io.popen("exiv2 -p c \"" .. path .. "\"" ) +comment = commentfile:read("*a") +commentfile:close() +return (comment) + Note that it is necessary to have escape characters surrounding path and filenames. + The following example demonstrates how to extract exif data from a file: +--Retrieve the DateTimeDigitized exif tag +exif_structure = Image:get_exif(); +DateTimeDigitized = exif_structure:get_datum("Exif.Photo.DateTimeDigitized"); +return (os.date(DateTimeDigitized)) +
+
Warning + Lua is a powerful programming language. Errors in script files, besides having undesirable side-effects, may cause Geeqie to crash.
+