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 js;
021 
022 import js.core.JsRegExp;
023 
024 /**
025  * <p>An <b>opaque</b> interface resembling JavaScript regular expressions for performing 
026  * pattern matching on string instances.</p>
027  * <p>This interface must be implemented in JS Simulation Libraries.</p>
028  *
029  * @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>
030  * @see Js#re(String)
031  * @see Js#re(String, String)
032  * @see js.core.JsGlobal.RegExp#create(Object, Object)
033  * 
034  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be 
035  * generated into the target codes. Re-compilers must exit with error on the operations of 
036  * accessing that kind of class objects.
037  * The <tt>checkcast</tt> operation to the class literal of this interface must be ignored 
038  * and <tt>instanceof</tt> to it always <tt>true</tt>.
039  */
040 
041 public interface RegExpLike
042 {
043     /**
044      * <p>Gets the <tt>global</tt> field of the current regular expression instance.</p>
045      * <p>The <tt>global</tt> field is a read-only boolean property of regular expression
046      * instances. It specifies whether a particular regular expression performs global matching, 
047      * that is, whether it was created with the "g" attribute.</p>
048      * @return The value of the <tt>global</tt> field of the regular expression.
049      * @see Js#re(String, String)
050      * @since 1.0
051      * @javascript Re-compilers must convert the interface invocation of this method into the 
052      * JavaScript expression: 
053      * <pre>re.global</pre>
054      * where <tt>re</tt> is the current regular expression instance of the invocation.
055      */
056     public boolean global();
057     /**
058      * <p>Gets the <tt>ignoreCase</tt> field of the current regular expression instance.</p>
059      * <p>The <tt>ignoreCase</tt> field is a read-only boolean property of regular expression 
060      * instances. It specifies whether a particular regular expression performs case-insensitive 
061      * matching, that is, whether it was created with the "i" attribute.</p>
062      * @return The value of the <tt>ignoreCase</tt> field of the regular expression.
063      * @see Js#re(String, String)
064      * @since 1.0
065      * @javascript Re-compilers must convert the interface invocation of this method into the 
066      * JavaScript expression: 
067      * <pre>re.ignoreCase</pre>
068      * where <tt>re</tt> is the current regular expression instance of the invocation.
069      */
070     public boolean ignoreCase();
071     /**
072      * <p>Gets the <tt>multiline</tt> field of the current regular expression instance.</p>
073      * <p>The <tt>multiline</tt> field is a read-only boolean property of regular expression 
074      * instances. It specifies whether a particular regular expression performs multiline 
075      * matching, that is, whether it was created with the "m" attribute.</p>
076      * @return The value of the <tt>multiline</tt> field of the regular expression.
077      * @see Js#re(String, String)
078      * @since 1.0
079      * @javascript Re-compilers must convert the interface invocation of this method into the 
080      * JavaScript expression: 
081      * <pre>re.multiline</pre>
082      * where <tt>re</tt> is the current regular expression instance of the invocation.
083      */
084     public boolean multiline();
085     /**
086      * <p>Gets the <tt>lastIndex</tt> field of the current regular expression instance.</p>
087      * <p>The <tt>lastIndex</tt> field is a read/write property of regular expression 
088      * instances. For regular expressions with the "g" attribute set, it contains an 
089      * integer that specifies the character position immediately following the last match 
090      * found by the {@link #exec(Object)} and {@link #test(Object)} methods. These methods 
091      * use this property as the starting point for the next search they conduct. This 
092      * allows you to call those methods repeatedly, to loop through all matches in a 
093      * string. Note that <tt>lastIndex</tt> is not used by regular expressions that do 
094      * not have the "g" attribute set and do not represent global patterns.</p>
095      * <p>This property is read/write, so you can set it at any time to specify where in the 
096      * target string the next search should begin. {@link #exec(Object)} and {@link #test(Object)} 
097      * automatically reset <tt>lastIndex</tt> to 0 when they fail to find a match 
098      * (or another match). If you begin to search a new string after a successful match 
099      * of some other string, you have to explicitly set this property to 0.</p>
100      * @return The value of the <tt>lastIndex</tt> field of the regular expression.
101      * @see #lastIndex(Integer)
102      * @see #exec(Object)
103      * @see #test(Object)
104      * @since 1.0
105      * @javascript Re-compilers must convert the interface invocation of this method into the 
106      * JavaScript expression: 
107      * <pre>re.lastIndex</pre>
108      * where <tt>re</tt> is the current regular expression instance of the invocation.
109      */
110     public Integer lastIndex();
111     /**
112      * <p>Sets the <tt>lastIndex</tt> field of the current regular expression instance.</p>
113      * <p>The <tt>lastIndex</tt> field is a read/write property of regular expression 
114      * instances. For regular expressions with the "g" attribute set, it contains an 
115      * integer that specifies the character position immediately following the last match 
116      * found by the {@link #exec(Object)} and {@link #test(Object)} methods. These methods 
117      * use this property as the starting point for the next search they conduct. This 
118      * allows you to call those methods repeatedly, to loop through all matches in a 
119      * string. Note that <tt>lastIndex</tt> is not used by regular expressions that do 
120      * not have the "g" attribute set and do not represent global patterns.</p>
121      * <p>This property is read/write, so you can set it at any time to specify where in the 
122      * target string the next search should begin. {@link #exec(Object)} and {@link #test(Object)} 
123      * automatically reset <tt>lastIndex</tt> to 0 when they fail to find a match 
124      * (or another match). If you begin to search a new string after a successful match 
125      * of some other string, you have to explicitly set this property to 0.</p>
126      * @param lastIndex The new <tt>lastIndex</tt> to set.
127      * @return The new value of the <tt>lastIndex</tt>.
128      * @see #lastIndex()
129      * @see #exec(Object)
130      * @see #test(Object)
131      * @since 1.0
132      * @javascript Re-compilers must convert the interface invocation of this method into the 
133      * JavaScript expression: 
134      * <pre>(re.lastIndex=lastIndex)</pre>
135      * where <tt>re</tt> is the current regular expression instance of the invocation.
136      */
137     public Integer lastIndex(Integer lastIndex);
138     /**
139      * <p>Gets the <tt>source</tt> field of the current regular expression instance.</p>
140      * <p>The <tt>source</tt> field is a read-only string property of regular expression 
141      * instances. It contains the text of the regular expression. This text does not include 
142      * the delimiting slashes used in regular-expression literals, and it does not include 
143      * the "g", "i", and "m" attributes.</p>
144      * @return The source text of the regular expression.
145      * @since 1.0
146      * @javascript Re-compilers must convert the interface invocation of this method into the 
147      * JavaScript expression: 
148      * <pre>re.source</pre>
149      * where <tt>re</tt> is the current regular expression instance of the invocation.
150      */
151     public String source();
152     /**
153      * <p>Performs powerful, general-purpose pattern matching with the current regular expression instance.</p>
154      * <p>This method is the most powerful of all the regular expression and string 
155      * pattern-matching methods. It is a general-purpose method that is somewhat more 
156      * complex to use than {@link #test(Object)}, {@link StringLike#search(RegExpLike)}, 
157      * {@link StringLike#replace(RegExpLike, String)}, and {@link StringLike#match(RegExpLike)}.</p>
158      * <p>This invocation searches string for text that matches the current regular expression. 
159      * If it finds a match, it returns an array of results; otherwise, it returns 
160      * <tt>null</tt>. Element 0 of the returned array is the matched text. Element 1 is 
161      * the text that matched the first parenthesized subexpression, if any, within the current 
162      * regular expression. Element 2 contains the text that matched the second subexpression, 
163      * and so on. The array length property specifies the number of elements in the array, 
164      * as usual. In addition to the array elements and the length property, the value 
165      * returned by the invocation also has two other properties. The <tt>index</tt> 
166      * property (see {@link ArrayLike#index()}) specifies the character position of the first 
167      * character of the matched text. The <tt>input</tt> property (see {@link ArrayLike#input()}) 
168      * refers to <tt>s</tt>. This returned array is the same as the array that is 
169      * returned by the {@link StringLike#match(RegExpLike)} method, when invoked on a 
170      * non-global regular expression instance.</p>
171      * <p>When this method is invoked on a non-global pattern, it performs the search and 
172      * returns the result described earlier. When the current instance is a global regular 
173      * expression, however, the invocation behaves in a slightly more complex way. It begins 
174      * searching string at the character position specified by the <tt>lastIndex</tt> 
175      * property (see {@link #lastIndex()} and {@link #lastIndex(Integer)}) of the current 
176      * regular expression. When it finds a match, it sets <tt>lastIndex</tt> to the 
177      * position of the first character after the match. This means that you can invoke 
178      * this method repeatedly in order to loop through all matches in a string. When 
179      * the invocation cannot find any more matches, it returns <tt>null</tt> and 
180      * resets <tt>lastIndex</tt> to zero. If you begin searching a new string 
181      * immediately after successfully finding a match in another string, you must be 
182      * careful to manually reset <tt>lastIndex</tt> to zero.</p>
183      * <p>Note that this invocation always includes full details of every match in the 
184      * array it returns, whether or not the current regular expression is a global pattern. 
185      * This is where this method differs from {@link StringLike#match(RegExpLike)}, which 
186      * returns much less information when used with global patterns. Calling this method 
187      * repeatedly in a loop is the only way to obtain complete pattern-matching 
188      * information for a global pattern.</p>
189      * @param s The string to be tested.
190      * @return An array containing the results of the match or undefined 
191      * <tt>null</tt> if no match was found.
192      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
193      * is invoked with an instance that is not a regular expression. See {@link Js#err(Object)} 
194      * and {@link js.core.JsTypeError} for JS Simulation.
195      * @see #lastIndex()
196      * @see #lastIndex(Integer)
197      * @see #test(Object)
198      * @see StringLike#match(RegExpLike)
199      * @see StringLike#replace(RegExpLike, String)
200      * @see StringLike#replace(RegExpLike, StringLike)
201      * @see StringLike#replace(RegExpLike, js.core.JsFunction)
202      * @see StringLike#search(RegExpLike)
203      * @since 1.0
204      * @javascript Re-compilers must convert the interface invocation of this method directly 
205      * into a JavaScript invocation on its current regular expression instance without changing the 
206      * method name, but expanding variable arguments, if any, into comma-separated values. 
207      */
208     public ArrayLike<?> exec(Object s);
209     /**
210      * <p>Tests whether a string contains the pattern represented by the current regular 
211      * expression.</p>
212      * <p></p>
213      * @param s The string to be tested.
214      * @return <tt>true</tt> if <tt>s</tt> contains text that matches the current 
215      * regular expression; false otherwise.
216      * @throws RuntimeException JavaScript throws a <tt>TypeError</tt> if this method 
217      * is invoked with an instance that is not a regular expression. See {@link Js#err(Object)} 
218      * and {@link js.core.JsTypeError} for JS Simulation.
219      * @see #exec(Object)
220      * @see #lastIndex()
221      * @see #lastIndex(Integer)
222      * @see StringLike#match(RegExpLike)
223      * @see StringLike#replace(RegExpLike, String)
224      * @see StringLike#replace(RegExpLike, StringLike)
225      * @see StringLike#replace(RegExpLike, js.core.JsFunction)
226      * @see StringLike#search(RegExpLike)
227      * @see StringLike#substring(Object)
228      * @see StringLike#substring(Object, Object)
229      * @since 1.0
230      * @javascript Re-compilers must convert the interface invocation of this method directly 
231      * into a JavaScript invocation on its current regular expression instance without changing the 
232      * method name, but expanding variable arguments, if any, into comma-separated values. 
233      */
234     public boolean test(Object s);
235     /**
236      * <p>Returns the primitive value associated with the current instance, if there is one. 
237      * This invocation simply returns the instance itself for the current instance is an 
238      * object and there is no primitive value for it.</p>
239      * @return The current regular expression itself.
240      * @since 1.0
241      * @javascript Re-compilers must convert the interface invocation of this method directly 
242      * into a JavaScript invocation on its current regular expression instance without changing the 
243      * method name, but expanding variable arguments, if any, into comma-separated values. 
244      */
245     public RegExpLike valueOf();
246     /**
247      * <p>Simply returns an regular expression object of the current instance.</p>
248      * <p>This method is useful for JS Simulation to implement opaque types.</p>
249      * @return An RegExp object of the current regular expression instance.
250      * @since 1.0
251      * @javascript Re-compilers must ignore the interface invocation of this method, that is, 
252      * replacing it with its current instance.
253      */
254     public JsRegExp var();
255 }