# Regular expressions for https://magnatune.com/api/grep

`re=` takes **Tcl Advanced Regular Expressions (ARE)**. They are close to PCRE/JavaScript, with a few differences listed below that matter: some PCRE habits silently match nothing.

How grep applies them:
- Matching is **case-insensitive**.
- Each catalog line is one album or one artist, with fields separated by tabs (`\t`). See the column headers at the top of https://magnatune.com/api/catalog.txt.
- **Every `re=` must match the same line** (AND). Use `|` inside one pattern for OR.
- At most 10 patterns, each up to 200 characters.

## Supported

|  Syntax | Meaning | Example  |
|---|---|---|
|  `abc` `.` | literal text, any character | `cello`  |
|  `a\|b` | either | `calm\|serene\|tranquil`  |
|  `( )` `(?: )` | group (capturing or not) | `(?:solo\|unaccompanied) (?:cello\|viol)`  |
|  `*` `+` `?` `{n}` `{n,}` `{n,m}` | repeat | `piano.{0,40}trio`  |
|  `*?` `+?` `??` `{n,m}?` | non-greedy repeat |  |
|  `[abc]` `[^abc]` `[a-z]` | character set | `[0-9]{4}`  |
|  `[[:alpha:]]` `[[:digit:]]` ... | POSIX classes inside a set |  |
|  `\d` `\s` `\w` (`\D` `\S` `\W`) | digit, space, word character | `\d+ min`  |
|  `\m` | **start of a word** | `\mmeditat` (meditation, meditative)  |
|  `\M` | **end of a word** | `piano\M` (piano, not pianos)  |
|  `\y` | word boundary, either end | `\ycello\y`  |
|  `\Y` | not a word boundary |  |
|  `^` `$` | start / end of the whole line | `^album`  |
|  `(?=...)` `(?!...)` | lookahead, negative lookahead | `piano(?!.*vocals)`  |
|  `\t` | tab (field separator) | `\tenergetic`  |
|  `\uXXXX` | a Unicode character | `caf\u00e9`  |
|  `(?i)` `(?x)` ... | embedded options at the start |  |
|  `***=` at the start | the rest is literal text, no metacharacters | `***=c++`  |

## Different from PCRE / JavaScript

|  You might write | In Tcl ARE | Use instead  |
|---|---|---|
|  `\bword\b` | `\b` is a **backspace**: matches nothing | `\mword\M` or `\yword\y`  |
|  `\<word\>` | literal `<` `>` | `\mword\M`  |
|  `(?<=...)` `(?<!...)` | lookbehind: **error** | put the context in the pattern: `solo cello`  |
|  `(?P<name>...)` `(?<name>...)` | named groups: **error** | `( )`  |
|  `\p{L}` | Unicode properties: **error** | `[[:alpha:]]`  |
|  `a++` `(?>...)` | possessive/atomic: **error** | `a+`  |
|  `\1` | back-references: refused by this API |  |

Errors come back as HTTP 400 with the reason.

## Examples

- Calm music with cello or piano: `https://magnatune.com/api/grep?re=\m(calm|serene|tranquil|peace|meditat)&re=\m(cello|piano)`
- Songs whose title mentions rain: `https://magnatune.com/api/grep?re=\mrain\M`
- Instrumental albums from 2020 on: `https://magnatune.com/api/grep?re=\tinstrumental\t&re=\t202[0-9]-`
