Package org.plumelib.util

Class FilesP

java.lang.Object
org.plumelib.util.FilesP
public final class FilesP extends Object
Utility methods that create and manipulate files, directories, streams, readers, and writers.

  • Method Details

    • newFileInputStream

      @SideEffectFree public static InputStream newFileInputStream(Path path) throws IOException
      Returns an InputStream for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      path - the possibly-compressed file to read
      Returns:
      an InputStream for file
      Throws:
      NoSuchFileException - if the file does not exist. Note that this is not FileNotFoundException, which the java.io file constructors throw.
      IOException - if there is trouble reading the file

    • newFileInputStream

      @SideEffectFree public static InputStream newFileInputStream(File file) throws IOException
      Returns an InputStream for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to read
      Returns:
      an InputStream for file
      Throws:
      NoSuchFileException - if the file does not exist. Note that this is not FileNotFoundException, which the java.io file constructors throw.
      IOException - if there is trouble reading the file

    • newFileReader

      @SideEffectFree public static InputStreamReader newFileReader(String filename) throws IOException
      Returns a Reader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      filename - the possibly-compressed file to read
      Returns:
      an InputStreamReader for filename
      Throws:
      IOException - if there is trouble reading the file

    • newFileReader

      @SideEffectFree public static InputStreamReader newFileReader(Path path) throws IOException
      Returns a Reader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      path - the possibly-compressed file to read
      Returns:
      an InputStreamReader for file
      Throws:
      IOException - if there is trouble reading the file

    • newFileReader

      @SideEffectFree public static InputStreamReader newFileReader(Path path, @Nullable Charset charset) throws IOException
      Returns a Reader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      path - the possibly-compressed file to read
      charset - the charset to use when reading the file, or null to use UTF-8
      Returns:
      an InputStreamReader for file
      Throws:
      IOException - if there is trouble reading the file

    • newFileReader

      @SideEffectFree public static InputStreamReader newFileReader(File file) throws IOException
      Returns a Reader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to read
      Returns:
      an InputStreamReader for file
      Throws:
      IOException - if there is trouble reading the file

    • newFileReader

      @SideEffectFree public static InputStreamReader newFileReader(File file, @Nullable Charset charset) throws IOException
      Returns a Reader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to read
      charset - the charset to use when reading the file, or null to use UTF-8
      Returns:
      an InputStreamReader for file
      Throws:
      IOException - if there is trouble reading the file

    • newBufferedFileReader

      @SideEffectFree public static BufferedReader newBufferedFileReader(String filename) throws IOException
      Returns a BufferedReader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      filename - the possibly-compressed file to read
      Returns:
      a BufferedReader for file
      Throws:
      IOException - if there is trouble reading the file

    • newBufferedFileReader

      @SideEffectFree public static BufferedReader newBufferedFileReader(File file) throws IOException
      Returns a BufferedReader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to read
      Returns:
      a BufferedReader for file
      Throws:
      IOException - if there is trouble reading the file

    • newBufferedFileReader

      @SideEffectFree public static BufferedReader newBufferedFileReader(String filename, @Nullable Charset charset) throws IOException
      Returns a BufferedReader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      filename - the possibly-compressed file to read
      charset - the character set to use when reading the file, or null to use UTF-8
      Returns:
      a BufferedReader for filename
      Throws:
      IOException - if there is trouble reading the file

    • newBufferedFileReader

      @SideEffectFree public static BufferedReader newBufferedFileReader(File file, @Nullable Charset charset) throws IOException
      Returns a BufferedReader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to read
      charset - the character set to use when reading the file, or null to use UTF-8
      Returns:
      a BufferedReader for file
      Throws:
      IOException - if there is trouble reading the file

    • newLineNumberFileReader

      @SideEffectFree public static LineNumberReader newLineNumberFileReader(String filename) throws IOException
      Returns a LineNumberReader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      filename - the possibly-compressed file to read
      Returns:
      a LineNumberReader for filename
      Throws:
      IOException - if there is trouble reading the file

    • newLineNumberFileReader

      @SideEffectFree public static LineNumberReader newLineNumberFileReader(File file) throws IOException
      Returns a LineNumberReader for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to read
      Returns:
      a LineNumberReader for file
      Throws:
      IOException - if there is trouble reading the file

    • newFileOutputStream

      @SideEffectFree public static OutputStream newFileOutputStream(Path path) throws IOException
      Returns an OutputStream for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      path - the possibly-compressed file to write
      Returns:
      an OutputStream for file
      Throws:
      IOException - if there is trouble writing the file

    • newFileOutputStream

      @SideEffectFree public static OutputStream newFileOutputStream(Path path, boolean append) throws IOException
      Returns an OutputStream for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)

      If the file name ends with ".gz" and append is true, the result writes a new gzip member rather than extending the gzip member that the file already contains. newFileInputStream(Path) reads all the concatenated members, so the file reads back as the concatenation of everything that was written to it.

      Parameters:
      path - the possibly-compressed file to write
      append - if true, then bytes will be written to the end of the file rather than the beginning
      Returns:
      an OutputStream for file
      Throws:
      IOException - if there is trouble writing the file

    • newFileOutputStream

      @SideEffectFree public static OutputStream newFileOutputStream(File file) throws IOException
      Returns an OutputStream for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to write
      Returns:
      an OutputStream for file
      Throws:
      IOException - if there is trouble writing the file

    • newFileWriter

      @SideEffectFree public static OutputStreamWriter newFileWriter(String filename) throws IOException
      Returns a Writer for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      filename - the possibly-compressed file to write
      Returns:
      an OutputStreamWriter for filename
      Throws:
      IOException - if there is trouble writing the file

    • newFileWriter

      @SideEffectFree public static OutputStreamWriter newFileWriter(Path path) throws IOException
      Returns a Writer for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      path - the possibly-compressed file to write
      Returns:
      an OutputStreamWriter for file
      Throws:
      IOException - if there is trouble writing the file

    • newFileWriter

      @SideEffectFree public static OutputStreamWriter newFileWriter(Path path, @Nullable Charset charset) throws IOException
      Returns a Writer for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      path - the possibly-compressed file to write
      charset - the charset to use when writing the file, or null to use UTF-8
      Returns:
      an OutputStreamWriter for file
      Throws:
      IOException - if there is trouble writing the file

    • newFileWriter

      @SideEffectFree public static OutputStreamWriter newFileWriter(File file) throws IOException
      Returns a Writer for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to write
      Returns:
      an OutputStreamWriter for file
      Throws:
      IOException - if there is trouble writing the file

    • newFileWriter

      @SideEffectFree public static OutputStreamWriter newFileWriter(File file, @Nullable Charset charset) throws IOException
      Returns a Writer for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      file - the possibly-compressed file to write
      charset - the charset to use when writing the file, or null to use UTF-8
      Returns:
      an OutputStreamWriter for file
      Throws:
      IOException - if there is trouble writing the file

    • newBufferedFileWriter

      @SideEffectFree public static BufferedWriter newBufferedFileWriter(String filename) throws IOException
      Returns a BufferedWriter for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)
      Parameters:
      filename - the possibly-compressed file to write
      Returns:
      a BufferedWriter for filename
      Throws:
      IOException - if there is trouble writing the file

    • newBufferedFileWriter

      @SideEffectFree public static BufferedWriter newBufferedFileWriter(String filename, boolean append) throws IOException
      Returns a BufferedWriter for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)

      If the file name ends with ".gz" and append is true, the result writes a new gzip member rather than extending the gzip member that the file already contains. newBufferedFileReader(String) reads all the concatenated members, so the file reads back as the concatenation of everything that was written to it.

      Parameters:
      filename - the possibly-compressed file to write
      append - if true, the resulting BufferedWriter appends to the end of the file instead of the beginning
      Returns:
      a BufferedWriter for filename
      Throws:
      IOException - if there is trouble writing the file

    • newBufferedFileOutputStream

      @SideEffectFree public static BufferedOutputStream newBufferedFileOutputStream(String filename, boolean append) throws IOException
      Returns a BufferedOutputStream for the file, accounting for the possibility that the file is compressed. (A file whose name ends with ".gz" is treated as compressed.)

      If the file name ends with ".gz" and append is true, the result writes a new gzip member rather than extending the gzip member that the file already contains. newFileInputStream(File) reads all the concatenated members, so the file reads back as the concatenation of everything that was written to it.

      Parameters:
      filename - the possibly-compressed file to write
      append - if true, the resulting BufferedOutputStream appends to the end of the file instead of the beginning
      Returns:
      a BufferedOutputStream for filename
      Throws:
      IOException - if there is trouble writing the file

    • countLines

      @Pure public static long countLines(String filename) throws IOException
      Counts the number of lines in the specified file.
      Parameters:
      filename - file whose size to count
      Returns:
      number of lines in filename
      Throws:
      IOException - if there is trouble reading the file

    • inferLineSeparator

      @Pure public static @Regex String inferLineSeparator(String filename) throws IOException
      Tries to infer the line separator used in a file.
      Parameters:
      filename - the file to infer a line separator from
      Returns:
      the inferred line separator used in filename
      Throws:
      IOException - if there is trouble reading the file

    • inferLineSeparator

      @Pure public static @Regex String inferLineSeparator(File file) throws IOException
      Tries to infer the line separator used in a file.
      Parameters:
      file - the file to infer a line separator from
      Returns:
      the inferred line separator used in filename
      Throws:
      IOException - if there is trouble reading the file

    • equalFiles

      @Pure public static boolean equalFiles(String file1, String file2)
      Returns true iff files have the same contents.
      Parameters:
      file1 - first file to compare
      file2 - second file to compare
      Returns:
      true iff the files have the same contents

    • equalFiles

      @Pure public static boolean equalFiles(String file1, String file2, boolean trimLines)
      Returns true iff the files have the same contents.
      Parameters:
      file1 - first file to compare
      file2 - second file to compare
      trimLines - if true, call String.trim on each line before comparing
      Returns:
      true iff the files have the same contents

    • canCreateAndWrite

      @SideEffectFree public static boolean canCreateAndWrite(File file)
      Returns true if the file exists and is writable, or if the file can be created.
      Parameters:
      file - the file to create and write
      Returns:
      true iff the file can be created and written

    • createTempFile

      public static Path createTempFile(String prefix, String suffix, FileAttribute<?>... attrs) throws IOException
      Creates a new empty file in the default temporary-file directory, using the given prefix and suffix strings to generate its name. This is like File.createTempFile(java.lang.String, java.lang.String, java.io.File), but uses sequential file names.
      Parameters:
      prefix - the prefix string to be used in generating the file's name; may be null
      suffix - the suffix string to be used in generating the file's name; may be null, in which case ".tmp" is used
      attrs - an optional list of file attributes to set atomically when creating the file
      Returns:
      the path to the newly created file that did not exist before this method was invoked
      Throws:
      IOException - if there is trouble creating the file

    • createTempFile

      public static Path createTempFile(Path dir, String prefix, String suffix, FileAttribute<?>... attrs) throws IOException
      Creates a new empty file in the specified directory, using the given prefix and suffix strings to generate its name. This is like File.createTempFile(java.lang.String, java.lang.String, java.io.File), but uses sequential file names.
      Parameters:
      dir - the path to directory in which to create the file
      prefix - the prefix string to be used in generating the file's name; may be null
      suffix - the suffix string to be used in generating the file's name; may be null, in which case ".tmp" is used
      attrs - an optional list of file attributes to set atomically when creating the file
      Returns:
      the path to the newly created file that did not exist before this method was invoked
      Throws:
      IOException - if there is trouble creating the file

    • createTempDir

      public static File createTempDir(String prefix, String suffix) throws IOException
      Creates an empty directory in the default temporary-file directory, using the given prefix and suffix to generate its name. For example, calling createTempDir("myPrefix", "mySuffix") will create the following directory: temporaryFileDirectory/myUserName/myPrefix_someString_suffix. someString is internally generated to ensure no temporary files of the same name are generated.
      Parameters:
      prefix - the prefix string to be used in generating the file's name; must be at least three characters long
      suffix - the suffix string to be used in generating the file's name; may be null, in which case the suffix ".tmp" will be used Returns: An abstract pathname denoting a newly-created empty file
      Returns:
      a File representing the newly-created temporary directory
      Throws:
      IllegalArgumentException - If the prefix argument contains fewer than three characters
      IOException - If a file could not be created
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method does not allow a file to be created
      See Also:

    • deleteDir

      public static boolean deleteDir(String dirName)
      Deletes the directory at dirName and all its files. Also works on regular files.
      Parameters:
      dirName - the directory to delete
      Returns:
      true if and only if the file or directory is successfully deleted; false otherwise

    • deleteDir

      public static boolean deleteDir(File dir)
      Deletes the directory at dir and all its files. Also works on regular files.
      Parameters:
      dir - the directory to delete
      Returns:
      true if and only if the file or directory is successfully deleted; false otherwise

    • createDirectory

      public static Path createDirectory(Path dir, FileAttribute<?>... attrs)
      Creates a new directory. Like Files.createDirectory(java.nio.file.Path, java.nio.file.attribute.FileAttribute<?>...), but does not throw any checked exceptions.
      Parameters:
      dir - the directory to create
      attrs - an optional list of file attributes to set atomically when creating the directory
      Returns:
      the directory

    • createDirectories

      public static Path createDirectories(Path dir, FileAttribute<?>... attrs)
      Creates a directory by creating all nonexistent parent directories first. Unlike the createDirectory method, an exception is not thrown if the directory could not be created because it already exists. Like Files.createDirectories(java.nio.file.Path, java.nio.file.attribute.FileAttribute<?>...), but does not throw any checked exceptions.
      Parameters:
      dir - the directory to create
      attrs - an optional list of file attributes to set atomically when creating the directory
      Returns:
      the directory

    • expandFilename

      @SideEffectFree public static File expandFilename(File name)
      Does tilde expansion on a file name (to the user's home directory).
      Parameters:
      name - file whose name to expand
      Returns:
      file with expanded file

    • expandFilename

      @SideEffectFree public static String expandFilename(String name)
      Does tilde expansion on a file name (to the user's home directory).
      Parameters:
      name - filename to expand
      Returns:
      expanded filename

    • javaSource

      @SideEffectFree public static String javaSource(File name)
      Returns a string version of the filename that can be used in Java source. On Windows, the file will return a backslash-separated string. Since backslash is an escape character, it must be quoted itself inside the string.

      The current implementation presumes that backslashes don't appear in filenames except as Windows path separators. That seems like a reasonable assumption.

      Parameters:
      name - file whose name to quote
      Returns:
      a string version of the name that can be used in Java source

    • writeObject

      public static void writeObject(Object o, File file) throws IOException
      Writes an Object to a File.
      Parameters:
      o - the object to write
      file - the file to which to write the object
      Throws:
      IOException - if there is trouble writing the file

    • readObject

      @SideEffectFree public static Object readObject(File file) throws IOException, ClassNotFoundException
      Reads an Object from a File. This is a wrapper around ObjectInputStream.readObject(), but it takes a File as an argument. Note that use of that method can lead to security vulnerabilities. Only run the method on trusted files.
      Parameters:
      file - the file from which to read
      Returns:
      the object read from the file
      Throws:
      IOException - if there is trouble reading the file
      ClassNotFoundException - if the object's class cannot be found

    • readerContents

      public static String readerContents(Reader r)
      Reads the entire contents of the reader and returns it as a string. Any IOException encountered will be turned into an Error.
      Parameters:
      r - the Reader to read; this method exhausts it and closes it
      Returns:
      the entire contents of the reader, as a string

    • readString

      @SideEffectFree public static String readString(Path path)
      Reads the entire contents of the file and returns it as a string.

      The point of this method is that it does not throw any checked exception: any IOException encountered will be turned into an Error.

      Parameters:
      path - the path to the file
      Returns:
      a String containing the content read from the file

    • readLinesRetainingSeparators

      @SideEffectFree public static List<String> readLinesRetainingSeparators(Path path)
      Reads the entire contents of the file and returns it as a list of lines. Each line ends with a line separator (except perhaps the last line).
      Parameters:
      path - the path to the file
      Returns:
      the lines of the file

    • writeString

      public static void writeString(File file, String contents)
      Creates a file with the given name and writes the specified string to it. If the file currently exists (and is writable) it is overwritten.

      The point of this method is that it does not throw any checked exception: any IOException encountered will be turned into an Error.

      Parameters:
      file - the file to write to
      contents - the text to put in the file

    • writeString

      public static void writeString(Path path, String contents)
      Creates a file with the given name and writes the specified string to it. If the file currently exists (and is writable) it is overwritten. Any IOException encountered will be turned into an Error.

      The point of this method is that it does not throw any checked exception: any IOException encountered will be turned into an Error.

      Parameters:
      path - the path to write to
      contents - the text to put in the file

    • streamCopy

      public static void streamCopy(InputStream from, OutputStream to)
      Copies the contents of the input stream to the output stream.
      Parameters:
      from - input stream
      to - output stream

    • streamString

      public static String streamString(InputStream is)
      Returns a String containing all the characters from the input stream.
      Parameters:
      is - input stream to read
      Returns:
      a String containing all the characters from the input stream

    • streamLines

      public static List<String> streamLines(InputStream stream) throws IOException
      Reads all lines from the stream and returns them in a List<String>.
      Parameters:
      stream - the stream to read from
      Returns:
      the list of lines read from the stream
      Throws:
      IOException - if there is an error reading from the stream

    • available

      public static @Nullable Integer available(InputStream is)
      Calls InputStream.available(), but returns null instead of throwing an IOException.
      Parameters:
      is - an input stream
      Returns:
      is.available(), or null if that throws an exception

    • isWhitespaceOnly

      public static @Nullable Boolean isWhitespaceOnly(InputStream is, @org.checkerframework.checker.index.qual.Positive int readLimit)
      Returns true if the first readLimit code points of the input stream consist only of whitespace.

      This method resets the input stream to its original position before returning, even when this method throws an exception. If the reset fails, the input stream is left positioned after the bytes that this method consumed, which may be one byte beyond the code points that this method examined; see readCodePoint(java.io.InputStream).

      Parameters:
      is - an input stream
      readLimit - how many code points to look ahead in the input stream
      Returns:
      null if !is.markSupported(); otherwise, true if the first readLimit code points of the input stream consist only of whitespace
      Throws:
      IllegalArgumentException - if the input stream contains a byte that cannot start a UTF-8 character; see readCodePoint(java.io.InputStream)
      UncheckedIOException - if there is trouble reading the input stream

    • readCodePoint

      public static int readCodePoint(InputStream is)
      Reads a Unicode code point from an input stream.

      If the stream ends in the middle of a multi-byte UTF-8 character, the truncated bytes are decoded, which yields the replacement character U+FFFD.

      If a byte within a multi-byte UTF-8 character is not a continuation byte, the bytes that were read are decoded, which yields the replacement character U+FFFD. The byte that is not a continuation byte has already been consumed and an InputStream does not support pushback, so the character that the offending byte starts is lost.

      This method throws an exception only for a first byte that cannot start any UTF-8 character. Other malformed input, such as an overlong encoding or an encoding of a code point above U+10FFFF, is decoded, which yields the replacement character U+FFFD.

      Parameters:
      is - an input stream
      Returns:
      the Unicode code point for the next character in the input stream, or -1 if the stream is at end of file
      Throws:
      IllegalArgumentException - if the bit pattern of the next byte is 10xxxxxx or 11111xxx, neither of which can start a UTF-8 character
      UncheckedIOException - if there is trouble reading the stream