🔗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>
🔗USAGE local df = require &quot;lib/dtutils.file&quot; local result = df.check_if_bin_exists(bin) bin - string - the binary to check for
🔗DESCRIPTION check_if_bin_exists checks to see if the specified binary exists. check_if_bin_exists first checks to see if a preference for the binary has been registered and uses that if found. The presence of the file is verified, then quoted and returned. If no preference is specified and the operating system is linux then the which command is used to check for a binary in the path.</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>
