doc/docbook/GuideReferenceLua.xml

   1 <?xml version="1.0" encoding="utf-8"?>\r
   2 <section id="GuideReferenceLua">\r
   3   <title>Lua Extensions</title>\r
   4   <para>\r
   5     Lua scripts allow the functionality of Geeqie to be extended. Lua scripts may only be used in conjunction with the\r
   6     <link linkend="OverlayScreenDisplay">Overlay Screen Display</link>\r
   7     ,\r
   8     <link linkend="GuideSidebarsInfo" endterm="Listpanes-ExifFileinfoCopyrightLocationandGPS">List panes</link>\r
   9     on the Info Sidebar, and the\r
  10     <programlisting xml:space="preserve">geeqie --remote --lua:</programlisting>\r
  11     command line option.\r
  12   </para>\r
  13   <para />\r
  14   <para>Some knowledge of the Lua programming language is required.</para>\r
  15   <section id="Requirements">\r
  16     <title>Requirements</title>\r
  17     <para>Use of Lua within Geeqie requires Lua to be installed. If you are compiling from sources, Lua functionality will be available if the development files dependencies are met.</para>\r
  18     <para>If you are using a pre-compiled distribution, availability depends on the package maintainer.</para>\r
  19   </section>\r
  20   <section id="HowToUseLua">\r
  21     <title>How to use Lua</title>\r
  22     <para>\r
  23       Lua scripts must be stored in a single folder as defined in\r
  24       <link linkend="GuideReferenceConfig" endterm="titleGuideReferenceConfig" />\r
  25       .\r
  26     </para>\r
  27     <para>\r
  28       A link to a Lua script must be inserted into the overlay template. Refer to the\r
  29       <link linkend="OverlayScreenDisplay">Overlay Screen Display</link>\r
  30       section of Window Options.\r
  31     </para>\r
  32     <para>The full extent of the Lua language is available.</para>\r
  33   </section>\r
  34   <section id="GeeqieBuiltIn Functions">\r
  35     <title>Geeqie Lua built-in functions</title>\r
  36     <para>The following functions are built in to Geeqie:</para>\r
  37     <para>\r
  38       <informaltable>\r
  39         <tgroup cols="2">\r
  40           <tbody>\r
  41             <row>\r
  42               <entry>\r
  43                 <emphasis role="strong">Function</emphasis>\r
  44               </entry>\r
  45               <entry>\r
  46                 <emphasis role="strong">Returns</emphasis>\r
  47               </entry>\r
  48             </row>\r
  49             <row>\r
  50               <entry>Image:get_path()</entry>\r
  51               <entry>The full path of the file, including filename and extension</entry>\r
  52             </row>\r
  53             <row>\r
  54               <entry>Image:get_name()</entry>\r
  55               <entry>The full filename including extension</entry>\r
  56             </row>\r
  57             <row>\r
  58               <entry>Image:get_extension</entry>\r
  59               <entry>The file extension including preceeding dot</entry>\r
  60             </row>\r
  61             <row>\r
  62               <entry>Image:get_date()</entry>\r
  63               <entry>The file date in Unix timestamp format.</entry>\r
  64             </row>\r
  65             <row>\r
  66               <entry>Image:get_size()</entry>\r
  67               <entry>The file size in bytes</entry>\r
  68             </row>\r
  69             <row>\r
  70               <entry>Image:get_marks()</entry>\r
  71               <entry>An integer representing the marks set for the file</entry>\r
  72             </row>\r
  73             <row>\r
  74               <entry>Image:get_exif()</entry>\r
  75               <entry>A data structure containing the entire exif data</entry>\r
  76             </row>\r
  77             <row>\r
  78               <entry>&lt;exif_str&gt;:get_datum("&lt;exif_tag&gt;")</entry>\r
  79               <entry>A single exif tag extracted from a structure output by the above command</entry>\r
  80             </row>\r
  81           </tbody>\r
  82         </tgroup>\r
  83       </informaltable>\r
  84     </para>\r
  85     <para>The keyword "Image" refers to the file currently being displayed by Geeqie.</para>\r
  86   </section>\r
  87   <section id="Examples">\r
  88     <title>Examples</title>\r
  89     <para>\r
  90       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:\r
  91       <programlisting xml:space="preserve">\r
  92         path=Image:get_path()\r
  93         commentfile=io.popen("exiv2 -p c \"" .. path .. "\"" )\r
  94         comment = commentfile:read("*a")\r
  95         commentfile:close()\r
  96         return (comment)\r
  97       </programlisting>\r
  98     </para>\r
  99     <para>Note that it is necessary to have escape characters surrounding path and filenames.</para>\r
 100     <para>\r
 101       The following example demonstrates how to extract exif data from a file:\r
 102       <programlisting xml:space="preserve">\r
 103         --Retrieve the DateTimeDigitized exif tag\r
 104         exif_structure = Image:get_exif();\r
 105         DateTimeDigitized = exif_structure:get_datum("Exif.Photo.DateTimeDigitized");\r
 106         return (os.date(DateTimeDigitized))\r
 107       </programlisting>\r
 108     </para>\r
 109   </section>\r
 110   <section id="Warning">\r
 111     <title>Warning</title>\r
 112     <warning>\r
 113       <para>Lua is a powerful programming language. Errors in script files, besides having undesirable side-effects, may cause Geeqie to crash.</para>\r
 114     </warning>\r
 115   </section>\r
 116 </section>\r