🔗USAGE local df = require "lib/dtutils.file" 🔗DESCRIPTION The dtutils.file library provides common file manipulation functions used in constructing darktable lua scripts
🔗RETURN VALUE df - library - the file functions
🔗FUNCTIONS 🔗check_if_bin_exists check if an executable exists
🔗check_if_file_exists check if a file or path exist
🔗chop_filetype remove a filetype from a filename
🔗create_unique_filename create a unique filename from the supplied argment
🔗executable_path_widget create a widget to get executable path preferences</description>
🔗DESCRIPTION check_if_bin_exists checks to see if the specified binary exists. check_if_bin_exists looks for an executable in the following order:
If an executable preference is registered, then it&rsquo;s checked to make sure it&rsquo;s a file, exists, and is executable. If it passes all these tests it is returned to the caller.</description>
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local result = df.check_if_file_exists(filepath) filepath - string - a file or path to check
🔗DESCRIPTION check_if_file_exists checks to see if a file or path exists.
🔗RETURN VALUE result - boolean - true if the file or path exists, false if it doesn&rsquo;t.</description>
🔗SYNOPSIS create a unique filename from the supplied argument
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local result = df.create_unique_filename(filepath) filepath - string - the path and filename requested
🔗DESCRIPTION create_unique_filename takes a requested filepath and checks to see if it exists. If if doesn&rsquo;t then it&rsquo;s returned intact. If it already exists, then a two digit increment is added to the filename and it is tested again. The increment keeps increasing until either a unique filename is found or there have been 100 attempts.</description>
🔗SYNOPSIS create a widget to get executable path preferences
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local widget = df.executable_path_widget(executables) executables - table - a table of strings that are executable names
🔗DESCRIPTION executable_path_widget takes a table of executable names and builds a set of file selector widgets to get the path to the executable. The resulting widgets are wrapped in a box widget and returned.
🔗RETURN VALUE widget - widget - a widget containing a file selector widget for each executable.</description>
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local result = df.file_copy(fromFile, toFile) fromFile - string - name of file to copy from
toFile - string - name of file to copy to
🔗DESCRIPTION copy a file using a succession of methods from operating system to a pure lua solution
🔗RETURN VALUE result - boolean - nil on error, true on success</description>
🔗SYNOPSIS move a file from one directory to another
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local result = df.file_move(fromFile, toFile) fromFile - string - name of the original file
toFile - string - the new file location and name
🔗DESCRIPTION Move a file from one place to another. Try a succession of methods from builtin to operating system to a pure lua solution.
🔗RETURN VALUE result - boolean - nil on error, some value on success</description>
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local result = df.filename_increment(filepath) filepath - string - filename to increment
🔗DESCRIPTION filename_increment solves the problem of filename conflict by adding an increment to the filename. If the supplied filename has no increment then &ldquo;01&rdquo; is added to the basename. If the filename already has an increment, then 1 is added to it and the filename returned.</description>
🔗SYNOPSIS return the path to an executable from a preference
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local result = df.get_executable_path_preference(executable) executable - string - the name of the executable to get the path for
🔗DESCRIPTION get_executable_path_preference returns the path preference to the requested executable.
🔗RETURN VALUE result - string - path to the executable
🔗LIMITATIONS executable should be the basename of the executable without extensions</description>
🔗SYNOPSIS make a filename safe to pass as an argument
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local sanitized_filename = df.sanitize_filename(filename) filename - string - a filepath and filename
🔗DESCRIPTION sanitize_filename places quotes around the filename in an operating system specific manner. The result is safe to pass as an argument to the operating system.
🔗RETURN VALUE sanitized_filename - string - quoted filename</description>
🔗SYNOPSIS set a preference for the path to an executable
🔗USAGE local df = require &quot;lib/dtutils.file&quot; df.set_executable_path_preference(executable, path) executable - string - the name of the executable to set the path for
path - string - the path to the binary
🔗DESCRIPTION set_executable_path_preference takes an executable name and path to the executable and registers the preference for later use.</description>
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local result = df.test_file(path, test) path - string - path and filename test - char - one of d, e, f, x where
d - directory e - exists f - file x - executable 🔗DESCRIPTION test_file checks a specified path to see if it meets the specified test
🔗RETURN VALUE result - boolean - true if the path satisfies the test, false if not</description>
