com.blackperl.Perl
Class Chomp

java.lang.Object
  |
  +--com.blackperl.Perl.Chomp

public final class Chomp

extends java.lang.Object

Static-method implementation of the Perl chomp keyword. The chomp keyword is a safer version of chop (see Chop) that only removes line-ending characters/sequences.

Like chop, chomp removes characters from the end of a StringBuffer object. The return value from the operation is different, however. In this case, the return value is the number of characters deleted, rather than the specific characters themselves. When operating on an array of StringBuffer objects, the value is the total number of characters deleted from all buffers. Note that only those character exactly matching the line.separator property are removed (and only the very last characters, in cases where multiple occurances are in a single buffer).

Here is an example, built around reading a file using the standard JDK BufferedReader class for line-oriented data:

     import java.io.*;
     import com.blackperl.Perl.Chomp;
 
     StringBuffer[] lines = new StringBuffer[1000];
     BufferedReader reader = new BufferedReader(new FileReader("lines"));
     String line = null; int index = 0;
 
     while ((line = reader.readLine()) != null)
     {
         lines[index] = new StringBuffer(line);
         Chomp.chomp(lines[index]);
         index++;
     }
 
     reader.close();
 

Using the array form of chomp, the loop can be shortened to:

     while ((line = reader.readLine()) != null)
         lines[index++] = new StringBuffer(line);
     Chomp.chomp(lines);
 

The resulting content of lines would be the same.

To keep with the Perl idiom this emulates, the argument may also be an object that implements the Map interface. If this is the case, all the values (not keys) must be StringBuffer objects. All will be chomped, just as with the array-form above (which also means that the return value is the sum of all operations). This is the only form of chomp that might throw a significant exception, in the case where the value in a Map entry cannot be cast to StringBuffer.

There are three modes of operation, based on the value of the record separator when the method is called. In normal operation, when the separator has a value that is not zero-length or null, that value is removed from the end of the string (if present) exactly once. If the separator is a zero-length (but not null) string, then chomp operates in what Perl calls "paragraph mode". In this mode, all the trailing instances of the "\n" character are removed (since the separator is empty, it cannot be used as a guide). The string "abc\n\n\n" would be chomped into "abc". Lastly, if the separator's value is null, this is a mode that Perl calls "slurping". In that mode, no chomping actually takes place. However many newline characters may be at the end of the buffer, it remains unchanged. This is all controllable through the setRecordSeparator method.

All components in this package provide an instance method to retrieve a singleton object which may be used to call the static methods, if the programmer prefers using an object to static invocation.

If this is the JDK 1.5 ("Tiger") edition of the package, this class is suitable for use via static import:

     // Using most of the code from the previous example, the changes are:
     import com.blackperl.Perl.Chomp.chomp;
 
     while ((line = reader.readLine()) != null)
         lines[index++] = new StringBuffer(line);
     chomp(lines);
 

Method Summary

static int	chomp(java.util.Map table) Perform a chomp on the values of the Map object passed in.
static int	chomp(java.lang.StringBuffer buffer) Perform a chomp on the StringBuffer passed in as a parameter.
static int	chomp(java.lang.StringBuffer[] buffers) Do a chomp on an array of StringBuffer objects.
static java.lang.String	getRecordSeparator() Retrieve the current value of the record-separator (line-end sequence).
static com.blackperl.Perl.Chomp	instance() The instance method is used to retrieve the Chomp singleton that applications can use in lieu of invoking the methods statically.
static void	setRecordSeparator(java.lang.String newRS) Assign a new record-separator to be used by the chomp variants.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

chomp

public static int chomp(java.util.Map table)
                 throws java.lang.ClassCastException

Perform a chomp on the values of the Map object passed in. Returns the total number of characters removed.

Parameters:

table - An object implementing the Map interface

Returns:

The character from the last chop().

Throws:

java.lang.ClassCastException

chomp

public static int chomp(java.lang.StringBuffer buffer)

Perform a chomp on the StringBuffer passed in as a parameter.

Parameters:

buffer - StringBuffer with the string data to trim

Returns:

The number of characters removed

chomp

public static int chomp(java.lang.StringBuffer[] buffers)

Do a chomp on an array of StringBuffer objects. Returns the total number of characters removed from all buffers.

Parameters:

buffers - An array of StringBuffer objects to operate upon

Returns:

The total number of characters removed from all buffers

getRecordSeparator

public static java.lang.String getRecordSeparator()

Retrieve the current value of the record-separator (line-end sequence).

Returns:

The current record-separator (line-terminator)

instance

public static com.blackperl.Perl.Chomp instance()

The instance method is used to retrieve the Chomp singleton that applications can use in lieu of invoking the methods statically.

Returns:

Singleton instance of the Chomp class

setRecordSeparator

public static void setRecordSeparator(java.lang.String newRS)

Assign a new record-separator to be used by the chomp variants.

Parameters:

newRS - A string to be used as the record-separator (line-end)