com.blackperl.Perl
Class Grep

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

public class Grep

extends java.lang.Object

Static-method implementation of the Perl grep keyword. The grep function traverses a List (or array) of objects. Each of the objects are evaluated using the eval method of the block passed in (see GrepBlock). When the method returns a Boolean object as a result, and the result's value is "true", the tested object is added to the list of values to be returned by grep. If eval returns an object other than Boolean, and the value is not null, the value returned by eval is what is put into the list of return values.

Because many of the common uses of grep in Perl involve testing against string values or regular expressions, there are also some convenience forms of the function provided here, to make coding a little easier. See the method documentation for details.

The "default" forms of grep take List objects as the parameter to provide the set of values to test. Any of the classes that implement the List interface may be used. Alternate forms of the function are also provided that take and return ordinary arrays of Object.

Here are some simple examples of grep:

     import java.util.*;
     import com.blackperl.Perl.Grep;
 
     Vector v = new Vector();
     for (int i = 0; i < 100; i++)
         v.add(new Integer(i));
     List even_numbers = Grep.grep(new GrepBlock() {
             public Object eval(Object I) {
                 return Boolean.valueOf((((Integer)I).intValue() & 1) == 0);
             } }, v);
     // even_numbers now has all even numbers in the range 0 to 99
 

Using arrays instead of the List interface:

     import java.util.regex.*;
     import com.blackperl.Perl.Grep;
 
     String[] languages = { "Java (vm)", "Perl (scripting)", "C (compiled)",
         "Python (scripting)", "Ruby (scripting)", "C# (vm)",
         "Fortran (compiled)" };
 
     // Returns Java and C#
     Object[] vm_languages = Grep.grep("(vm)", languages);
 
     // Returns Perl and Python
     Object[] p_languages = Grep.grep(Pattern.compile("^P"), languages);
 

Note that while the array interfaces may be easier to use in many cases that the List interfaces, the return value is always of the Object[] form-- trying to cast the return value in the above examples so as to assign directly to an array of String would raise a ClassCastException. The choice of List over array is largely a matter of choosing when and where you want to cast your result objects. Eventually, the JDK 1.5 version of this class will utilize generics to reduce the complexity of this.

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:

     import com.blackperl.Perl.Grep.grep;
 
     // Assume the same "languages" string array as previous examples
 
     // Returns Perl, Python and Ruby.
     String[] scripting_languages = grep("(scripting)", languages);
 

Method Summary

static java.util.List	grep(com.blackperl.Perl.GrepBlock block, java.util.List list) Do a grep over the list of objects, evaluating each one via the given GrepBlock (see GrepBlock).
static java.lang.Object[]	grep(com.blackperl.Perl.GrepBlock block, java.lang.Object[] objArray) This is identical to the block-list form of grep, except that it takes and returns an array of Object, rather than a List instance.
static java.util.List	grep(java.util.regex.Pattern pattern, java.util.List list) This is a shorthand-form for grep, that takes a java.util.regex.Pattern object and used an internal class that implements GrepBlock to provide an evaluation function that returns a Boolean value indicating whether the stringification of the given test object matched the pattern.
static java.lang.Object[]	grep(java.util.regex.Pattern pattern, java.lang.Object[] objArray) The pattern-list form of grep, only taking and returning arrays of Object, rather than List instances.
static java.util.List	grep(java.lang.String string, java.util.List list) This is another shorthand-form for grep, this one taking a String object and constructing a GrepBlock that tests the string to see if it is a contained substring within the stringification of each test object.
static java.lang.Object[]	grep(java.lang.String string, java.lang.Object[] objArray) The string-list form of grep, with arrays instead of the List instances.
static com.blackperl.Perl.Grep	instance() The instance method is used to retrieve the Grep singleton that applications can use in lieu of invoking the methods statically.

Methods inherited from class java.lang.Object

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

Method Detail

grep

public static java.util.List grep(com.blackperl.Perl.GrepBlock block,
                                  java.util.List list)

Do a grep over the list of objects, evaluating each one via the given GrepBlock (see GrepBlock). When the eval method is executed, the result is interpreted in one of two ways: If the return value is a Boolean object, and that object has a value of "true", the original object (from list is inserted into the return-list. If the return value is an object other than Boolean (or derived from), it is added to the return-list. If the return value is either null or a Boolean with value "false", then no value is added to the return.

Parameters:

block - An object of a class implementing the GrepBlock interface\

list - A List object with all the values to test via the block

Returns:

A List object of all the matched values

grep

public static java.lang.Object[] grep(com.blackperl.Perl.GrepBlock block,
                                      java.lang.Object[] objArray)

This is identical to the block-list form of grep, except that it takes and returns an array of Object, rather than a List instance.

Parameters:

block - The GrepBlock to evaluate objects against

objArray - An array of Objects to be evaluated

Returns:

An array of those values matched by the block evaluation

grep

public static java.util.List grep(java.util.regex.Pattern pattern,
                                  java.util.List list)

This is a shorthand-form for grep, that takes a java.util.regex.Pattern object and used an internal class that implements GrepBlock to provide an evaluation function that returns a Boolean value indicating whether the stringification of the given test object matched the pattern. Those that match are collected and returned in a List object as the return value. This assumes that for all the objects in list the toString() method is callable.

Parameters:

pattern - The regular expression to test objects against

list - A List object containing the objects to test against it

Returns:

A List object containing all the objects that matched the pattern

grep

public static java.lang.Object[] grep(java.util.regex.Pattern pattern,
                                      java.lang.Object[] objArray)

The pattern-list form of grep, only taking and returning arrays of Object, rather than List instances.

Parameters:

pattern - The Pattern to compare each object against

objArray - The array of Objects to test

Returns:

An array of those Objects that matched

grep

public static java.util.List grep(java.lang.String string,
                                  java.util.List list)

This is another shorthand-form for grep, this one taking a String object and constructing a GrepBlock that tests the string to see if it is a contained substring within the stringification of each test object. Those that contain string as a substring are added to the output list. This assumes that all the objects in list can call a toString method.

Parameters:

string - The String to test as a substring in the objects

list - A List object containing the objects to test against

Returns:

A List object containing all the matching objects

grep

public static java.lang.Object[] grep(java.lang.String string,
                                      java.lang.Object[] objArray)

The string-list form of grep, with arrays instead of the List instances.

Parameters:

string - The String to compare each object with

objArray - The array of Objects to test

Returns:

An array of those Objects that matched

instance

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

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

Returns:

Singleton instance of the Chomp class