Package org.machanism.machai.gw.tools

Class FileFunctionTools

java.lang.Object
org.machanism.machai.gw.tools.FileFunctionTools
All Implemented Interfaces:
FunctionTools
public class FileFunctionTools extends Object implements FunctionTools
Installs file-system tools into a ProcessProvider.

Tools in this installer are intended for host-integrated use where the host controls the base working directory. All paths provided to these tools are interpreted relative to the working directory supplied by the provider/runtime.

Installed tools

  • read_file – reads a file as text
  • write_file – writes a file (creating parent directories as needed)
  • list_files_in_directory – lists immediate children of a directory
Author:
Viktor Tovstyi

  • Field Details

    • DEFAULT_CHARSET

      private static final String DEFAULT_CHARSET
      Default character set used when reading or writing text files.
      See Also:

  • Constructor Details

    • FileFunctionTools

      public FileFunctionTools()

  • Method Details

    • listFiles

      public Map<String,List<String>> listFiles(File dirPath, File projectDir) throws IOException
      Lists the contents of a specified directory within a project, grouping the results into separate lists for directories and files using their relative paths.

      This method resolves the target directory using dirPath and projectDir, verifies that it is a valid directory, and iterates through its direct children. Each child is classified as either a directory or a file and its relative path is added to the corresponding list in the returned map.

      Parameters:
      dirPath - the path to the target directory to list contents of. Defaults to "." (current directory).
      projectDir - the root project directory used to compute relative paths for the listed files and folders.
      Returns:
      a Map containing two key-value pairs:
      • "directories" - a List of relative paths for all subdirectories found.
      • "files" - a List of relative paths for all files found.
      If the specified path is not a directory or is empty, the respective lists will be empty.
      Throws:
      IOException - if the directory cannot be accessed
      IllegalArgumentException - if either path is null, cannot be canonicalized, or the requested path is outside projectDir

    • collectRecursive

      private void collectRecursive(File currentDir, File projectDir, List<String> directories, List<String> files)
      Recursively collects directories and files below currentDir.
      Parameters:
      currentDir - directory whose children are being inspected
      projectDir - root used to compute project-relative paths
      directories - destination list for discovered directory paths
      files - destination list for discovered file paths

    • getRecursiveFiles

      public Object getRecursiveFiles(File path, int maxCount, File projectDir) throws IOException
      Lists files recursively in a directory up to a specified maximum limit.

      This AI functional tool returns the files discovered below a directory.

      Parameters:
      path - the relative or absolute path of the directory to scan
      maxCount - the maximum number of files allowed in the result; throws an error if exceeded
      projectDir - the root project directory context
      Returns:
      a List of relative file path strings, or a message string indicating no files were found
      Throws:
      IOException - if the directory cannot be accessed
      IllegalArgumentException - if the number of discovered files exceeds maxCount, or if the requested path is invalid or outside projectDir

    • collectFilesRecursive

      private void collectFilesRecursive(File currentDir, File projectDir, List<String> filePaths, int maxCount)
      Recursively collects files below currentDir, enforcing the result limit as files are discovered.
      Parameters:
      currentDir - directory whose children are being inspected
      projectDir - root used to compute project-relative paths
      filePaths - destination list for discovered file paths
      maxCount - maximum number of files permitted
      Throws:
      IllegalArgumentException - if the number of discovered files exceeds maxCount

    • getRecursiveFolders

      public Object getRecursiveFolders(File dir, int maxCount, File projectDir) throws IOException
      Implements get_recursive_folder_list.

      This AI functional tool recursively discovers and returns only the folder structure (directories) within a specified path. It does not return files or contents stored inside those folders.

      Parameters:
      dir - directory path relative to projectDir to start scanning from
      maxCount - maximum number of folders allowed in the result
      projectDir - project root used to resolve the directory
      Returns:
      project-relative folder paths as a list, or a message when none are found
      Throws:
      IOException - if the directory cannot be traversed
      IllegalArgumentException - if the number of discovered folders exceeds maxCount, or if the requested path is invalid or outside projectDir

    • writeFile

      public String writeFile(File filePath, String text, String charsetName, File projectDir) throws IOException
      Implements write_file.

      This AI functional tool creates or replaces a file with the supplied text.

      Parameters:
      filePath - file to create or replace, relative to projectDir
      text - content to write
      charsetName - character set used to encode the content
      projectDir - project root used to resolve the file
      Returns:
      a success message or an error message when writing fails
      Throws:
      IOException - if the file cannot be created or written
      IllegalArgumentException - if the requested path is invalid or outside projectDir

    • writeFileContent

      private void writeFileContent(File file, String content, String charsetName) throws IOException
      Writes content to file using charsetName.
      Parameters:
      file - destination file
      content - content to write
      charsetName - character set name
      Throws:
      IOException - if writing fails
      IllegalArgumentException - if charsetName does not identify a supported character set

    • writeNewFile

      private String writeNewFile(File file, String text, String charsetName, File filePath) throws IOException
      Creates the file (and parent directories as needed) and writes text using the requested character set.
      Parameters:
      file - file to create
      text - content
      charsetName - character set name
      filePath - original (relative) file path used for messaging
      Returns:
      success message
      Throws:
      IOException - if an I/O error occurs
      IllegalArgumentException - if charsetName does not identify a supported character set

    • readFile

      public String readFile(File filePath, String charsetName, int maxFileSize, File projectDir, Configurator configurator) throws IOException
      Implements read_file.

      This AI functional tool reads a file and returns its text content.

      Parameters:
      filePath - file to read, relative to projectDir
      charsetName - the name of the requested charset used to decode the file
      maxFileSize - the maximum allowed character length of the file content
      projectDir - project root used to resolve the file
      configurator - configuration used to substitute URL and header values
      Returns:
      the complete file contents as text
      Throws:
      IOException - if the file does not exist, is a directory, or cannot be read
      IllegalArgumentException - if the file content length exceeds the allowed maxFileSize limit, the requested path is invalid or outside projectDir, or charsetName does not identify a supported character set

    • getFile

      File getFile(File filePath, File projectDir) throws IOException
      Resolves a requested path beneath the canonical project root.
      Parameters:
      filePath - requested file or directory
      projectDir - project root
      Returns:
      canonical file located under the project root
      Throws:
      IOException - if the file cannot be resolved
      IllegalArgumentException - if a path is invalid or escapes the root

    • getRelativePath

      public static String getRelativePath(File dir, File file, boolean addSingleDot)
      Computes a project-relative path string.

      The returned path always uses forward slashes (/) for consistency across platforms.

      Parameters:
      dir - base directory used to relativize the file
      file - target file or directory
      addSingleDot - whether to prefix relative path with ./
      Returns:
      relative path, . if dir equals file, or null when either argument is null or the paths cannot be relativized (for example, because they use different roots)

    • applyPatchToFile

      public String applyPatchToFile(File file, String patch, String charsetName, File projectDir)
      Implements apply_patch_to_file.

      This AI functional tool applies a targeted unified or simplified search-and-replace patch to a file within the project directory.

      Parameters:
      file - path of the file to patch, relative to projectDir
      patch - patch content in a supported format
      charsetName - character set used to read and write the file
      projectDir - project root used to resolve the file
      Returns:
      a success message, or a failure message containing the underlying error detail