Update RegexLanguage Javadoc

regex/src/com.oracle.truffle.regex/src/com/oracle/truffle/regex/RegexEngineBuilder.java

@@ -44,6 +44,16 @@
  * <li>{@link String} {@code options} (optional): a comma-separated list of options for the engine,
  * the currently supported options include:</li>
  * <ul>
+ * <li>{@code Flavor}: the flavor of regular expressions to support
+ * <ul>
+ * <li>{@code ECMAScript} (default): regular expressions as provided by RegExp objects in ECMAScript
+ * </li>
+ * <li>{@code PythonStr}: regular expressions as provided by the {@code re} module in Python when
+ * compiling {@code str}-based regular expressions</li>
+ * <li>{@code PythonBytes}: regular expressions as provided by the {@code re} module in Python when
+ * compiling {@code bytes}-based regular expressions</li>
+ * </ul>
+ * </li>
  * <li>{@code U180EWhitespace}: the U+180E Unicode character (MONGOLIAN VOWEL SEPARATOR) is to be
  * treated as whitespace (Unicode versions before 6.3.0)</li>
  * <li>{@code RegressionTestMode}: all compilation is done eagerly, so as to detect errors early

regex/src/com.oracle.truffle.regex/src/com/oracle/truffle/regex/RegexLanguage.java

@@ -41,34 +41,37 @@
 /**
  * Truffle Regular Expression Language
  * <p>
- * This language represents classic regular expressions, currently in JavaScript flavor only. By
- * evaluating any source, or by importing the T_REGEX_ENGINE_BUILDER, you get access to the
- * {@link RegexEngineBuilder}. By calling this builder, you can build your custom
+ * This language represents classic regular expressions. By evaluating any source, you get access to
+ * the {@link RegexEngineBuilder}. By calling this builder, you can build your custom
  * {@link RegexEngine} which implements your flavor of regular expressions and uses your fallback
  * compiler for expressions not covered. The {@link RegexEngine} accepts regular expression patterns
  * and flags and compiles them to {@link RegexObject}s, which you can use to match the regular
  * expressions against strings.
  * <p>
  *
  * <pre>
- * Usage example in JavaScript:
+ * Usage example in pseudocode:
  * {@code
- * var engineBuilder = Polyglot.eval("application/tregex", "");
- * // or var engineBuilder = Polyglot.import("T_REGEX_ENGINE_BUILDER"); after initializing the language
- * var engine = engineBuilder();
- * var pattern = engine("(a|(b))c", "i");
- * var result = pattern.exec("xacy", 0);
- * print(result.isMatch);    // true
- * print(result.input);      // "xacy"
- * print(result.groupCount); // 3
- * print(result.start[0] + ", " + result.end[0]); // "1, 3"
- * print(result.start[1] + ", " + result.end[1]); // "1, 2"
- * print(result.start[2] + ", " + result.end[2]); // "-1, -1"
- * var result2 = pattern.exec("xxx", 0);
- * print(result.isMatch);    // false
- * print(result.input);      // null
- * print(result.groupCount); // 0
- * print(result.start[0] + ", " + result.end[0]); // throws IndexOutOfBoundsException
+ * engineBuilder = <eval any source in the "regex" language>
+ * engine = engineBuilder("Flavor=ECMAScript", optionalFallbackCompiler)
+ *
+ * regex = engine("(a|(b))c", "i")
+ * assert(regex.pattern == "(a|(b))c")
+ * assert(regex.flags.ignoreCase == true)
+ *
+ * result = regex.exec("xacy", 0)
+ * assert(result.isMatch == true)
+ * assert(result.input == "xacy")
+ * assert(result.groupCount == 3)
+ * assert([result.start[0], result.end[0]], [ 1,  3])
+ * assert([result.start[1], result.end[1]], [ 1,  2])
+ * assert([result.start[2], result.end[2]], [-1, -1])
+ *
+ * result2 = regex.exec("xxx", 0)
+ * assert(result2.isMatch == false)
+ * assert(result2.input == null)
+ * assert(result2.groupCount == 0)
+ * assertThrows([result2.start[0], result2.end[0]], IndexOutOfBoundsException)
  * }
  * </pre>
  */

regex/src/com.oracle.truffle.regex/src/com/oracle/truffle/regex/RegexObject.java

@@ -33,6 +33,7 @@
 import com.oracle.truffle.regex.result.RegexResult;
 import com.oracle.truffle.regex.runtime.RegexObjectExecMethod;
 import com.oracle.truffle.regex.runtime.RegexObjectMessageResolutionForeign;
+import com.oracle.truffle.regex.tregex.parser.flavors.PythonFlags;
 import com.oracle.truffle.regex.util.TruffleNull;
 import com.oracle.truffle.regex.util.TruffleReadOnlyMap;
 
@@ -42,7 +43,12 @@
  * three properties:
  * <ol>
  * <li>{@link String} {@code pattern}: the source of the compiled regular expression</li>
- * <li>{@link RegexFlags} {@code flags}: the set of flags passed to the regular expression compiler
+ * <li>{@link TruffleObject} {@code flags}: the set of flags passed to the regular expression
+ * compiler. The type differs based on the flavor of regular expressions used:
+ * <ul>
+ * <li>{@link RegexFlags} if the flavor was {@code ECMAScript}</li>
+ * <li>{@link PythonFlags} if the flavor was {@code PythonStr} or {@code PythonBytes}</li>
+ * </ul>
  * </li>
  * <li>{@link RegexObjectExecMethod} {@code exec}: an executable method that matches the compiled
  * regular expression against a string. The method accepts two parameters: