/interpreter/tags/at2dist110511/src/edu/vub/at/objects/ATText.java

  1/**
  2 * AmbientTalk/2 Project
  3 * ATText.java created on 26-jul-2006 at 15:18:43
  4 * (c) Programming Technology Lab, 2006 - 2007
  5 * Authors: Tom Van Cutsem & Stijn Mostinckx
  6 * 
  7 * Permission is hereby granted, free of charge, to any person
  8 * obtaining a copy of this software and associated documentation
  9 * files (the "Software"), to deal in the Software without
 10 * restriction, including without limitation the rights to use,
 11 * copy, modify, merge, publish, distribute, sublicense, and/or
 12 * sell copies of the Software, and to permit persons to whom the
 13 * Software is furnished to do so, subject to the following
 14 * conditions:
 15 *
 16 * The above copyright notice and this permission notice shall be
 17 * included in all copies or substantial portions of the Software.
 18 *
 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 21 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 23 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 24 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 25 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 26 * OTHER DEALINGS IN THE SOFTWARE.
 27 */
 28package edu.vub.at.objects;
 29
 30import edu.vub.at.exceptions.InterpreterException;
 31import edu.vub.at.exceptions.XIllegalArgument;
 32import edu.vub.at.objects.grammar.ATExpression;
 33
 34/**
 35 * ATText is the public interface to a native AmbientTalk string (a string of characters).
 36 * Extends the ATExpression interface since a Text can also be output by the parser as a literal.
 37 * 
 38 * @author tvc
 39 */
 40public interface ATText extends ATExpression {
 41
 42	// base-level interface
 43	/**
 44	 * Explodes a text into a table of constituent characters.
 45	 * <p>
 46	 * Usage example:
 47	 * <code>"ambienttalk".explode()</code> returns <code> [a, m, b, i, e, n, t, t, a, l, k]</code>
 48	 * 
 49	 * @return an {@link ATTable} resulting of exploding the receiver text into a table of constituent characters.
 50	 */
 51	public ATTable base_explode() throws InterpreterException;
 52	
 53	/**
 54	 * Splits a text according to the given regular expression.
 55	 * <p>
 56	 * For regular expression syntax, see the Java regular-expression constructs in java.util.regex.Pattern.
 57	 * For regular expression syntax, see the Apache Regexp API of class
 58	 * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">RE</a>.
 59	 * <p>
 60	 * Usage example:
 61	 * <code>"one, two, three".split(", ")</code> returns <code>[ "one", "two", "three" ]</code>
 62	 * 
 63	 * @param regexpr a text representing the regular expression to apply in the split.
 64	 * @return an {@link ATTable} resulting of splitting the receiver text into a table according to the given regular expression.
 65	 * @throws XIllegalArgument if regular expression's syntax is invalid. 
 66	 */
 67	public ATTable base_split(ATText regexpr) throws InterpreterException;
 68	
 69	/**
 70	 * Evaluates a given closure on those elements of this text that match a given regular expression.
 71	 * <p>
 72	 * For regular expression syntax, see the Apache Regexp API of class
 73	 * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">RE</a>.
 74	 * <p>
 75	 * Usage example:
 76	 * <code>"ambienttalk".find: "[aeiou]" do: { |vowel| buff << vowel; nil }</code> returns <code>buff = "aiea"</code>
 77	 * 
 78	 * @param regexp a text representing the regular expression to be found in the text.
 79	 * @param consumer the closure code that is applied each time the regular expression is matched in the text.
 80	 * @return nil
 81	 * @throws XIllegalArgument if regular expression's syntax is invalid. 
 82	 * @throws InterpreterException if raised inside the code closure.
 83	 */
 84	public ATNil base_find_do_(ATText regexp, ATClosure consumer) throws InterpreterException;
 85	
 86	/**
 87	 * Returns a new text replacing those elements of this text that match a given regular expression with the
 88	 * value resulting of the evaluation of a given closure.
 89	 * <p>
 90	 * For regular expression syntax, see the Apache Regexp API of class
 91	 * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">RE</a>.
 92	 * <p>
 93	 * Usage example:
 94	 * <code>"ambienttalk".replace: "[aeiou]" by: { |vowel| vowel.toUpperCase() }</code> returns <code>AmbIEnttAlk</code>
 95	 * 
 96	 * @param regexp a text representing the regular expression to be found in the text.
 97	 * @param transformer the closure code that is applied each time the regular expression matches.
 98	 * @return {@link ATText} replacing those elements of the table that match the regexpr pattern with the value resulting of the evaluation of the transformer closure.
 99	 * @throws XIllegalArgument if regular expression's syntax is invalid. 
100	 * @throws InterpreterException if raised inside the code closure.
101	 */
102	public ATText base_replace_by_(ATText regexp, ATClosure transformer) throws InterpreterException;
103	
104	/**
105	 * Converts all of the characters in this text to upper case.
106	 * 
107	 * @return the {@link ATText} resulting of the conversion.
108	 */
109	public ATText base_toUpperCase() throws InterpreterException;
110	
111	/**
112	 * Converts all of the characters in this text to lower case.
113	 * 
114	 * @return the {@link ATText} resulting of the conversion.
115	 */
116	public ATText base_toLowerCase() throws InterpreterException;
117	
118	/**
119	 * Returns the length of this text.
120	 * 
121	 * @return the {@link ATNumber} representing the length of the sequence of characters of this text.
122	 */
123	public ATNumber base_length() throws InterpreterException;
124	
125	/**
126	 * Concatenation infix operator. Returns the concatenation of the this text and the text representing a given object.
127	 * <p>
128	 * Usage example:
129	 * <code>"ambient" + "talk"</code> returns <code>"ambienttalk"</code>
130	 * 
131	 * @param other an object whose text representation is concatenated to the receiver text.
132	 * @return an ATText containing the elements of the receiver text and then the elements of text representing the other object.
133	 */
134	public ATText base__oppls_(ATObject other) throws InterpreterException;
135	
136	/**
137	 * Returns the value of evaluating the generalized equality between this text and a given one.
138	 * <p>
139	 * The generalized equality returns:
140	 * <ul>
141	 * <li>-1 if the receiver is numerically greater than the text passed as argument.
142	 * <li>1 if the receiver is numerically smaller than the text passed as argument.
143	 * <li>0 if the receiver is numerically equal to the the text passed as argument.
144	 * </ul>
145	 * <p>
146	 * Usage example:
147	 * <code>"ambienttalk" <=> "ambienttalk"</code> returns <code>0</code>
148	 * 
149	 * @param other a text.
150	 * @return a {@link ATNumber} resulting of applying the generalized equality between the receiver and other. 
151	 */
152	public ATNumber base__opltx__opeql__opgtx_(ATText other) throws InterpreterException;
153	
154	/**
155	 * Attempts to match this text against a given regular expression.
156	 * <p>
157	 * For regular expression syntax, see the Apache Regexp API of class
158	 * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">RE</a>.
159	 * <p>
160	 * Usage example:
161	 * <code>"ambienttalk" ~= ".*tt.*"</code> returns <code>true</code>
162	 * 
163	 * @param other a text representing the regular expression to be found in the text.
164	 * @return true if and only if, the receiver text matches completely the other text pattern.
165	 * @throws XIllegalArgument if regular expression's syntax is invalid. 
166	 */
167	public ATBoolean base__optil__opeql_(ATText other) throws InterpreterException;
168	
169	/**
170	 * Tries to convert the text into a numeric object (a number or a fraction).
171	 * Example: <code>"1.0".parseNumeric() => 1.0</code>
172	 * @return the numeric object denoted by this text
173	 * @throws XIllegalArgument if the text cannot be converted into a number or a fraction
174	 */
175	public ATNumeric base_parseNumeric() throws InterpreterException;
176	
177	/**
178	 * Converts a single AmbientTalk character (i.e. a text of length 1) into its corresponding
179	 * numeric Unicode value. See {@link java.lang.Character#getNumericValue(char)}.
180	 * @return a number that represents the unicode value of the text character
181	 * @throws XTypeMismatch if the receiver text is not a character (i.e. if it has length() > 1)
182	 */
183	public ATNumber base_toNumber() throws InterpreterException;
184	
185}