Update the documentation of the regex dsl

Author: Robin Picard

docs/reference/regex_dsl.md

@@ -39,51 +39,55 @@ print(to_regex(digit))    # Output: [0-9]+
 
 ---
 
-## Early Introduction to Quantifiers & Operators
+## Early Introduction to Quantifiers & Combining Terms
 
 The DSL supports common regex quantifiers as methods on every `Term`. These methods allow you to specify how many times a pattern should be matched. They include:
 
-- **`times(count)`**: Matches the term exactly `count` times.
+- **`exactly(count)`**: Matches the term exactly `count` times.
 - **`optional()`**: Matches the term zero or one time.
 - **`one_or_more()`**: Matches the term one or more times (Kleene Plus).
 - **`zero_or_more()`**: Matches the term zero or more times (Kleene Star).
-- **`repeat(min_count, max_count)`**: Matches the term between `min_count` and `max_count` times (or open-ended if one value is omitted).
+- **`between(min_count, max_count)`**: Matches the term between `min_count` and `max_count` times (inclusive).
+- **`at_least(count)`**: Matches the term at least `count` times.
+- **`at_most(count)`**: Matches the term up to `count` times.
 
-Let’s see these quantifiers side by side with examples.
+These quantifiers can also be used as functions that take the `Term` as an argument. If the term is a plain string, it will be automatically converted to a `String` object. Thus `String("foo").optional()` is equivalent to `optional("foo")`.
+
+Let's see these quantifiers side by side with examples.
 
 ### Quantifiers in Action
 
-#### `times(count)`
+#### `exactly(count)`
 
 This method restricts the term to appear exactly `count` times.
 
 ```python
 # Example: exactly 5 digits
-five_digits = Regex(r"\d").times(5)
+five_digits = Regex(r"\d").exactly(5)
 print(to_regex(five_digits))  # Output: (\d){5}
 ```
 
-You can also use the `times` function:
+You can also use the `exactly` function:
 
 ```python
-from outlines.types import times
+from outlines.types import exactly
 
 # Example: exactly 5 digits
-five_digits = times(Regex(r"\d"), 5)
+five_digits = exactly(Regex(r"\d"), 5)
 print(to_regex(five_digits))  # Output: (\d){5}
 ```
 
 #### `optional()`
 
-The `optional()` method makes a term optional, meaning it may occur zero or one time.
+This method makes a term optional, meaning it may occur zero or one time.
 
 ```python
 # Example: an optional "s" at the end of a word
 maybe_s = String("s").optional()
 print(to_regex(maybe_s))  # Output: (s)?
 ```
 
-You can also use the `optional` function, the string will automatically be converted to a `String` object:
+You can also use the `optional` function:
 
 ```python
 from outlines.types import optional
@@ -116,15 +120,15 @@ print(to_regex(letters))  # Output: ([A-Za-z])+
 
 #### `zero_or_more()`
 
-This method means that the term can occur zero or more times.
+This method indicates that the term can occur zero or more times.
 
 ```python
 # Example: zero or more spaces
 spaces = String(" ").zero_or_more()
 print(to_regex(spaces))  # Output: ( )*
 ```
 
-You can also use the `zero_or_more` function, the string will automatically be converted to a `String` instance:
+You can also use the `zero_or_more` function:
 
 ```python
 from outlines.types import zero_or_more
@@ -134,40 +138,64 @@ spaces = zero_or_more(" ")
 print(to_regex(spaces))  # Output: ( )*
 ```
 
-#### `repeat(min_count, max_count)`
+#### `between(min_count, max_count)`
 
-The `repeat` method provides flexibility to set a lower and/or upper bound on the number of occurrences.
+This method indicates that the term can appear any number of times between `min_count` and `max_count` (inclusive).
 
 ```python
 # Example: Between 2 and 4 word characters
-word_chars = Regex(r"\w").repeat(2, 4)
+word_chars = Regex(r"\w").between(2, 4)
 print(to_regex(word_chars))  # Output: (\w){2,4}
-
-# Example: At least 3 digits (min specified, max left open)
-at_least_three = Regex(r"\d").repeat(3, None)
-print(to_regex(at_least_three))  # Output: (\d){3,}
-
-# Example: Up to 2 punctuation marks (max specified, min omitted)
-up_to_two = Regex(r"[,.]").repeat(None, 2)
-print(to_regex(up_to_two))  # Output: ([,.]){,2}
 ```
 
-You can also use the `repeat` function:
+You can also use the `between` function:
 
 ```python
-from outlines import repeat
+from outlines.types import between
 
 # Example: Between 2 and 4 word characters
-word_chars = repeat(Regex(r"\w"), 2, 4)
+word_chars = between(Regex(r"\w"), 2, 4)
 print(to_regex(word_chars))  # Output: (\w){2,4}
+```
+
+#### `at_least(count)`
 
-# Example: At least 3 digits (min specified, max left open)
-at_least_three = repeat(Regex(r"\d"), 3, None)
+This method indicates that the term must appear at least `count` times.
+
+```python
+# Example: At least 3 digits
+at_least_three = Regex(r"\d").at_least(3)
 print(to_regex(at_least_three))  # Output: (\d){3,}
+```
+
+You can also use the `at_least` function:
+
+```python
+from outlines.types import at_least
+
+# Example: At least 3 digits
+at_least_three = at_least(Regex(r"\d"), 3)
+print(to_regex(at_least_three))  # Output: (\d){3,}
+```
+
+#### `at_most(count)`
+
+This method indicates that the term can appear at most `count` times.
+
+```python
+# Example: At most 3 digits
+up_to_three = Regex(r"\d").at_most(3)
+print(to_regex(up_to_three))  # Output: (\d){0,3}
+```
+
+You can also use the `at_most` function:
+
+```python
+from outlines.types import at_most
 
-# Example: Up to 2 punctuation marks (max specified, min omitted)
-up_to_two = repeat(Regex(r"[,.]"), None, 2)
-print(to_regex(up_to_two))  # Output: ([,.]){,2}
+# Example: At most 3 digits
+up_to_three = at_most(Regex(r"\d"), 3)
+print(to_regex(up_to_three))  # Output: (\d){0,3}
 ```
 
 ---
@@ -186,17 +214,17 @@ pattern = String("hello") + " " + Regex(r"\w+")
 print(to_regex(pattern))  # Output: hello\ (\w+)
 ```
 
-### Alternation (`|`)
+### Alternation (`either()`)
 
-The `|` operator creates alternatives, allowing a match for one of several patterns.
+The `either()` function creates alternatives, allowing a match for one of several patterns. You can provide as many terms as you want.
 
 ```python
-# Example: Match either "cat" or "dog"
-animal = String("cat") | "dog"
-print(to_regex(animal))  # Output: (cat|dog)
+# Example: Match either "cat" or "dog" or "mouse"
+animal = either(String("cat"), "dog", "mouse")
+print(to_regex(animal))  # Output: (cat|dog|mouse)
 ```
 
-*Note:* When using operators with plain strings (such as `"dog"`), the DSL automatically wraps them in a `String` object and escapes the characters that have a special meaning in regular expressions.
+*Note:* When using `either()` with plain strings (such as `"dog"`), the DSL automatically wraps them in a `String` object that escapes the characters that have a special meaning in regular expressions, just like with quantifier functions.
 
 ---
 
@@ -223,7 +251,7 @@ For instance you can describe the answers in the GSM8K dataset using the followi
 ```python
 from outlines.types import sentence, digit
 
-answer = "A: " + sentence.repeat(2,4) + " So the answer is: " + digit.repeat(1,4)
+answer = "A: " + sentence.between(2,4) + " So the answer is: " + digit.between(1,4)
 ```
 
 ---
@@ -237,7 +265,7 @@ Suppose you want to create a regex that matches an ID format like "ID-12345", wh
 - Followed by exactly 5 digits.
 
 ```python
-id_pattern = "ID-" + Regex(r"\d").times(5)
+id_pattern = "ID-" + Regex(r"\d").exactly(5)
 print(to_regex(id_pattern))  # Output: ID-(\d){5}
 ```
 
@@ -273,9 +301,9 @@ When used in a Pydantic model, the email field is automatically validated agains
 Consider a pattern to match a simple date format: `YYYY-MM-DD`.
 
 ```python
-year = Regex(r"\d").times(4)         # Four digits for the year
-month = Regex(r"\d").times(2)         # Two digits for the month
-day = Regex(r"\d").times(2)           # Two digits for the day
+year = Regex(r"\d").exactly(4)         # Four digits for the year
+month = Regex(r"\d").exactly(2)        # Two digits for the month
+day = Regex(r"\d").exactly(2)          # Two digits for the day
 
 # Combine with literal hyphens
 date_pattern = year + "-" + month + "-" + day