docs, readme

Author: asg017

README.md

@@ -1,29 +1,35 @@
 # sqlite-regex
 
-A fast and performant SQLite extension for regular expressions.
+A fast and performant SQLite extension for regular expressions. Based on [`sqlite-loadable-rs`](https://github.com/asg017/sqlite-loadable-rs), and the [regex crate](https://crates.io/crates/regex).
 
-See [`sqlite-loadable-rs`](https://github.com/asg017/sqlite-loadable-rs), the framework that makes this extension possible.
+See [_Introducing sqlite-regex: The fastest Regular Expression Extension for SQLite_](https://observablehq.com/@asg017/introducing-sqlite-regex) (Jan 2023) for more details!
 
-## WORK IN PROGRESS
+If your company or organization finds this library useful, consider [supporting my work](#supporting)!
 
-This extension isn't 100% complete yet, but hoping to release in the next 1-2 weeks! A sneak peek at what to expect:
+![](./benchmarks/dates.png)
 
-### The fastest `REGEXP()` implementation in SQLite
+## Usage
 
-I don't have a fancy benchmark screenshot yet, but in my Mac, I get ~50% faster results with the `regexp()` in `sqlite-regex` over the "official" [regexp.c](https://github.com/sqlite/sqlite/blob/master/ext/misc/regexp.c) SQLite extension.
-
-### More regex utilities
+```sql
+.load ./regex0
+select 'foo' matches 'f';
 
-Very rarely does `regexp` cover all your regular expression needs. `sqlite-regex` also includes support for many other regex operations, such as:
+```
 
-**Find all occurances of a pattern in a string**
+**Find all occurrences of a pattern in a string**
 
 ```sql
-select regex_find('[0-9]{3}-[0-9]{3}-[0-9]{4}', 'phone: 111-222-3333');
+select regex_find(
+  '[0-9]{3}-[0-9]{3}-[0-9]{4}',
+  'phone: 111-222-3333'
+);
 -- '111-222-3333'
 
 select rowid, *
-from regex_find_all('\b\w{13}\b', 'Retroactively relinquishing remunerations is reprehensible.');
+from regex_find_all(
+  '\b\w{13}\b',
+  'Retroactively relinquishing remunerations is reprehensible.'
+);
 /*
 ┌───────┬───────┬─────┬───────────────┐
 │ rowid │ start │ end │     match     │
@@ -36,6 +42,19 @@ from regex_find_all('\b\w{13}\b', 'Retroactively relinquishing remunerations is
 */
 ```
 
+**Use RegexSets to match a string on multiple patterns in linear time**
+
+```sql
+select regexset_is_match(
+  regexset(
+    "bar",
+    "foo",
+    "barfoo"
+  ),
+  'foobar'
+)
+```
+
 **Split the string on the given pattern delimiter**
 
 ```sql
@@ -54,7 +73,7 @@ from regex_split('[ \t]+', 'a b     c d    e');
 */
 ```
 
-**Replace occurances of a pattern with another string**
+**Replace occurrences of a pattern with another string**
 
 ```sql
 select regex_replace(
@@ -68,4 +87,62 @@ select regex_replace_all('a', 'abc abc', '');
 -- 'bc bc'
 ```
 
-And more!
+## Documentation
+
+See [`docs.md`](./docs.md) for a full API reference.
+
+## Installing
+
+The [Releases page](https://github.com/asg017/sqlite-regex/releases) contains pre-built binaries for Linux x86_64, MacOS, and Windows.
+
+### As a loadable extension
+
+If you want to use `sqlite-regex` as a [Runtime-loadable extension](https://www.sqlite.org/loadext.html), Download the `regex0.dylib` (for MacOS), `regex0.so` (Linux), or `regex0.dll` (Windows) file from a release and load it into your SQLite environment.
+
+> **Note:**
+> The `0` in the filename (`regex0.dylib`/ `regex0.so`/`regex0.dll`) denotes the major version of `sqlite-regex`. Currently `sqlite-regex` is pre v1, so expect breaking changes in future versions.
+
+For example, if you are using the [SQLite CLI](https://www.sqlite.org/cli.html), you can load the library like so:
+
+```sql
+.load ./regex0
+select regex_version();
+-- v0.1.0
+```
+
+Or in Python, using the builtin [sqlite3 module](https://docs.python.org/3/library/sqlite3.html):
+
+```python
+import sqlite3
+con = sqlite3.connect(":memory:")
+con.enable_load_extension(True)
+con.load_extension("./regex0")
+print(con.execute("select regex_version()").fetchone())
+# ('v0.1.0',)
+```
+
+Or in Node.js using [better-sqlite3](https://github.com/WiseLibs/better-sqlite3):
+
+```javascript
+const Database = require("better-sqlite3");
+const db = new Database(":memory:");
+db.loadExtension("./regex0");
+console.log(db.prepare("select regex_version()").get());
+// { 'regex_version()': 'v0.1.0' }
+```
+
+Or with [Datasette](https://datasette.io/):
+
+```
+datasette data.db --load-extension ./regex0
+```
+
+## Supporting
+
+I (Alex 👋🏼) spent a lot of time and energy on this project and [many other open source projects](https://github.com/asg017?tab=repositories&q=&type=&language=&sort=stargazers). If your company or organization uses this library (or you're feeling generous), then please [consider supporting my work](https://alexgarcia.xyz/work.html), or share this project with a friend!
+
+## See also
+
+- [sqlite-xsv](https://github.com/asg017/sqlite-xsv), A SQLite extension for working with CSVs
+- [sqlite-loadable](https://github.com/asg017/sqlite-loadable-rs), A framework for writing SQLite extensions in Rust
+- [sqlite-http](https://github.com/asg017/sqlite-http), A SQLite extension for making HTTP requests

benchmarks/README.md

@@ -1,3 +1,17 @@
+# `sqlite-regex` Benchmarks
+
+## Caveat: Benchmarks are hard and easy to game
+
+This benchmark isn't exhaustive, and only benchmarks between other widely-used SQLite regex extensions.
+
+## `REGEXP()` across all SQLite regex extensions
+
+![](./dates.png)
+
+Explaination: Essentially running `select count(*) from corpus where line regexp "\d{4}-\d{2}-\d{2}"`, though `regexp` and `sqlean/re` doesn't support `\d` or `{4}` syntax.
+
+```
 gcc -O3 -shared -fPIC regexp.c -o regexp.dylib
 
 gcc -O3 -shared -fPIC -I./ re.c sqlite3-re.c -o re.dylib
+```