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

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