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

http://ambienttalk.googlecode.com/ · Java · 185 lines · 18 code · 15 blank · 152 comment · 0 complexity · a2ec6c194e9cef7b1afe86ed5fdd6df1 MD5 · raw file

  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. */
  28. package edu.vub.at.objects;
  29. import edu.vub.at.exceptions.InterpreterException;
  30. import edu.vub.at.exceptions.XIllegalArgument;
  31. import edu.vub.at.objects.grammar.ATExpression;
  32. /**
  33. * ATText is the public interface to a native AmbientTalk string (a string of characters).
  34. * Extends the ATExpression interface since a Text can also be output by the parser as a literal.
  35. *
  36. * @author tvc
  37. */
  38. public interface ATText extends ATExpression {
  39. // base-level interface
  40. /**
  41. * Explodes a text into a table of constituent characters.
  42. * <p>
  43. * Usage example:
  44. * <code>"ambienttalk".explode()</code> returns <code> [a, m, b, i, e, n, t, t, a, l, k]</code>
  45. *
  46. * @return an {@link ATTable} resulting of exploding the receiver text into a table of constituent characters.
  47. */
  48. public ATTable base_explode() throws InterpreterException;
  49. /**
  50. * Splits a text according to the given regular expression.
  51. * <p>
  52. * For regular expression syntax, see the Java regular-expression constructs in java.util.regex.Pattern.
  53. * For regular expression syntax, see the Apache Regexp API of class
  54. * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">RE</a>.
  55. * <p>
  56. * Usage example:
  57. * <code>"one, two, three".split(", ")</code> returns <code>[ "one", "two", "three" ]</code>
  58. *
  59. * @param regexpr a text representing the regular expression to apply in the split.
  60. * @return an {@link ATTable} resulting of splitting the receiver text into a table according to the given regular expression.
  61. * @throws XIllegalArgument if regular expression's syntax is invalid.
  62. */
  63. public ATTable base_split(ATText regexpr) throws InterpreterException;
  64. /**
  65. * Evaluates a given closure on those elements of this text that match a given regular expression.
  66. * <p>
  67. * For regular expression syntax, see the Apache Regexp API of class
  68. * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">RE</a>.
  69. * <p>
  70. * Usage example:
  71. * <code>"ambienttalk".find: "[aeiou]" do: { |vowel| buff << vowel; nil }</code> returns <code>buff = "aiea"</code>
  72. *
  73. * @param regexp a text representing the regular expression to be found in the text.
  74. * @param consumer the closure code that is applied each time the regular expression is matched in the text.
  75. * @return nil
  76. * @throws XIllegalArgument if regular expression's syntax is invalid.
  77. * @throws InterpreterException if raised inside the code closure.
  78. */
  79. public ATNil base_find_do_(ATText regexp, ATClosure consumer) throws InterpreterException;
  80. /**
  81. * Returns a new text replacing those elements of this text that match a given regular expression with the
  82. * value resulting of the evaluation of a given closure.
  83. * <p>
  84. * For regular expression syntax, see the Apache Regexp API of class
  85. * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">RE</a>.
  86. * <p>
  87. * Usage example:
  88. * <code>"ambienttalk".replace: "[aeiou]" by: { |vowel| vowel.toUpperCase() }</code> returns <code>AmbIEnttAlk</code>
  89. *
  90. * @param regexp a text representing the regular expression to be found in the text.
  91. * @param transformer the closure code that is applied each time the regular expression matches.
  92. * @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.
  93. * @throws XIllegalArgument if regular expression's syntax is invalid.
  94. * @throws InterpreterException if raised inside the code closure.
  95. */
  96. public ATText base_replace_by_(ATText regexp, ATClosure transformer) throws InterpreterException;
  97. /**
  98. * Converts all of the characters in this text to upper case.
  99. *
  100. * @return the {@link ATText} resulting of the conversion.
  101. */
  102. public ATText base_toUpperCase() throws InterpreterException;
  103. /**
  104. * Converts all of the characters in this text to lower case.
  105. *
  106. * @return the {@link ATText} resulting of the conversion.
  107. */
  108. public ATText base_toLowerCase() throws InterpreterException;
  109. /**
  110. * Returns the length of this text.
  111. *
  112. * @return the {@link ATNumber} representing the length of the sequence of characters of this text.
  113. */
  114. public ATNumber base_length() throws InterpreterException;
  115. /**
  116. * Concatenation infix operator. Returns the concatenation of the this text and the text representing a given object.
  117. * <p>
  118. * Usage example:
  119. * <code>"ambient" + "talk"</code> returns <code>"ambienttalk"</code>
  120. *
  121. * @param other an object whose text representation is concatenated to the receiver text.
  122. * @return an ATText containing the elements of the receiver text and then the elements of text representing the other object.
  123. */
  124. public ATText base__oppls_(ATObject other) throws InterpreterException;
  125. /**
  126. * Returns the value of evaluating the generalized equality between this text and a given one.
  127. * <p>
  128. * The generalized equality returns:
  129. * <ul>
  130. * <li>-1 if the receiver is numerically greater than the text passed as argument.
  131. * <li>1 if the receiver is numerically smaller than the text passed as argument.
  132. * <li>0 if the receiver is numerically equal to the the text passed as argument.
  133. * </ul>
  134. * <p>
  135. * Usage example:
  136. * <code>"ambienttalk" <=> "ambienttalk"</code> returns <code>0</code>
  137. *
  138. * @param other a text.
  139. * @return a {@link ATNumber} resulting of applying the generalized equality between the receiver and other.
  140. */
  141. public ATNumber base__opltx__opeql__opgtx_(ATText other) throws InterpreterException;
  142. /**
  143. * Attempts to match this text against a given regular expression.
  144. * <p>
  145. * For regular expression syntax, see the Apache Regexp API of class
  146. * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">RE</a>.
  147. * <p>
  148. * Usage example:
  149. * <code>"ambienttalk" ~= ".*tt.*"</code> returns <code>true</code>
  150. *
  151. * @param other a text representing the regular expression to be found in the text.
  152. * @return true if and only if, the receiver text matches completely the other text pattern.
  153. * @throws XIllegalArgument if regular expression's syntax is invalid.
  154. */
  155. public ATBoolean base__optil__opeql_(ATText other) throws InterpreterException;
  156. /**
  157. * Tries to convert the text into a numeric object (a number or a fraction).
  158. * Example: <code>"1.0".parseNumeric() => 1.0</code>
  159. * @return the numeric object denoted by this text
  160. * @throws XIllegalArgument if the text cannot be converted into a number or a fraction
  161. */
  162. public ATNumeric base_parseNumeric() throws InterpreterException;
  163. /**
  164. * Converts a single AmbientTalk character (i.e. a text of length 1) into its corresponding
  165. * numeric Unicode value. See {@link java.lang.Character#getNumericValue(char)}.
  166. * @return a number that represents the unicode value of the text character
  167. * @throws XTypeMismatch if the receiver text is not a character (i.e. if it has length() > 1)
  168. */
  169. public ATNumber base_toNumber() throws InterpreterException;
  170. }