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