doc/docbook/GuideReferenceLua.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <section id="GuideReferenceLua">
   3     <title>
   4       Lua Extensions
   5     </title><para>Lua scripts allow the functionality of Geeqie to be extended. Lua scripts may only be used in conjunction with the Overlay Screen Display.
   6     </para><para/>
   7     <para>Some knowledge of the Lua programming language is required.</para>
   8     <section id="Requirements"><title>Requirements</title><para>Use 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.</para>
   9     <para>If you are using a pre-compiled distribution, availability depends on the package maintainer.</para></section>
  10     <section id="HowToUseLua"><title>How to use Lua</title><para>Lua scripts must be stored in a single folder:<programlisting>
  11     ~/.config/geeqie/lua/</programlisting></para>
  12     <para>A link to a Lua script must be inserted into the overlay template. Refer to the Overlay Screen Display section of <link linkend="GuideOptionsWindow">Window Options</link>.</para>
  13     <para>The full extent of the Lua language is available.</para></section>
  14     <section id="GeeqieBuiltIn Functions"><title>Geeqie Lua built-in functions
  15     </title><para>The following functions are built in to Geeqie:</para><para>
  16     <informaltable><tgroup cols="2"><tbody><row><entry>
  17         <emphasis role="strong">Function</emphasis>
  18         </entry><entry>
  19           <emphasis role="strong">Returns</emphasis>
  20         </entry></row>
  21     <row><entry>
  22           Image:get_path()
  23         </entry><entry>
  24           The full path of the file, including filename and extension
  25         </entry></row>
  26     <row><entry>
  27           Image:get_name()
  28         </entry><entry>
  29           The full filename including extension
  30         </entry></row>
  31     <row><entry>
  32           Image:get_extension
  33         </entry><entry>
  34           The file extension including preceeding dot
  35         </entry></row>
  36     <row><entry>
  37           Image:get_date()
  38         </entry><entry>
  39           The file date in Unix timestamp format.
  40         </entry></row>
  41     <row><entry>
  42           Image:get_size()
  43         </entry><entry>
  44           The file size in bytes
  45         </entry></row>
  46     <row><entry>
  47           Image:get_exif()
  48         </entry><entry>
  49           A data structure containing the entire exif data
  50         </entry></row>
  51     <row><entry>
  52           &lt;exif_str&gt;:get_datum("&lt;exif_tag&gt;")
  53         </entry><entry>
  54           A single exif tag extracted from a structure output by the above command
  55         </entry></row>
  56     </tbody></tgroup></informaltable>
  57     </para><para>The keyword "Image" refers to the file currently being displayed by Geeqie.</para></section>
  58     <section id="Examples"><title>Examples
  59     </title><para>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:<programlisting>
  60 --Retrieve the jpeg comment of a file
  61 path=Image:get_path()
  62 commentfile=io.popen("exiv2 -p c \"" .. path .. "\"" )
  63 comment = commentfile:read("*a")
  64 commentfile:close()
  65 return (comment)</programlisting></para>
  66     <para>Note that it is necessary to have escape characters surrounding path and filenames.</para>
  67     <para>The following example demonstrates how to extract exif data from a file:<programlisting>
  68 --Retrieve the DateTimeDigitized exif tag
  69 exif_structure = Image:get_exif();
  70 DateTimeDigitized = exif_structure:get_datum("Exif.Photo.DateTimeDigitized");
  71 return (os.date(DateTimeDigitized))
  72     </programlisting></para></section>
  73     <section id="Warning"><title>Warning
  74     </title><para>Lua is a powerful programming language. Errors in script files, besides having undesirable side-effects, may cause Geeqie to crash.</para></section>
  75 </section>