Package ghidra.program.model.sourcemap

# Interface SourcePathTransformer

All Known Implementing Classes:
  `UserDataPathTransformer`

public interface SourcePathTransformer
SourcePathTransformers are used to transform `SourceFile` paths. The intended use is to transform the path of a `SourceFile` in a programs's `SourceFileManager` before sending the path to an IDE.

There are two types of transformations: file and directory. File transforms map a particular `SourceFile` to an absolute file path. Directory transforms transform an initial segment of a path. For example, the directory transforms "/c:/users/" -> "/src/test/" sends "/c:/users/dir/file1.c" to "/src/test/dir/file1.c"

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDirectoryTransform(String sourceDir, String targetDir)`
  Adds a new directory transform.
  `void`
  `addFileTransform(SourceFile sourceFile, String path)`
  Adds a new file transform.
  `String`
  `getTransformedPath(SourceFile sourceFile, boolean useExistingAsDefault)`
  Returns the transformed path for `sourceFile`.
  `List<SourcePathTransformRecord>`
  `getTransformRecords()`
  Returns a list of all `SourcePathTransformRecord`s
  `void`
  `removeDirectoryTransform(String sourceDir)`
  Removes any directory transform associated with `sourceDir`
  `void`
  `removeFileTransform(SourceFile sourceFile)`
  Removes any file transform for `sourceFile`.

- ## Method Details

  - ### addFileTransform

    void addFileTransform(SourceFile sourceFile, String path)
    Adds a new file transform. Any existing file transform for `sourceFile` is overwritten. `path` must be a valid, normalized file path (with forward slashes).
    Parameters:
      `sourceFile` - source file (can't be null).
      `path` - new path

  - ### removeFileTransform

    void removeFileTransform(SourceFile sourceFile)
    Removes any file transform for `sourceFile`.
    Parameters:
      `sourceFile` - source file

  - ### addDirectoryTransform

    void addDirectoryTransform(String sourceDir, String targetDir)
    Adds a new directory transform. Any existing directory transform for `sourceDir` is overwritten. `sourceDir` and `targetDir` must be valid, normalized directory paths (with forward slashes).
    Parameters:
      `sourceDir` - source directory
      `targetDir` - target directory

  - ### removeDirectoryTransform

    void removeDirectoryTransform(String sourceDir)
    Removes any directory transform associated with `sourceDir`
    Parameters:
      `sourceDir` - source directory

  - ### getTransformedPath

    String getTransformedPath(SourceFile sourceFile, boolean useExistingAsDefault)
    Returns the transformed path for `sourceFile`. The transformed path is determined as follows:
    - If there is a file transform for `sourceFile`, the file transform is applied.
    - Otherwise, the most specific directory transform (i.e., longest source directory string) is applied.
    - If no directory transform applies, the value of `useExistingAsDefault` determines whether the path of `sourceFile` or `null` is returned.
    Parameters:
      `sourceFile` - source file to transform
      `useExistingAsDefault` - whether to return sourceFile's path if no transform applies
    Returns:
      transformed path or null

  - ### getTransformRecords

    List<SourcePathTransformRecord> getTransformRecords()
    Returns a list of all `SourcePathTransformRecord`s
    Returns:
      transform records