From e42f4e864bac21ed3b19d1869df2cdd4f8c3433c Mon Sep 17 00:00:00 2001 From: pacien Date: Sat, 22 Feb 2020 14:53:03 +0100 Subject: compiler: flatten gallery config GitHub: closes #129 --- compiler/ldgallery.1.md | 154 +++++++++++++++++++++++++++++++++++++++++++++++ compiler/src/Compiler.hs | 7 +-- compiler/src/Config.hs | 45 +++++++------- 3 files changed, 180 insertions(+), 26 deletions(-) create mode 100644 compiler/ldgallery.1.md (limited to 'compiler') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md new file mode 100644 index 0000000..5524409 --- /dev/null +++ b/compiler/ldgallery.1.md @@ -0,0 +1,154 @@ +--- +pagetitle: User manual - ldgallery +title: LDGALLERY(1) ldgallery user manual +author: Pacien TRAN-GIRARD, Guillaume FOUET +date: 2020-02-15 (v0.1.0.0-SNAPSHOT) +--- + + +# NAME + +ldgallery - a static web gallery generator with tags + + +# DESCRIPTION + +ldgallery is a static gallery generator which turns a collection of tagged pictures into a searchable web gallery. + +The ldgallery compiler program processes pictures and aggregates metadata from plain text sidecar files to generate an indexed version of the gallery. It can optionally output a static web viewer along, which allows the content to be presented and searched through from a JavaScript-enabled web browser. This client-side web application does not require any special software on the server's side. + + +# COMMAND + +ldgallery [\--input-dir _./_] [\--output-dir _./out_] [\--with-viewer] + +Available options are: + +-i, \--input-dir _DIR_ +: Gallery source directory. + Defaults to the current directory. + +-o, \--output-dir _DIR_ +: Generated gallery output path. + Must be distinct from the source directory. + Defaults to ./out. + +-g, \--gallery-config _FILE_ +: Gallery configuration file. + Defaults to $input-dir/gallery.yaml. + +-r, \--rebuild-all +: Invalidate cache and recompile everything. + +-c, \--clean-output +: Remove unnecessary files from the output directory. + +-w, \--with-viewer +: Include the static web viewer in the output. + +-h, \--help +: Display help message. + +\--version +: Print version information. + +\--numeric-version +: Print just the version number. + + +# INPUT GALLERY STRUCTURE + +A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories. + +Directory thumbnails can be set by placing a picture file named "_directory", with any image file extension, inside of directories. + +An example input gallery directory structure could be as follows: + +``` +./example-gallery +├── DSC0001.jpg --------- a picture +├── DSC0001.jpg.yaml ---- its associated sidecar metadata file +├── Some directory ------ a directory grouping gallery items +│ ├── _directory.jpg -- a thumbnail for its parent directory +│ ├── _directory.yaml - directory sidecar metadata file +│ ├── DSC0002.jpg +│ ├── DSC0002.jpg.yaml +│ ├── DSC0003.jpg +│ └── DSC0003.jpg.yaml +└── gallery.yaml -------- gallery settings file +``` + + +# METADATA SIDECAR + +File metadata are read from sidecar files of the same name, with the ".yaml" extension appended. +Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored. + +Directory metadata are read from sidecar files named "_directory.yaml" located within the directory. + +When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below. + +title +: Title of the item. + Defaults to the name of the file or directory. + +datetime +: ISO 8601 zoned date and time. + Defaults to the last modification time of the file itself, + or the most recent modification date of a directory's items. + +description +: Description for the item. + +tags +: List of tags for the item. + Tag groups can be defined using prefixes separated by "." (dot). + Tags specified in a directory metadata sidecar are applied to all items within that directory. + + +# GALLERY CONFIGURATION + +The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory. + +includedDirectories[] +: Glob patterns of directory names to include in the gallery. Defaults to ["*"] (matches all directory names). + +excludedDirectories[] +: Glob patterns of directory names to exclude from the gallery. Defaults to [] (none). + +includedFiles[] +: Glob patterns of file names to include in the gallery. Defaults to ["*"] (matches all file names). + +excludedFiles[] +: Glob patterns of file names to exclude from the gallery. Defaults to [] (none). + +tagsFromDirectories.fromParents +: Automatically generate tags from the name of parent directories, + looking up in the hierarchy as far as indicated by this parameter. + Defaults to 0 (do not generate tags from parent directories). + +tagsFromDirectories.prefix +: Prefix to use for tags automatically generated from the parent directories' names. + +thumbnailMaxResolution.width +: Maximum width in pixels of the item thumbnails, 400 by default. + +thumbnailMaxResolution.height +: Maximum height in pixels of the item thumbnails, 300 by default. + +pictureMaxResolution.width +: Maximum width in pixels of the picture items, unlimited by default. + +pictureMaxResolution.height +: Maximum height in pixels of the picture items, unlimited by default. + + +# SEE ALSO + +The ldgallery source code is available on . + +Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET. + +This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 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 Affero General Public License for more details . diff --git a/compiler/src/Compiler.hs b/compiler/src/Compiler.hs index bb0ee97..73ac8a4 100644 --- a/compiler/src/Compiler.hs +++ b/compiler/src/Compiler.hs @@ -70,7 +70,7 @@ writeJSON outputPath object = ensureParentDir JSON.encodeFile outputPath object -galleryDirFilter :: CompilerConfig -> [FilePath] -> FSNode -> Bool +galleryDirFilter :: GalleryConfig -> [FilePath] -> FSNode -> Bool galleryDirFilter config excludedCanonicalDirs = (not . isHidden) &&& (not . isExcludedDir) @@ -102,8 +102,7 @@ galleryDirFilter config excludedCanonicalDirs = compileGallery :: FilePath -> FilePath -> FilePath -> [FilePath] -> Bool -> Bool -> IO () compileGallery configPath inputDirPath outputDirPath excludedDirs rebuildAll cleanOutput = do - fullConfig <- readConfig $ inputGalleryConf configPath - let config = compiler fullConfig + config <- readConfig $ inputGalleryConf configPath inputDir <- readDirectory inputDirPath excludedCanonicalDirs <- mapM canonicalizePath excludedDirs @@ -119,7 +118,7 @@ compileGallery configPath inputDirPath outputDirPath excludedDirs rebuildAll cle when cleanOutput $ galleryCleanupResourceDir resources outputDirPath writeJSON outputIndex resources - writeJSON outputViewerConf $ viewer fullConfig + writeJSON outputViewerConf $ viewerConfig config where inputGalleryConf :: FilePath -> FilePath diff --git a/compiler/src/Config.hs b/compiler/src/Config.hs index bf5a28e..5f1806d 100644 --- a/compiler/src/Config.hs +++ b/compiler/src/Config.hs @@ -17,11 +17,10 @@ -- along with this program. If not, see . module Config - ( GalleryConfig(..) - , CompilerConfig(..) + ( GalleryConfig(..), readConfig + , ViewerConfig(..), viewerConfig , TagsFromDirectoriesConfig(..) , Resolution(..) - , readConfig ) where @@ -39,7 +38,18 @@ data Resolution = Resolution } deriving (Generic, Show, ToJSON, FromJSON) -data CompilerConfig = CompilerConfig +data TagsFromDirectoriesConfig = TagsFromDirectoriesConfig + { fromParents :: Int + , prefix :: String + } deriving (Generic, Show) + +instance FromJSON TagsFromDirectoriesConfig where + parseJSON = withObject "TagsFromDirectoriesConfig" $ \v -> TagsFromDirectoriesConfig + <$> v .:? "fromParents" .!= 0 + <*> v .:? "prefix" .!= "" + + +data GalleryConfig = GalleryConfig { includedDirectories :: [String] , excludedDirectories :: [String] , includedFiles :: [String] @@ -49,8 +59,8 @@ data CompilerConfig = CompilerConfig , pictureMaxResolution :: Maybe Resolution } deriving (Generic, Show) -instance FromJSON CompilerConfig where - parseJSON = withObject "CompilerConfig" $ \v -> CompilerConfig +instance FromJSON GalleryConfig where + parseJSON = withObject "GalleryConfig" $ \v -> GalleryConfig <$> v .:? "includedDirectories" .!= ["*"] <*> v .:? "excludedDirectories" .!= [] <*> v .:? "includedFiles" .!= ["*"] @@ -59,22 +69,13 @@ instance FromJSON CompilerConfig where <*> v .:? "thumbnailMaxResolution" .!= (Resolution 400 300) <*> v .:? "pictureMaxResolution" - -data TagsFromDirectoriesConfig = TagsFromDirectoriesConfig - { fromParents :: Int - , prefix :: String - } deriving (Generic, Show) - -instance FromJSON TagsFromDirectoriesConfig where - parseJSON = withObject "TagsFromDirectoriesConfig" $ \v -> TagsFromDirectoriesConfig - <$> v .:? "fromParents" .!= 0 - <*> v .:? "prefix" .!= "" +readConfig :: FileName -> IO GalleryConfig +readConfig = decodeYamlFile -data GalleryConfig = GalleryConfig - { compiler :: CompilerConfig - , viewer :: JSON.Object - } deriving (Generic, FromJSON, Show) +data ViewerConfig = ViewerConfig + { -- TODO: add viewer config keys (tag groups...) + } deriving (Generic, ToJSON, Show) -readConfig :: FileName -> IO GalleryConfig -readConfig = decodeYamlFile +viewerConfig :: GalleryConfig -> ViewerConfig +viewerConfig _ = ViewerConfig -- TODO -- cgit v1.2.3