org.erights.e.meta.java.io
Class FileSugar

java.lang.Object
  |
  +--org.erights.e.meta.java.io.FileSugar

public class FileSugar
extends Object

Untamed: A sweetener defining extra messages that may be e-sent to a File.

Since File isn't final, and none of its public instance methods are final, it would seem we should subclass it instead of sugarring it. However, our handling of URL and File are closely parallel and should stay so. Unfortunately, URL is declared final, and so must be dealt with by sugarring. Therefore, we continue to do so for File as well.

A File is made to act like it implements org.erights.e.elib.serial.Loader, which we would do if we were defining a subclass. It "implements" Loader to provide a loader specific to the directory tree rooted in itself.

Author:
Mark S. Miller

Field Summary
private static int BUF_SIZE
           
private static String NEWLINE
          platform newlines
 
Constructor Summary
private FileSugar()
          prevent instantiation
 
Method Summary
static void __printOn(File self, TextWriter out)
          Enabled: Normalize the E-printed form to use forward slashes as separators.
static void appendText(File self, String text)
          Enabled: Append to the file so the additional contents represents the string 'text', turning '\n's into platform newlines, and converting to UTF-8
private static String asUrl(File self)
          XXX should this be public? Should we use Java's File.toUrl() instead?
static ReadOnlyFile deepReadOnly(File self)
          Enabled: Returns a transitively read-only (or "Sensory") view of this file or directory.
static File get(File self, String name)
          Enabled: "Implements" org.erights.e.elib.serial.Loader#get
static String getAbsolutePath(File self)
          Enabled:
static byte[] getBytes(File self)
          Enabled: Returns the binary contents of the file as an array of bytes.
static String getCanonicalPath(File self)
          Enabled:
static BigInteger getCryptoHash(File self)
          Enabled: A SHA hash of the binary content of the file.
static String getParent(File self)
          Enabled:
static String getPath(File self)
          Enabled:
static String getPlatformPath(File self)
          Enabled:
static String getText(File self)
          Enabled: Gets the contents of the file as a String, normalizing newlines into '\n's.
static Twine getTwine(File self)
          Enabled: Gets the contents of the file as Twine (a text string that remembers where it came from), normalizing newlines into '\n's.
static boolean isNormal(File self)
          Enabled: Is this a "normal" file? (ie, a non-directory) This is the same test as self.isFile(), but less confusingly named.
static void iterate(File self, AssocFunc func)
          Enabled: Enumerates lineNumber => String (text line) associations.
static void iterate(File self, AssocFunc func, boolean isLocated)
          Enabled: If the file is a directory, enumerate filename => File associations for each child of the directory.
static Object[] optUncall(File self, Object obj)
          Enabled: "implements" org.erights.e.elib.serial.Loader#optUncall.
static void setBytes(File self, byte[] contents)
          Enabled: Sets the binary contents of the file to 'contents'.
static void setText(File self, String text)
          Enabled: Write the file so that its contents represents the string 'text', turning '\n's into platform newlines, and converting to UTF-8.
static ReadOnlyFile shallowReadOnly(File self)
          Enabled: Returns a one-level readOnly view of this file or directory.
static BufferedReader textReader(File self)
          Enabled: Open 'self' for reading text, decoding UTF-8 and turning platform newlines into '\n's
static TextWriter textWriter(File self)
          Enabled: 'append' argument defaults to false
static TextWriter textWriter(File self, boolean append)
          Enabled: Open 'self' for writing of appending text, encoded as UTF-8, with '\n's written as platform newlines.
private static void writeText(File self, String text, boolean append)
          Write the file (or append to the file) so that its contents represents the string 'text', turning '\n's into platform newlines, and converting to UTF-8
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NEWLINE

private static final String NEWLINE
platform newlines


BUF_SIZE

private static final int BUF_SIZE
Constructor Detail

FileSugar

private FileSugar()
prevent instantiation

Method Detail

shallowReadOnly

public static ReadOnlyFile shallowReadOnly(File self)
Enabled: Returns a one-level readOnly view of this file or directory.

If this is a directory, then the result gives read-only access to the directory itself, but undiminished access to the contents of the directory. If this is a non-directory, then the result gives read-only access to it.


deepReadOnly

public static ReadOnlyFile deepReadOnly(File self)
Enabled: Returns a transitively read-only (or "Sensory") view of this file or directory.

If this is a directory, then all contents fetched through this view will also result in a transitively read-only view of those contents.


appendText

public static void appendText(File self,
                              String text)
                       throws IOException
Enabled: Append to the file so the additional contents represents the string 'text', turning '\n's into platform newlines, and converting to UTF-8

IOException

getPath

public static String getPath(File self)
Enabled:


getAbsolutePath

public static String getAbsolutePath(File self)
Enabled:


getCanonicalPath

public static String getCanonicalPath(File self)
                               throws IOException
Enabled:

IOException

getPlatformPath

public static String getPlatformPath(File self)
Enabled:


getParent

public static String getParent(File self)
Enabled:


isNormal

public static boolean isNormal(File self)
Enabled: Is this a "normal" file? (ie, a non-directory) This is the same test as self.isFile(), but less confusingly named.


asUrl

private static String asUrl(File self)
XXX should this be public? Should we use Java's File.toUrl() instead?


__printOn

public static void __printOn(File self,
                             TextWriter out)
                      throws IOException
Enabled: Normalize the E-printed form to use forward slashes as separators. Also, E URI expressions have angle brackets arond them, so file objects print that way too. E'ers can still use getPath() to get the path as the File object sees it.

IOException

textReader

public static BufferedReader textReader(File self)
                                 throws FileNotFoundException
Enabled: Open 'self' for reading text, decoding UTF-8 and turning platform newlines into '\n's

FileNotFoundException

iterate

public static void iterate(File self,
                           AssocFunc func)
                    throws IOException
Enabled: Enumerates lineNumber => String (text line) associations.

Each text line ends with a "\n". isLocated defaults to false.

IOException

iterate

public static void iterate(File self,
                           AssocFunc func,
                           boolean isLocated)
                    throws IOException
Enabled: If the file is a directory, enumerate filename => File associations for each child of the directory.

Otherwise assume it's a text file and enumerates lineNumber => String/Twine (text line) associations. Like Perl, each text line ends with a "\n".

Parameters:
isLocated - If true, and if self is a non-directory, then enumerate text lines as Twine with location info rather than bare Strings.
IOException

getText

public static String getText(File self)
                      throws IOException
Enabled: Gets the contents of the file as a String, normalizing newlines into '\n's.

XXX should be made atomic.

IOException

getTwine

public static Twine getTwine(File self)
                      throws IOException
Enabled: Gets the contents of the file as Twine (a text string that remembers where it came from), normalizing newlines into '\n's.

XXX should be made atomic.

IOException

getCryptoHash

public static BigInteger getCryptoHash(File self)
                                throws NoSuchAlgorithmException,
                                       FileNotFoundException,
                                       IOException
Enabled: A SHA hash of the binary content of the file.

XXX should be made atomic.

NoSuchAlgorithmException
FileNotFoundException
IOException

getBytes

public static byte[] getBytes(File self)
                       throws IOException
Enabled: Returns the binary contents of the file as an array of bytes.

XXX should be made atomic.

IOException

setBytes

public static void setBytes(File self,
                            byte[] contents)
                     throws IOException
Enabled: Sets the binary contents of the file to 'contents'.

XXX Should be made atomic and crash-safe

IOException

setText

public static void setText(File self,
                           String text)
                    throws IOException
Enabled: Write the file so that its contents represents the string 'text', turning '\n's into platform newlines, and converting to UTF-8.

XXX Should be made atomic and crash-safe

IOException

textWriter

public static TextWriter textWriter(File self)
                             throws IOException
Enabled: 'append' argument defaults to false

IOException

textWriter

public static TextWriter textWriter(File self,
                                    boolean append)
                             throws IOException
Enabled: Open 'self' for writing of appending text, encoded as UTF-8, with '\n's written as platform newlines.

IOException

writeText

private static void writeText(File self,
                              String text,
                              boolean append)
                       throws IOException
Write the file (or append to the file) so that its contents represents the string 'text', turning '\n's into platform newlines, and converting to UTF-8

Should be made crash-safe

IOException

get

public static File get(File self,
                       String name)
Enabled: "Implements" org.erights.e.elib.serial.Loader#get


optUncall

public static Object[] optUncall(File self,
                                 Object obj)
Enabled: "implements" org.erights.e.elib.serial.Loader#optUncall.

Parameters:
self -
obj -
Returns:


comments?