From 6202928d32c697443ee47ceee421c6bb0aa99a19 Mon Sep 17 00:00:00 2001 From: Colin Clark Date: Mon, 17 May 2021 15:19:21 +0100 Subject: [PATCH] Use Doxygen to create a Lua API reference Generate a Lua API document - the Lua interface is minimal at the moment, but may get expanded. Change lua.c slightly so that the required data is visible. Create a script to generate the Doxygen html files. Include the API in the main help file. --- doc/Makefile.am | 4 +- doc/create-doxygen-lua-api.sh | 99 +++++++++++++++++++++ doc/docbook/GuideReference.xml | 1 + doc/docbook/GuideReferenceLuaAPI.xml | 7 ++ src/lua.c | 127 +++++++++++++++++++++++---- 5 files changed, 220 insertions(+), 18 deletions(-) create mode 100755 doc/create-doxygen-lua-api.sh create mode 100644 doc/docbook/GuideReferenceLuaAPI.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index 78b96233..3b3a20e8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -5,7 +5,7 @@ helpdir = @htmldir@ EXTRA_DIST = docbook2html.sh docbook icons html/GuideIndex.html: docbook/GuideIndex.xml - rm -rf html; mkdir html; cp $(srcdir)/icons/* html/ + rm -rf html; mkdir html; cp $(srcdir)/icons/* html/; ./create-doxygen-lua-api.sh if [ -x "$(GNOME_DOC_TOOL)" ]; then \ "$(GNOME_DOC_TOOL)" html -i -o html/ $(srcdir)/docbook/GuideIndex.xml ; \ else \ @@ -19,6 +19,8 @@ install-data-hook: html $(MKDIR_P) "$(DESTDIR)$(helpdir)" || exit 1; \ cd $(srcdir)/html; for f in * ; do $(INSTALL_DATA) "$$f" "$(DESTDIR)$(helpdir)/$$f" ; done; \ ln -s -f GuideIndex.html "$(DESTDIR)$(helpdir)/index.html" ; \ + $(MKDIR_P) "$(DESTDIR)$(helpdir)/lua-api" || exit 1; \ + cd ./lua-api/html; for f in * ; do $(INSTALL_DATA) "$$f" "$(DESTDIR)$(helpdir)/lua-api/$$f" ; done; \ fi uninstall-hook: diff --git a/doc/create-doxygen-lua-api.sh b/doc/create-doxygen-lua-api.sh new file mode 100755 index 00000000..38c92edf --- /dev/null +++ b/doc/create-doxygen-lua-api.sh @@ -0,0 +1,99 @@ +#!/bin/bash + +#********************************************************************** +# Copyright (C) 2021 - The Geeqie Team +# +# Author: Colin Clark +# +# 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 2 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, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +#********************************************************************** +# +# This script will create the Lua API html document, which is part of +# the Geeqie Help file. +# +# It is run during the generation of the help files. +# +# The generated Lua html files are placed in doc/html/lua-api +# +# The doxygen.conf file is modified to extract only those comments +# that are useful as part of an API description. +# +#********************************************************************** + +export PROJECT="Geeqie" +export VERSION=$(git tag --list v[1-9]* | tail -1) +export SRCDIR="$PWD/.." +export DOCDIR="$PWD/html/lua-api" + +TMPFILE=$(mktemp) || exit 1 + +# Modify the Geeqie doxygen.conf file to produce +# only the data needed for the lua API document +awk ' +BEGIN { + FILE_PATTERNS_found = "FALSE" +} +{ + if (FILE_PATTERNS_found == "TRUE") + { + if ($0 ~ /\\/) + { + next + } + else + { + FILE_PATTERNS_found = "FALSE" + } + } + if ($1 == SHOW_INCLUDE_FILES) + { + {print "SHOW_INCLUDE_FILES = NO"} + } + else if ($1 == "FILE_PATTERNS") + { + print "FILE_PATTERNS = lua.c" + FILE_PATTERNS_found = "TRUE" + next + } + else if ($1 == "EXCLUDE_SYMBOLS") + { + print "EXCLUDE_SYMBOLS = L \\" + print "lua_callvalue \\" + print "lua_check_exif \\" + print "lua_check_image \\" + print "lua_init \\" + print "_XOPEN_SOURCE \\" + print "LUA_register_global \\" + print "LUA_register_meta" + } + else if ($1 == "SOURCE_BROWSER") + { + print "SOURCE_BROWSER = NO" + } + else if ($1 == "HAVE_DOT") + { + {print "HAVE_DOT = NO"} + } + else + { + {print} + } +} +' ../doxygen.conf > $TMPFILE + +doxygen $TMPFILE + +rm $TMPFILE + diff --git a/doc/docbook/GuideReference.xml b/doc/docbook/GuideReference.xml index a8c62f3e..88f936dd 100644 --- a/doc/docbook/GuideReference.xml +++ b/doc/docbook/GuideReference.xml @@ -6,6 +6,7 @@ + diff --git a/doc/docbook/GuideReferenceLuaAPI.xml b/doc/docbook/GuideReferenceLuaAPI.xml new file mode 100644 index 00000000..5d36e667 --- /dev/null +++ b/doc/docbook/GuideReferenceLuaAPI.xml @@ -0,0 +1,7 @@ + +
+ Lua API + + The Lua API document + +
diff --git a/src/lua.c b/src/lua.c index 384037fd..cb0eb650 100644 --- a/src/lua.c +++ b/src/lua.c @@ -38,6 +38,18 @@ #include "ui_fileops.h" #include "exif.h" +/** + * @file + * User API consists of the following namespaces: + * + * @link image_methods Image:@endlink basic image information + * + * Collection: not implemented + * + * @link exif_methods :get_datum() @endlink get single exif parameter + * + */ + static lua_State *L; /** The LUA object needed for all operations (NOTE: That is * a upper-case variable to match the documentation!) */ @@ -69,6 +81,13 @@ static FileData *lua_check_image(lua_State *L, int index) return *fd; } +/** + * @brief Get exif structure of selected image + * @param L + * @returns An @ref ExifData data structure containing the entire exif data + * + * To be used in conjunction with @link lua_exif_get_datum :get_datum() @endlink + */ static int lua_image_get_exif(lua_State *L) { FileData *fd; @@ -87,6 +106,13 @@ static int lua_image_get_exif(lua_State *L) return 1; } +/** + * @brief Get full path of selected image + * @param L + * @returns char The full path of the file, including filename and extension + * + * + */ static int lua_image_get_path(lua_State *L) { FileData *fd; @@ -96,6 +122,13 @@ static int lua_image_get_path(lua_State *L) return 1; } +/** + * @brief Get full filename of selected image + * @param L + * @returns char The full filename including extension + * + * + */ static int lua_image_get_name(lua_State *L) { FileData *fd; @@ -105,6 +138,13 @@ static int lua_image_get_name(lua_State *L) return 1; } +/** + * @brief Get file extension of selected image + * @param L + * @returns char The file extension including preceding dot + * + * + */ static int lua_image_get_extension(lua_State *L) { FileData *fd; @@ -114,6 +154,14 @@ static int lua_image_get_extension(lua_State *L) return 1; } +/** + * @brief Get file date of selected image + * @param L + * @returns time_t The file date in Unix timestamp format. + * + * time_t - signed integer which represents the number of seconds since + * the start of the Unix epoch: midnight UTC of January 1, 1970 + */ static int lua_image_get_date(lua_State *L) { FileData *fd; @@ -123,6 +171,13 @@ static int lua_image_get_date(lua_State *L) return 1; } +/** + * @brief Get file size of selected image + * @param L + * @returns integer The file size in bytes + * + * + */ static int lua_image_get_size(lua_State *L) { FileData *fd; @@ -132,6 +187,15 @@ static int lua_image_get_size(lua_State *L) return 1; } +/** + * @brief Get marks of selected image + * @param L + * @returns unsigned integer Bit map of marks set + * + * Bit 0 == Mark 1 etc. + * + * + */ static int lua_image_get_marks(lua_State *L) { FileData *fd; @@ -150,7 +214,21 @@ static ExifData *lua_check_exif(lua_State *L, int index) return *exif; } -/* Interface for EXIF data */ +/** + * @brief Interface for EXIF data + * @param L + * @returns return A single exif tag extracted from a structure output by the @link lua_image_get_exif Image:get_exif() @endlink command + * + * e.g. \n + * exif_structure = Image:get_exif(); \n + * DateTimeDigitized = exif_structure:get_datum("Exif.Photo.DateTimeDigitized"); + * + * Where return is: \n + * Exif.Photo.DateTimeOriginal = signed integer time_t \n + * Exif.Photo.DateTimeDigitized = signed integer time_t \n + * otherwise char + * + */ static int lua_exif_get_datum(lua_State *L) { const gchar *key; @@ -206,6 +284,37 @@ static int lua_exif_get_datum(lua_State *L) return 1; } +/** + * @brief Image: metatable and methods \n + * Call by e.g. \n + * path_name = @link lua_image_get_path Image:getpath() @endlink \n + * where the keyword Image represents the currently selected image + */ +static const luaL_Reg image_methods[] = { + {"get_path", lua_image_get_path}, + {"get_name", lua_image_get_name}, + {"get_extension", lua_image_get_extension}, + {"get_date", lua_image_get_date}, + {"get_size", lua_image_get_size}, + {"get_exif", lua_image_get_exif}, + {"get_marks", lua_image_get_marks}, + {NULL, NULL} +}; + +/** + * @brief exif: table and methods \n + * Call by e.g. \n + * @link lua_exif_get_datum :get_datum() @endlink \n + * where is the output of @link lua_image_get_exif Image:get_exif() @endlink + * + * exif_structure = Image:get_exif(); \n + * DateTimeDigitized = exif_structure:get_datum("Exif.Photo.DateTimeDigitized"); + */ +static const luaL_Reg exif_methods[] = { + {"get_datum", lua_exif_get_datum}, + {NULL, NULL} +}; + /** * @brief Initialize the lua interpreter. */ @@ -219,17 +328,6 @@ void lua_init(void) {NULL, NULL} }; - /* The Image metatable and methodes */ - static const luaL_Reg image_methods[] = { - {"get_path", lua_image_get_path}, - {"get_name", lua_image_get_name}, - {"get_extension", lua_image_get_extension}, - {"get_date", lua_image_get_date}, - {"get_size", lua_image_get_size}, - {"get_exif", lua_image_get_exif}, - {"get_marks", lua_image_get_marks}, - {NULL, NULL} - }; LUA_register_global(L, "Image", image_methods); luaL_newmetatable(L, "Image"); LUA_register_meta(L, meta_methods); @@ -242,11 +340,6 @@ void lua_init(void) lua_pop(L, 1); lua_pop(L, 1); - /* The Exif table and methodes */ - static const luaL_Reg exif_methods[] = { - {"get_datum", lua_exif_get_datum}, - {NULL, NULL} - }; LUA_register_global(L, "Exif", exif_methods); luaL_newmetatable(L, "Exif"); LUA_register_meta(L, meta_methods); -- 2.20.1