Package de.unibremen.informatik.st.libvcs4j

Interface VCSFile

  • All Superinterfaces:
    VCSModelElement
    public interface VCSFile
extends VCSModelElement
    Represents a file in a VCS at a certain point in time. For the sake of convenience, we use the name "VCSFile" instead of "File" to avoid naming collisions with File.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  VCSFile.Position
      A position within a file.
      static interface  VCSFile.Range
      A range within a file.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default java.lang.String getPath()
      Returns the absolute path of this file as it was like when its corresponding revision was checked out by VCSEngine.next().
      java.lang.String getRelativePath()
      Returns the relative path of this file as it was like when its corresponding revision was checked out by VCSEngine.next().
      Revision getRevision()
      Returns the Revision of this file.
      default java.util.Optional<java.nio.charset.Charset> guessCharset()
      Tries to guess the charset of this file.
      default boolean isBinary()
      Tries to guess whether this file is a binary file.
      default java.util.Optional<VCSFile.Position> positionAt​(int line, int lineOffset, int tabSize)
      Creates a position from the given line, line offset, and tab size.
      default java.util.Optional<VCSFile.Position> positionOf​(int offset, int tabSize)
      Creates a position from the given offset and tab size.
      default java.util.Optional<VCSFile.Position> positionOf​(int line, int column, int tabSize)
      Creates a position from the given line, column, and tab size.
      default byte[] readAllBytes()
      Returns the contents of this file.
      default java.lang.String readContent()
      Returns the content of this file as a String.
      default java.util.List<LineInfo> readLineInfo()
      Reads the line information of this file.
      default java.util.List<java.lang.String> readLines()
      Returns the content of this file as a list of strings excluding EOL characters.
      default java.util.List<java.lang.String> readLinesWithEOL()
      Returns the content of this file as a list of strings including EOL characters.
      default java.io.File toFile()
      Returns a File object (absolute path) representing this file.
      default java.nio.file.Path toPath()
      Returns the absolute path of this file as Path.
      default java.io.File toRelativeFile()
      Returns a File object (relative path) representing this file.
      default java.nio.file.Path toRelativePath()
      Returns the relative path of this file as Path.

    • Method Detail

      • getRelativePath

        java.lang.String getRelativePath()
        Returns the relative path of this file as it was like when its corresponding revision was checked out by VCSEngine.next().

        The path is relative to VCSEngine.getOutput().

        Returns:
        The relative path of this file.

      • guessCharset

        default java.util.Optional<java.nio.charset.Charset> guessCharset()
                                                           throws java.io.IOException
        Tries to guess the charset of this file.
        Returns:
        The guessed charset.
        Throws:
        java.io.IOException - If an error occurred while reading the contents of this file.

      • getPath

        default java.lang.String getPath()
        Returns the absolute path of this file as it was like when its corresponding revision was checked out by VCSEngine.next().
        Returns:
        The absolute path of this file.

      • readAllBytes

        default byte[] readAllBytes()
                     throws java.io.IOException
        Returns the contents of this file.
        Returns:
        The contents of this file.
        Throws:
        java.io.IOException - If an error occurred while reading the contents.

      • readContent

        default java.lang.String readContent()
                              throws java.io.IOException
        Returns the content of this file as a String. The default implementation uses readAllBytes() and guessCharset() to create an appropriate String. If guessCharset() returns an empty optional the system default charset is used as fallback.
        Returns:
        The content of this file as a String.
        Throws:
        BinaryFileException - If this file is binary (see isBinary()).
        java.io.IOException - If an error occurred while reading the file content.

      • readLines

        default java.util.List<java.lang.String> readLines()
                                            throws java.io.IOException
        Returns the content of this file as a list of strings excluding EOL characters.
        Returns:
        The content of this file as a list of strings excluding EOLs.
        Throws:
        BinaryFileException - If this file is binary (see isBinary()).
        java.io.IOException - If an error occurred while reading the file content.

      • readLinesWithEOL

        default java.util.List<java.lang.String> readLinesWithEOL()
                                                   throws java.io.IOException
        Returns the content of this file as a list of strings including EOL characters. The following EOLs are supported: '\n', '\r\n', '\r'.
        Returns:
        The content of this file as a list of strings including EOLs.
        Throws:
        BinaryFileException - If this file is binary (see isBinary()).
        java.io.IOException - If an error occurred while reading the file content.

      • readLineInfo

        default java.util.List<LineInfo> readLineInfo()
                                       throws java.io.IOException
        Reads the line information of this file.
        Returns:
        The line information of this file.
        Throws:
        BinaryFileException - If this file is binary (see isBinary()).
        java.io.IOException - If an error occurred while reading the the information.

      • isBinary

        default boolean isBinary()
                  throws java.io.IOException
        Tries to guess whether this file is a binary file. The default implementation uses Files.probeContentType(Path) to check whether the detected file type (if any) matches one of the predefined values. If Files.probeContentType(Path) is unable to detect the file type, the number of ASCII and non-ASCII chars is counted and evaluated.
        Returns:
        true if this file is a binary file, false otherwise.
        Throws:
        java.io.IOException - If an error occurred while reading the file contents.

      • toFile

        default java.io.File toFile()
        Returns a File object (absolute path) representing this file.
        Returns:
        A File object (absolute path) representing this file.

      • toRelativeFile

        default java.io.File toRelativeFile()
        Returns a File object (relative path) representing this file.
        Returns:
        A File object (relative path) representing this file.

      • toPath

        default java.nio.file.Path toPath()
        Returns the absolute path of this file as Path.
        Returns:
        The absolute path of this file as Path.

      • toRelativePath

        default java.nio.file.Path toRelativePath()
        Returns the relative path of this file as Path.
        Returns:
        The relative path of this file as Path.

      • positionOf

        default java.util.Optional<VCSFile.Position> positionOf​(int offset,
                                                        int tabSize)
                                                 throws java.lang.IllegalArgumentException,
                                                        java.io.IOException
        Creates a position from the given offset and tab size. Returns an empty Optional if there is no position for offset, or if offset points to a new line delimiter.
        Parameters:
        offset - The number of characters to move to reach a position.
        tabSize - The number of characters acquired by a tab (\t).
        Returns:
        The corresponding position.
        Throws:
        java.lang.IllegalArgumentException - If offset < 0 or tabSize < 1.
        BinaryFileException - If this file is binary (see isBinary()).
        java.io.IOException - If an error occurred while reading the file content.

      • positionOf

        default java.util.Optional<VCSFile.Position> positionOf​(int line,
                                                        int column,
                                                        int tabSize)
                                                 throws java.lang.IllegalArgumentException,
                                                        java.io.IOException
        Creates a position from the given line, column, and tab size. Returns an empty Optional if there is no position for line and column with respect to tabSize, or if line and column with respect to tabSize point to a new line delimiter.
        Parameters:
        line - The line of the position to create.
        column - The column of the position to create.
        tabSize - The number of characters acquired by a tab (\t).
        Returns:
        The corresponding position.
        Throws:
        java.lang.IllegalArgumentException - If line < 1, column < 1, or tabSize < 1.
        BinaryFileException - If this file is binary (see isBinary()).
        java.io.IOException - If an error occurred while reading the file content.

      • positionAt

        default java.util.Optional<VCSFile.Position> positionAt​(int line,
                                                        int lineOffset,
                                                        int tabSize)
                                                 throws java.lang.IllegalArgumentException,
                                                        java.io.IOException
        Creates a position from the given line, line offset, and tab size. Returns an empty Optional if there is no position for line and lineOffset, or if line and lineOffset point to a new line delimiter.
        Parameters:
        line - The line of the position to create.
        lineOffset - The line offset of the position to create.
        tabSize - The number of characters acquired by a tab (\t).
        Returns:
        The corresponding position.
        Throws:
        java.lang.IllegalArgumentException - If line < 1, lineOffset < 0, or tabSize < 1.
        BinaryFileException - If this file is binary (see isBinary()).
        java.io.IOException - If an error occurred while reading the file content.