001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package jsx.core;
021 
022 import js.*;
023 
024 /**
025  * <p>A utility class providing the static methods operating on regular expressions.</p>
026  * <p>Users are encouraged to use the utilities provided by this class instead of the 
027  * <b>opaque</b> methods of {@link js.RegExpLike} or {@link js.core.JsRegExp} in 
028  * consideration of the reuse benefit for re-compilation results.</p>
029  * 
030  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
031  */
032 public final class RegExpLikes extends Disposable
033 {
034     private RegExpLikes() {}
035 
036     /**
037      * <p>Gets the <tt>global</tt> field of the current regular expression instance.</p>
038      * <p>The <tt>global</tt> field is a read-only boolean property of regular expression
039      * instances. It specifies whether a particular regular expression performs global matching, 
040      * that is, whether it was created with the "g" attribute.</p>
041      * @param r The current regular expression.
042      * @return The value of the <tt>global</tt> field of the regular expression.
043      * @see Js#re(String, String)
044      * @since 1.0
045      */
046     public static final boolean global(RegExpLike r) {
047         return r.global();
048     }
049     /**
050      * <p>Gets the <tt>ignoreCase</tt> field of the current regular expression instance.</p>
051      * <p>The <tt>ignoreCase</tt> field is a read-only boolean property of regular expression 
052      * instances. It specifies whether a particular regular expression performs case-insensitive 
053      * matching, that is, whether it was created with the "i" attribute.</p>
054      * @param r The current regular expression.
055      * @return The value of the <tt>ignoreCase</tt> field of the regular expression.
056      * @see Js#re(String, String)
057      * @since 1.0
058      */
059     public static final boolean ignoreCase(RegExpLike r) {
060         return r.ignoreCase();
061     }
062     /**
063      * <p>Gets the <tt>multiline</tt> field of the current regular expression instance.</p>
064      * <p>The <tt>multiline</tt> field is a read-only boolean property of regular expression 
065      * instances. It specifies whether a particular regular expression performs multiline 
066      * matching, that is, whether it was created with the "m" attribute.</p>
067      * @param r The current regular expression.
068      * @return The value of the <tt>multiline</tt> field of the regular expression.
069      * @see Js#re(String, String)
070      * @since 1.0
071      */
072     public static final boolean multiline(RegExpLike r) {
073         return r.multiline();
074     }
075     /**
076      * <p>Gets the <tt>lastIndex</tt> field of the current regular expression instance.</p>
077      * <p>The <tt>lastIndex</tt> field is a read/write property of regular expression 
078      * instances. For regular expressions with the "g" attribute set, it contains an 
079      * integer that specifies the character position immediately following the last match 
080      * found by the {@link #exec(js.RegExpLike, Object)} and {@link #test(js.RegExpLike, Object)} methods. These methods 
081      * use this property as the starting point for the next search they conduct. This 
082      * allows you to call those methods repeatedly, to loop through all matches in a 
083      * string. Note that <tt>lastIndex</tt> is not used by regular expressions that do 
084      * not have the "g" attribute set and do not represent global patterns.</p>
085      * <p>This property is read/write, so you can set it at any time to specify where in the 
086      * target string the next search should begin. {@link #exec(js.RegExpLike, Object)} and {@link #test(js.RegExpLike, Object)} 
087      * automatically reset <tt>lastIndex</tt> to 0 when they fail to find a match 
088      * (or another match). If you begin to search a new string after a successful match 
089      * of some other string, you have to explicitly set this property to 0.</p>
090      * @param r The current regular expression.
091      * @return The value of the <tt>lastIndex</tt> field of the regular expression.
092      * @see #lastIndex(js.RegExpLike, Integer)
093      * @see #exec(js.RegExpLike, Object)
094      * @see #test(js.RegExpLike, Object)
095      * @since 1.0
096      */
097     public static final Integer lastIndex(RegExpLike r) {
098         return r.lastIndex();
099     }
100     /**
101      * <p>Sets the <tt>lastIndex</tt> field of the current regular expression instance.</p>
102      * <p>The <tt>lastIndex</tt> field is a read/write property of regular expression 
103      * instances. For regular expressions with the "g" attribute set, it contains an 
104      * integer that specifies the character position immediately following the last match 
105      * found by the {@link #exec(js.RegExpLike, Object)} and {@link #test(js.RegExpLike, Object)} methods. These methods 
106      * use this property as the starting point for the next search they conduct. This 
107      * allows you to call those methods repeatedly, to loop through all matches in a 
108      * string. Note that <tt>lastIndex</tt> is not used by regular expressions that do 
109      * not have the "g" attribute set and do not represent global patterns.</p>
110      * <p>This property is read/write, so you can set it at any time to specify where in the 
111      * target string the next search should begin. {@link #exec(js.RegExpLike, Object)} and {@link #test(js.RegExpLike, Object)} 
112      * automatically reset <tt>lastIndex</tt> to 0 when they fail to find a match 
113      * (or another match). If you begin to search a new string after a successful match 
114      * of some other string, you have to explicitly set this property to 0.</p>
115      * @param r The current regular expression.
116      * @param lastIndex The new <tt>lastIndex</tt> to set.
117      * @return The new value of the <tt>lastIndex</tt>.
118      * @see #lastIndex(js.RegExpLike)
119      * @see #exec(js.RegExpLike, Object)
120      * @see #test(js.RegExpLike, Object)
121      * @since 1.0
122      */
123     public static final Integer lastIndex(RegExpLike r, Integer lastIndex) {
124         return r.lastIndex(lastIndex);
125     }
126     /**
127      * <p>Gets the <tt>source</tt> field of the current regular expression instance.</p>
128      * <p>The <tt>source</tt> field is a read-only string property of regular expression 
129      * instances. It contains the text of the regular expression. This text does not include 
130      * the delimiting slashes used in regular-expression literals, and it does not include 
131      * the "g", "i", and "m" attributes.</p>
132      * @param r The current regular expression.
133      * @return The source text of the regular expression.
134      * @since 1.0
135      */
136     public static final String source(RegExpLike r) {
137         return r.source();
138     }
139     /**
140      * <p>Performs powerful, general-purpose pattern matching with the current regular expression instance.</p>
141      * <p>This method is the most powerful of all the regular expression and string 
142      * pattern-matching methods. It is a general-purpose method that is somewhat more 
143      * complex to use than {@link #test(js.RegExpLike, Object)}, {@link StringLikes#search(js.StringLike, RegExpLike)}, 
144      * {@link StringLikes#replace(js.StringLike, RegExpLike, String)}, and {@link StringLikes#match(js.StringLike, RegExpLike)}.</p>
145      * <p>This invocation searches string for text that matches the current regular expression. 
146      * If it finds a match, it returns an array of results; otherwise, it returns 
147      * <tt>null</tt>. Element 0 of the returned array is the matched text. Element 1 is 
148      * the text that matched the first parenthesized subexpression, if any, within the current 
149      * regular expression. Element 2 contains the text that matched the second subexpression, 
150      * and so on. The array length property specifies the number of elements in the array, 
151      * as usual. In addition to the array elements and the length property, the value 
152      * returned by the invocation also has two other properties. The <tt>index</tt> 
153      * property (see {@link ArrayLikes#index(js.ArrayLike)}) specifies the character position of the first 
154      * character of the matched text. The <tt>input</tt> property (see {@link ArrayLikes#input(js.ArrayLike)}) 
155      * refers to <tt>s</tt>. This returned array is the same as the array that is 
156      * returned by the {@link StringLikes#match(js.StringLike, RegExpLike)} method, when invoked on a 
157      * non-global regular expression instance.</p>
158      * <p>When this method is invoked on a non-global pattern, it performs the search and 
159      * returns the result described earlier. When the current instance is a global regular 
160      * expression, however, the invocation behaves in a slightly more complex way. It begins 
161      * searching string at the character position specified by the <tt>lastIndex</tt> 
162      * property (see {@link #lastIndex(js.RegExpLike)} and {@link #lastIndex(js.RegExpLike, Integer)}) of the current 
163      * regular expression. When it finds a match, it sets <tt>lastIndex</tt> to the 
164      * position of the first character after the match. This means that you can invoke 
165      * this method repeatedly in order to loop through all matches in a string. When 
166      * the invocation cannot find any more matches, it returns <tt>null</tt> and 
167      * resets <tt>lastIndex</tt> to zero. If you begin searching a new string 
168      * immediately after successfully finding a match in another string, you must be 
169      * careful to manually reset <tt>lastIndex</tt> to zero.</p>
170      * <p>Note that this invocation always includes full details of every match in the 
171      * array it returns, whether or not the current regular expression is a global pattern. 
172      * This is where this method differs from {@link StringLikes#match(js.StringLike, RegExpLike)}, which 
173      * returns much less information when used with global patterns. Calling this method 
174      * repeatedly in a loop is the only way to obtain complete pattern-matching 
175      * information for a global pattern.</p>
176      * @param r The current regular expression.
177      * @param s The string to be tested.
178      * @return An array containing the results of the match or undefined 
179      * <tt>null</tt> if no match was found.
180      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
181      * is invoked with an instance that is not a regular expression. See {@link Js#err(Object)} 
182      * and {@link js.core.JsTypeError} for JS Simulation.
183      * @see #lastIndex(js.RegExpLike)
184      * @see #lastIndex(js.RegExpLike, Integer)
185      * @see #test(js.RegExpLike, Object)
186      * @see StringLikes#match(js.StringLike, RegExpLike)
187      * @see StringLikes#replace(js.StringLike, RegExpLike, String)
188      * @see StringLikes#replace(js.StringLike, RegExpLike, StringLike)
189      * @see StringLikes#replace(js.StringLike, RegExpLike, js.core.JsFunction)
190      * @see StringLikes#search(js.StringLike, RegExpLike)
191      * @since 1.0
192      */
193     public static final ArrayLike<?> exec(RegExpLike r, Object s) {
194         return r.exec(s);
195     }
196     /**
197      * <p>Tests whether a string contains the pattern represented by the current regular 
198      * expression.</p>
199      * <p></p>
200      * @param r The current regular expression.
201      * @param s The string to be tested.
202      * @return <tt>true</tt> if <tt>s</tt> contains text that matches the current 
203      * regular expression; false otherwise.
204      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
205      * is invoked with an instance that is not a regular expression. See {@link Js#err(Object)} 
206      * and {@link js.core.JsTypeError} for JS Simulation.
207      * @see #exec(js.RegExpLike, Object)
208      * @see #lastIndex(js.RegExpLike)
209      * @see #lastIndex(js.RegExpLike, Integer)
210      * @see StringLikes#match(js.StringLike, RegExpLike)
211      * @see StringLikes#replace(js.StringLike, RegExpLike, String)
212      * @see StringLikes#replace(js.StringLike, RegExpLike, StringLike)
213      * @see StringLikes#replace(js.StringLike, RegExpLike, js.core.JsFunction)
214      * @see StringLikes#search(js.StringLike, RegExpLike)
215      * @see StringLikes#substring(js.StringLike, Object)
216      * @see StringLikes#substring(js.StringLike, Object, Object)
217      * @since 1.0
218      */
219     public static final boolean test(RegExpLike r, Object s) {
220         return r.test(s);
221     }
222 }