View Javadoc
   /*
    * Strings.java
    * Created on August 18, 2003
    *
    * The Blues Framework - A lightweight application framework
    * Copyright (C) 2003  Lonnie Pryor
    * http://blues.lonniepryor.com
    *
    * This library is free software; you can redistribute it and/or modify it under the
   * terms of the GNU Lesser General Public License as published by the Free Software
   * Foundation; either version 2.1 of the License, or (at your option) any later
   * version.
   *
   * This library is distributed in the hope that it will be useful, but WITHOUT ANY
   * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
   * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public License along
   * with this library; if not, write to:
   *
   *   The Free Software Foundation, Inc.
   *   59 Temple Place, Suite 330
   *   Boston, MA 02111-1307 USA
   *
   */
  package com.lonniepryor.blues.util;
  
  import java.util.ArrayList;
  import java.util.List;
  
  /***
   * Specification interface for identifying Strings or parts of Strings. Instances
   * of this class may be logically combined using the AND, OR, and NOT operations.
   * Instances may also be sequentially constructed using the Builder class. Many
   * common use-cases are supplied via static accessor methods.
   *
   * @author Lonnie Pryor
   * @version $Revision: 1.1 $
   */
  public abstract class Strings {
    /*** A specification satisfied by any non-null string. */
    private static final Strings any = new Strings() {
        protected boolean evaluate (String canidate, int begin, int end) {
          return true;
        }
      };
    /*** A specification satisfied by any non-empty string. */
    private static final Strings notEmpty = Strings.withAtLeastNumChars(1);
  
    /***
     * Creates a new Strings object.
     */
    protected Strings () {
    }
  
    /***
     * Returns a specification satisfied by any non-null string.
     *
     * @return A specification satisfied by any non-null string.
     */
    public static Strings any () {
      return any;
    }
  
    /***
     * Returns a specification satisfied by any non-empty string.
     *
     * @return A specification satisfied by any non-empty string.
     */
    public static Strings notEmpty () {
      return notEmpty;
    }
  
    /***
     * Returns a specification satisfied by strings of at least the specified length.
     *
     * @param minChars The minimum length of valid strings.
     *
     * @return A specification satisfied by strings of al least the specified length
     */
    public static Strings withAtLeastNumChars (final int minChars) {
      if (minChars < 0)
        throw new IllegalArgumentException("minChars < 0");
      return new Strings() {
          protected boolean evaluate (String canidate, int begin, int end) {
            return ((end - begin) >= minChars);
          }
        };
    }
  
    /***
     * Returns a specification satisfied by strings with a single character that
     * satisfies the specified specification.
     *
     * @param specification The specification to match to.
     *
     * @return A specification satisfied by strings with a single character that
     *         satisfies the specified specification.
     */
   public static Strings matching (final Characters specification) {
     if (specification == null)
       throw new NullPointerException("specification");
     return new Strings() {
         protected boolean evaluate (String canidate, int begin, int end) {
           return ((end - begin) == 1)
           && specification.isSatisfiedBy(canidate.charAt(begin));
         }
       };
   }
 
   /***
    * Returns a specification satisfied by strings equal to the specified string.
    *
    * @param characters The string to match to.
    *
    * @return A specification satisfied by strings equal to the specified string.
    */
   public static Strings matching (final String characters) {
     if (characters == null)
       throw new NullPointerException("characters");
     return new Strings() {
         protected boolean evaluate (String canidate, int begin, int end) {
           return ((end - begin) == characters.length())
           && canidate.regionMatches(begin, characters, 0, characters.length());
         }
       };
   }
 
   /***
    * Returns a Builder whose resulting Strings specification will allow any number
    * of inital characters.
    *
    * @return A Builder whose resulting Strings specification will allow any number
    *         of inital characters.
    */
   public static Builder startingWithAny () {
     return startingWithAtLeastNumChars(0);
   }
 
   /***
    * Returns a Builder whose resulting Strings specification will require at least
    * the supplied number of inital characters.
    *
    * @param minChars The minimum number of charactes to require.
    *
    * @return A Builder whose resulting Strings specification will require at least
    *         the supplied number of inital characters.
    */
   public static Builder startingWithAtLeastNumChars (final int minChars) {
     if (minChars < 0)
       throw new IllegalArgumentException("minChars < 0");
     return new Builder() {
         Strings create (Strings next) {
           return newWildcard(minChars, next);
         }
       };
   }
 
   /***
    * Returns a Builder whose resulting Strings specification will require the
    * supplied character at the beginning of canidate strings.
    *
    * @param specification The specification to match to.
    *
    * @return A Builder whose resulting Strings specification will require the
    *         supplied character at the beginning of canidate strings.
    */
   public static Builder startingWith (final Characters specification) {
     if (specification == null)
       throw new NullPointerException("specification");
     return new Builder() {
         Strings create (Strings next) {
           return newCharacters(specification, next);
         }
       };
   }
 
   /***
    * Returns a Builder whose resulting Strings specification will require the
    * supplied text at the beginning of canidate strings.
    *
    * @param characters The text required at the beginning of canidates.
    *
    * @return A Builder whose resulting Strings specification will require the
    *         supplied text at the beginning of canidate strings.
    */
   public static Builder startingWith (final String characters) {
     if (characters == null)
       throw new NullPointerException("characters");
     return new Builder() {
         Strings create (Strings next) {
           return newString(characters, next);
         }
       };
   }
 
   /***
    * Parses a string pattern containing the '' wildcard. Format:
    * <pre>
    *   strings     ::=  wildcard | ( [ wildcard ] pattern )
    *   pattern     ::=  characters [ wildcard [ pattern ] ]
    *   wildcard    ::=  "*"
    *   characters  ::=  Any sequence of characters except "*"
    * </pre>
    * Astriks will match zero or more characters, all other characters are matched
    * exactly.
    *
    * @param stringPattern The content of the pattern.
    *
    * @return A Strings specification from the supplied pattern.
    *
    * @throws ParseException if the pattern is invalid.
    */
   public static Strings parse (String stringPattern) {
     if (stringPattern == null)
       throw new NullPointerException("stringPattern");
     if (stringPattern.equals("*"))
       return any;
     int firstWildcard = stringPattern.indexOf('*');
     if (firstWildcard < 0)
       return matching(stringPattern);
     if (firstWildcard == 0)
       return readCharacters(stringPattern, 1, startingWithAny());
     return readWildcard(
       stringPattern, firstWildcard,
       startingWith(stringPattern.substring(0, firstWildcard)));
   }
 
   /***
    * Reads a wildcard as the next pattern input.
    *
    * @param stringPattern The content of the pattern.
    * @param index The current index.
    * @param builder The Builder to use.
    *
    * @return The finished Strings specification.
    *
    * @throws ParseException if the pattern is invalid.
    */
   private static Strings readWildcard (
     String stringPattern, int index, Builder builder) {
     if (index == (stringPattern.length() - 1))
       return builder.endingWithAny();
     return readCharacters(stringPattern, index + 1, builder.followedByAny());
   }
 
   /***
    * Reads characters as the next pattern input.
    *
    * @param stringPattern The content of the pattern.
    * @param index The current index.
    * @param builder The Builder to use.
    *
    * @return The finished Strings specification.
    *
    * @throws ParseException if the pattern is invalid.
    */
   private static Strings readCharacters (
     String stringPattern, int index, Builder builder) {
     if (stringPattern.charAt(index) == '*')
       throw new ParseException(
         "Invalid string pattern '" + stringPattern
         + "': contains a double wildcard");
     int next = stringPattern.indexOf('*', index);
     if (next < 0)
       return builder.endingWith(stringPattern.substring(index));
     return readWildcard(
       stringPattern, next, builder.followedBy(stringPattern.substring(index, next)));
   }
 
   /***
    * Parses a logical expression as described in the Expression class, using this
    * class's parse() method for creating values.
    *
    * @param stringPatternExpr The content of the pattern expression.
    *
    * @return A Strings specification from the supplied pattern expression.
    *
    * @throws ParseException if the pattern expression is invalid.
    *
    * @see Expression
    * @see Strings#parse(String)
    */
   public static Strings parseExpression (String stringPatternExpr) {
     if (stringPatternExpr == null)
       throw new NullPointerException("stringPatternExpr");
     return (Strings)Expression.parse(
       stringPatternExpr,
       new Expression.Builder() {
         public Object or (Object left, Object right) {
           return ((Strings)left).or((Strings)right);
         }
 
         public Object and (Object left, Object right) {
           return ((Strings)left).and((Strings)right);
         }
 
         public Object not (Object value) {
           return ((Strings)value).not();
         }
 
         public Object create (String stringPattern) {
           return parse(stringPattern);
         }
       });
   }
 
   /***
    * Returns true if the supplied String is not null and satisfies this
    * specification.
    *
    * @param canidate The String to test.
    *
    * @return True if the supplied String is not null and satisfies this
    *         specification.
    */
   public final boolean isSatisfiedBy (String canidate) {
     return (canidate != null) && evaluate(canidate, 0, canidate.length());
   }
 
   /***
    * Returns true if the supplied String is not null and the specified range
    * satisfies this specification.
    *
    * @param canidate The String to test.
    * @param begin The beginning of the range (inclusive).
    * @param end The end of the range(excusive).
    *
    * @return True if the supplied String is not null and the specified range
    *         satisfies this specification.
    */
   public final boolean isSatisfiedBy (String canidate, int begin, int end) {
     return (canidate != null) && (begin >= 0) && (end <= canidate.length())
     && (begin <= end) && evaluate(canidate, begin, end);
   }
 
   /***
    * Returns true if the specified range satisfies this specification.
    *
    * @param canidate The String to test.
    * @param begin The beginning of the range (inclusive).
    * @param end The end of the range(excusive).
    *
    * @return True if the specified range satisfies this specification.
    */
   protected abstract boolean evaluate (String canidate, int begin, int end);
 
   /***
    * Returns true if all of the supplied Strings satisfy this specification.
    *
    * @param all The array of Strings to test.
    *
    * @return True if all of the supplied Strings satisfy this specification.
    */
   public final boolean isSatisfiedByAll (String[] all) {
     if (all == null)
       throw new NullPointerException("all");
     for (int i = 0; i < all.length; ++i)
       if (!isSatisfiedBy(all[i]))
         return false;
     return true;
   }
 
   /***
    * Returns true if any of the supplied Strings satisfy this specification.
    *
    * @param any The array of Strings to test.
    *
    * @return True if any of the supplied Strings satisfy this specification.
    */
   public final boolean isSatisfiedByAny (String[] any) {
     if (any == null)
       throw new NullPointerException("any");
     for (int i = 0; i < any.length; ++i)
       if (isSatisfiedBy(any[i]))
         return true;
     return false;
   }
 
   /***
    * Selects the first Strings that satisfies this specification from the supplied
    * array.
    *
    * @param from The array to select from.
    *
    * @return The first Strings that satisfies this specification from the supplied
    *         array.
    */
   public final String selectFirst (String[] from) {
     if (from == null)
       throw new NullPointerException("from");
     for (int i = 0; i < from.length; ++i)
       if (isSatisfiedBy(from[i]))
         return from[i];
     return null;
   }
 
   /***
    * Selects all the Strings that satisfy this specification from the supplied
    * array.
    *
    * @param from The array to select from.
    *
    * @return All the Strings that satisfy this specification from the supplied
    *         array.
    */
   public final String[] selectAll (String[] from) {
     if (from == null)
       throw new NullPointerException("from");
     List results = new ArrayList(from.length);
     for (int i = 0; i < from.length; ++i)
       if (isSatisfiedBy(from[i]))
         results.add(from[i]);
     return (String[])results.toArray(new String[results.size()]);
   }
 
   /***
    * Returns a specification representing a logical AND of this specification on
    * the left and the supplied specification on the right.
    *
    * @param specification The specification to AND with.
    *
    * @return A specification representing a logical AND of this specification on
    *         the left and the supplied specification on the right.
    */
   public final Strings and (final Strings specification) {
     if (specification == null)
       throw new NullPointerException("specification");
     return new Strings() {
         public boolean evaluate (String canidate, int begin, int end) {
           return Strings.this.evaluate(canidate, begin, end)
           && specification.evaluate(canidate, begin, end);
         }
       };
   }
 
   /***
    * Returns a specification representing a logical OR of this specification on the
    * left and the supplied specification on the right.
    *
    * @param specification The specification to OR with.
    *
    * @return A specification representing a logical OR of this specification on the
    *         left and the supplied specification on the right.
    */
   public final Strings or (final Strings specification) {
     if (specification == null)
       throw new NullPointerException("specification");
     return new Strings() {
         public boolean evaluate (String canidate, int begin, int end) {
           return Strings.this.evaluate(canidate, begin, end)
           || specification.evaluate(canidate, begin, end);
         }
       };
   }
 
   /***
    * Returns a specification representing a logical NOT of this specification.
    *
    * @return A specification representing a logical NOT of this specification.
    */
   public final Strings not () {
     return new Strings() {
         public boolean evaluate (String canidate, int begin, int end) {
           return !Strings.this.evaluate(canidate, begin, end);
         }
       };
   }
 
   /***
    * Helper class for sequentially constructing the elements of a common Strings
    * specification.
    *
    * @author Lonnie Pryor
    * @version $Revision: 1.1 $
    */
   public abstract static class Builder {
     /***
      * Returns a Builder whose resulting Strings specification will accept any
      * number of characters at this point in canidate strings.
      *
      * @return A Builder whose resulting Strings specification will accept any
      *         number of characters at this point in canidate strings.
      */
     public Builder followedByAny () {
       return followedByAtLeastNumChars(0);
     }
 
     /***
      * Returns a Builder whose resulting Strings specification will require the at
      * least the specified number of characters at this point in canidate strings.
      *
      * @param minChars The minimum number of charactes to require.
      *
      * @return A Builder whose resulting Strings specification will require the at
      *         least the specified number of characters at this point in canidate
      *         strings.
      */
     public Builder followedByAtLeastNumChars (final int minChars) {
       if (minChars < 0)
         throw new IllegalArgumentException("minChars < 0");
       return new Builder() {
           public Strings create (Strings next) {
             return Builder.this.create(newWildcard(minChars, next));
           }
         };
     }
 
     /***
      * Returns a Builder whose resulting Strings specification will require the
      * supplied character at this point in canidate strings.
      *
      * @param specification The specification to match to.
      *
      * @return A Builder whose resulting Strings specification will require the
      *         supplied character at this point in canidate strings.
      */
     public Builder followedBy (final Characters specification) {
       if (specification == null)
         throw new NullPointerException("specification");
       return new Builder() {
           Strings create (Strings next) {
             return Builder.this.create(newCharacters(specification, next));
           }
         };
     }
 
     /***
      * Returns a Builder whose resulting Strings specification will require the
      * supplied text at this point in canidate strings.
      *
      * @param characters The text to match.
      *
      * @return A Builder whose resulting Strings specification will require the
      *         supplied text at this point in canidate strings.
      */
     public Builder followedBy (final String characters) {
       if (characters == null)
         throw new NullPointerException("characters");
       return new Builder() {
           public Strings create (Strings next) {
             return Builder.this.create(newString(characters, next));
           }
         };
     }
 
     /***
      * Returns a Strings specification that will accept any number of characters at
      * the end of canidate strings.
      *
      * @return A Strings specification that will accept any number of characters at
      *         the end of canidate strings.
      */
     public Strings endingWithAny () {
       return endingWithAtLeastNumChars(0);
     }
 
     /***
      * Returns a Strings specification that will require the at least the specified
      * number of characters at the end of canidate strings.
      *
      * @param minChars The minimum number of charactes to require.
      *
      * @return A Strings specification that will require the at least the specified
      *         number of characters at the end of canidate strings.
      */
     public Strings endingWithAtLeastNumChars (final int minChars) {
       if (minChars < 0)
         throw new IllegalArgumentException("minChars < 0");
       return Builder.this.create(newWildcard(minChars, null));
     }
 
     /***
      * Returns a Strings specification that will require the supplied character at
      * the end of canidate strings.
      *
      * @param specification The specification to match to.
      *
      * @return A Strings specification that will require the supplied character at
      *         the end of canidate strings.
      */
     public Strings endingWith (final Characters specification) {
       if (specification == null)
         throw new NullPointerException("specification");
       return Builder.this.create(newCharacters(specification, null));
     }
 
     /***
      * Returns a Strings specification that will require the supplied text at the
      * end of canidate strings.
      *
      * @param characters The text to match.
      *
      * @return A Strings specification that will require the supplied text at the
      *         end of canidate strings.
      */
     public Strings endingWith (final String characters) {
       if (characters == null)
         throw new NullPointerException("characters");
       return Builder.this.create(newString(characters, null));
     }
 
     /***
      * Chained method for constructing instances of Strings.
      *
      * @param next The next specification in the chain.
      *
      * @return A chained Strings object for this Builder instance.
      */
     abstract Strings create (Strings next);
 
     /***
      * Creates a new chained Strings object that matched a number of characters.
      *
      * @param minChars The minimum number of charactes to require.
      * @param next The next specification in the chain.
      *
      * @return A new chained Strings object that matched a number of characters.
      */
     static Strings newWildcard (final int minChars, final Strings next) {
       return new Strings() {
           protected boolean evaluate (String canidate, int begin, int end) {
             if (next == null)
               return (end - begin) >= minChars;
             for (int i = begin + minChars; i < end; ++i)
               if (next.evaluate(canidate, i, end))
                 return true;
             return false;
           }
         };
     }
 
     /***
      * Creates a new chained Strings object that matched a single character.
      *
      * @param specification The character specification to match.
      * @param next The next specification in the chain.
      *
      * @return A new chained Strings object that matched a single character.
      */
     static Strings newCharacters (
       final Characters specification, final Strings next) {
       return new Strings() {
           protected boolean evaluate (String canidate, int begin, int end) {
             if (begin >= end)
               return false;
             if (!specification.isSatisfiedBy(canidate.charAt(begin)))
               return false;
             if (next == null)
               return (end - begin) == 1;
             return next.evaluate(canidate, begin + 1, end);
           }
         };
     }
 
     /***
      * Creates a new chained Strings object that matched a specific sequence of
      * characters.
      *
      * @param characters The text to match.
      * @param next The next specification in the chain.
      *
      * @return A new chained Strings object that matched a specific sequence of
      *         characters.
      */
     static Strings newString (final String characters, final Strings next) {
       return new Strings() {
           protected boolean evaluate (String canidate, int begin, int end) {
             if ((begin + characters.length()) > end)
               return false;
             if (!canidate.regionMatches(begin, characters, 0, characters.length()))
               return false;
             if (next == null)
               return (begin + characters.length()) == end;
             return next.evaluate(canidate, begin + characters.length(), end);
           }
         };
     }
   }
 }