Skip to content

Commit a611fa0

Browse files
jeffreyavenjeffreyaven
committed
updated docs
1 parent 4342a8e commit a611fa0

23 files changed

+307954
-2
lines changed

‎.github/FUNDING.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
---
2+
github: [stackql]

‎.github/workflows/build.yml

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: build
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- .github/**
8+
- src/**
9+
- test/**
10+
- Makefile
11+
pull_request:
12+
branches: [main]
13+
workflow_dispatch:
14+
15+
jobs:
16+
build:
17+
runs-on: ${{ matrix.os }}
18+
strategy:
19+
matrix:
20+
os: [ubuntu-20.04, windows-latest, macos-latest]
21+
22+
steps:
23+
- uses: actions/checkout@v2
24+
25+
- name: Install dependencies on Linux
26+
if: matrix.os == 'ubuntu-20.04'
27+
run: sudo apt-get install -y sqlite3 gcc unzip
28+
29+
- name: Install dependencies on Windows
30+
if: matrix.os == 'windows-latest'
31+
shell: pwsh
32+
run: |
33+
choco install -y mingw
34+
choco install -y unzip
35+
choco install -y sqlite
36+
37+
- name: Install dependencies on macOS
38+
if: matrix.os == 'macos-latest'
39+
run: brew install sqlite3 gcc unzip
40+
41+
- name: Download and prepare sources
42+
run: |
43+
make prepare-dist
44+
make download-sqlite
45+
46+
- name: Compile and test on Linux
47+
if: matrix.os == 'ubuntu-20.04'
48+
run: |
49+
make compile-linux
50+
make test-all
51+
52+
- name: Compile on Windows
53+
if: matrix.os == 'windows-latest'
54+
shell: pwsh
55+
run: |
56+
make compile-windows
57+
58+
- name: Compile on macOS
59+
if: matrix.os == 'macos-latest'
60+
run: |
61+
make compile-macos

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
*.log
2+
13
# Prerequisites
24
*.d
35

‎Makefile

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Copyright (c) 2024 StackQL Studios, MIT License
2+
# https://github.com/stackql
3+
4+
.PHONY: prepare-dist compile-linux compile-windows compile-macos test-all test clean
5+
6+
SQLITE_RELEASE_YEAR := 2024
7+
SQLITE_VERSION := 3460000
8+
9+
SRC_DIR = src
10+
DIST_DIR = dist
11+
12+
prepare-dist:
13+
mkdir -p $(DIST_DIR)
14+
rm -rf $(DIST_DIR)/*
15+
16+
download-sqlite:
17+
curl -L https://www.sqlite.org/$(SQLITE_RELEASE_YEAR)/sqlite-amalgamation-$(SQLITE_VERSION).zip --output src.zip
18+
unzip src.zip
19+
mv sqlite-amalgamation-$(SQLITE_VERSION)/* $(SRC_DIR)
20+
rm -rf sqlite-amalgamation-$(SQLITE_VERSION)
21+
rm src.zip
22+
23+
compile-linux:
24+
gcc -O2 -fPIC -shared -I$(SRC_DIR) $(SRC_DIR)/json_equal/*.c -o $(DIST_DIR)/json_equal.so -lsqlite3
25+
gcc -O2 -fPIC -shared -I$(SRC_DIR) $(SRC_DIR)/regexp/*.c -o $(DIST_DIR)/regexp.so -lsqlite3
26+
gcc -O2 -fPIC -shared -I$(SRC_DIR) $(SRC_DIR)/split_part/*.c -o $(DIST_DIR)/split_part.so -lsqlite3
27+
28+
compile-windows:
29+
gcc -O2 -shared -Isrc src/json_equal/*.c -o dist/json_equal.dll
30+
gcc -O2 -shared -Isrc src/regexp/*.c -o dist/regexp.dll
31+
gcc -O2 -shared -Isrc src/split_part/*.c -o dist/split_part.dll
32+
33+
compile-macos:
34+
gcc -O2 -fPIC -dynamiclib -Isrc src/json_equal/*.c -o dist/json_equal.dylib
35+
gcc -O2 -fPIC -dynamiclib -Isrc src/regexp/*.c -o dist/regexp.dylib
36+
gcc -O2 -fPIC -dynamiclib -Isrc src/split_part/*.c -o dist/split_part.dylib
37+
38+
test-all:
39+
make test suite=json_equal
40+
make test suite=regexp
41+
make test suite=split_part
42+
43+
# fails if grep does find a failed test case
44+
test:
45+
@sqlite3 < test/$(suite).sql > test.log
46+
@cat test.log | (! grep -Ex "[0-9_]+.[^1]")
47+
48+
clean:
49+
rm -f $(DIST_DIR)/*.so
50+
rm -f $(DIST_DIR)/*.dll
51+
rm -f $(DIST_DIR)/*.dylib
52+
rm -f test.log

‎README.md

Lines changed: 112 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,112 @@
1-
# sqlite-ext-functions
2-
Extended SQLite functions for StackQL
1+
# SQLite Extended Functions for StackQL
2+
3+
Extended SQLite functions for StackQL providing additional capabilities for JSON manipulation, regular expressions, and string splitting.
4+
5+
## Table of Contents
6+
7+
- [Introduction](#introduction)
8+
- [Features](#features)
9+
- [Installation](#installation)
10+
- [Usage](#usage)
11+
- [Development](#development)
12+
- [Contributing](#contributing)
13+
- [License](#license)
14+
15+
## Introduction
16+
17+
This repository contains a set of extended functions for SQLite designed to enhance the SQL capabilities in StackQL. These extensions provide additional JSON handling, regular expression matching, and string manipulation functionalities.
18+
19+
## Features
20+
21+
- **JSON Functions**: Includes `json_equal` to compare JSON objects and arrays.
22+
- **Regular Expression Functions**: Includes `regexp_like`, `regexp_substr`, and `regexp_replace` for pattern matching and manipulation.
23+
- **String Splitting Function**: Includes `split_part` to split strings based on a separator and retrieve specific parts.
24+
25+
## Installation
26+
27+
### Prerequisites
28+
29+
- **SQLite**: Ensure SQLite is installed on your system.
30+
- **GCC**: Required for compiling the extensions.
31+
- **Git**: For cloning the repository.
32+
33+
### Building from Source
34+
35+
Clone the repository and build the extensions:
36+
37+
```bash
38+
git clone https://github.com/stackql/sqlite-ext-functions.git
39+
cd sqlite-ext-functions
40+
41+
# Prepare the distribution directory
42+
make prepare-dist
43+
44+
# Download the SQLite amalgamation source
45+
make download-sqlite
46+
47+
# Compile the extensions for your platform
48+
make compile-linux # For Linux
49+
make compile-windows # For Windows
50+
make compile-macos # For macOS
51+
```
52+
53+
### Load Extensions
54+
55+
After compilation, you can load the extensions in your SQLite shell using:
56+
57+
```sql
58+
.load '/path/to/dist/json_equal'
59+
.load '/path/to/dist/regexp'
60+
.load '/path/to/dist/split_part'
61+
```
62+
63+
## Usage
64+
65+
### JSON Functions
66+
67+
```sql
68+
SELECT json_equal('{"key": "value"}', '{"key": "value"}'); -- Returns 1 (true)
69+
SELECT json_equal('[1, 2, 3]', '[3, 2, 1]'); -- Returns 0 (false)
70+
```
71+
72+
### Regular Expression Functions
73+
74+
```sql
75+
SELECT regexp_like('hello world', '^hello'); -- Returns 1 (true)
76+
SELECT regexp_substr('hello world', 'w.*d'); -- Returns 'world'
77+
SELECT regexp_replace('hello world', 'world', 'SQLite'); -- Returns 'hello SQLite'
78+
```
79+
80+
### String Splitting Function
81+
82+
```sql
83+
SELECT split_part('one,two,three', ',', 2); -- Returns 'two'
84+
SELECT split_part('one,two,three', ',', -1); -- Returns 'three'
85+
```
86+
87+
## Development
88+
89+
### Testing
90+
91+
Run tests to verify the functionality of the extensions:
92+
93+
```bash
94+
make test-all
95+
```
96+
97+
### Clean Up
98+
99+
Clean the distribution directory and test logs:
100+
101+
```bash
102+
make clean
103+
```
104+
105+
## License
106+
107+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
108+
109+
## Contact
110+
111+
For questions or support, please reach out to [StackQL Studios](https://github.com/stackql).
112+

‎docs/json_equal.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
## json_equal
2+
3+
```text
4+
json_equal(JSON1, JSON2)
5+
```
6+
7+
Compares two JSON strings and returns 1 if they are equivalent, 0 otherwise. This function supports comparison of JSON objects and arrays and treats objects with keys in different orders as equivalent, following the JSON specification.
8+
9+
```sql
10+
SELECT json_equal('{"key": "value"}', '{"key": "value"}');
11+
-- Returns 1 (true)
12+
13+
SELECT json_equal('{"key1": "value1", "key2": "value2"}', '{"key2": "value2", "key1": "value1"}');
14+
-- Returns 1 (true)
15+
16+
SELECT json_equal('{"key": "value"}', '{"key": "different"}');
17+
-- Returns 0 (false)
18+
19+
SELECT json_equal('[1, 2, 3]', '[1, 2, 3]');
20+
-- Returns 1 (true)
21+
22+
SELECT json_equal('[1, 2, 3]', '[3, 2, 1]');
23+
-- Returns 0 (false)
24+
25+
SELECT json_equal('[{"key": "value"}]', '[{"key": "value"}]');
26+
-- Returns 1 (true)
27+
```
28+
29+
### Key Features
30+
31+
- **Supports JSON objects and arrays:** Allows for deep comparisons of JSON structures.
32+
- **Order-agnostic comparison:** Treats JSON objects with keys in different orders as equivalent, as per the JSON specification.
33+
34+
### Installation and Usage
35+
36+
SQLite command-line interface:
37+
38+
```
39+
sqlite> .load ./json_equal.so
40+
sqlite> SELECT json_equal('{"key": "value"}', '{"key": "value"}');
41+
```
42+
### Implementation Details
43+
44+
The `json_equal` function is implemented using the [cJSON library](https://github.com/DaveGamble/cJSON) by Dave Gamble. It is part of the StackQL extension suite for SQLite, providing enhanced JSON handling capabilities.
45+
46+
[⬇️ Download](https://github.com/stackql/stackql/releases/latest) •
47+
[✨ Explore](https://github.com/stackql/stackql) •
48+
[🚀 Follow](https://github.com/stackql)

‎docs/regexp_fns.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
## Regular Expression Functions in SQLite
2+
3+
These functions provide capabilities for regular expression pattern matching and string manipulation. Each function expects the input `source` and `pattern` to be TEXT. They offer features like checking for matches, extracting substrings, and replacing patterns.
4+
5+
[regexp_like](#regexp_like) •
6+
[regexp_substr](#regexp_substr) •
7+
[regexp_replace](#regexp_replace)
8+
9+
### regexp_like
10+
11+
```text
12+
regexp_like(source, pattern)
13+
```
14+
15+
Checks if the `source` string matches the `pattern`. Returns 1 if the pattern matches the string, 0 otherwise.
16+
17+
```sql
18+
SELECT regexp_like('hello world', 'hello');
19+
-- Returns 1
20+
21+
SELECT regexp_like('hello world', '^world');
22+
-- Returns 0
23+
```
24+
25+
### regexp_substr
26+
27+
```text
28+
regexp_substr(source, pattern)
29+
```
30+
31+
Returns the substring of the `source` that matches the `pattern`. If no match is found, it returns `NULL`.
32+
33+
```sql
34+
SELECT regexp_substr('hello world', 'w.*d');
35+
-- Returns 'world'
36+
37+
SELECT regexp_substr('hello world', 'abc');
38+
-- Returns NULL
39+
```
40+
41+
### regexp_replace
42+
43+
```text
44+
regexp_replace(source, pattern, replacement)
45+
```
46+
47+
Replaces the substring of the `source` that matches the `pattern` with the `replacement` string. If no match is found, the original string is returned.
48+
49+
```sql
50+
SELECT regexp_replace('hello world', 'world', 'SQLite');
51+
-- Returns 'hello SQLite'
52+
53+
SELECT regexp_replace('hello world', 'abc', 'def');
54+
-- Returns 'hello world'
55+
```
56+
57+
### Supported Regular Expression Syntax
58+
59+
- **X\*** Zero or more occurrences of X
60+
- **X\+** One or more occurrences of X
61+
- **X?** Zero or one occurrence of X
62+
- **(X)** Match X
63+
- **X\|Y** X or Y
64+
- **^X** X occurring at the beginning of the string
65+
- **X$** X occurring at the end of the string
66+
- **.** Match any single character
67+
- **\\c** Character c where c is one of \\\{}()[]\|*+?.
68+
- **\\c** C-language escapes for c in afnrtv, e.g., \t or \n
69+
- **[abc]** Any single character from the set abc
70+
- **[^abc]** Any single character not in the set abc
71+
- **[a-z]** Any single character in the range a-z
72+
- **[^a-z]** Any single character not in the range a-z
73+
74+
### Installation and Usage
75+
76+
SQLite command-line interface:
77+
78+
```
79+
sqlite> .load ./regexp_fns.so
80+
sqlite> SELECT regexp_like('hello world', 'hello');
81+
```
82+
83+
### Implementation Details
84+
85+
This extension is built using the [tiny-regex-c library](https://github.com/kokke/tiny-regex-c) by Kristian Evensen, providing a minimalistic and efficient implementation of regular expressions in C. It is part of the StackQL suite for SQLite, offering enhanced string manipulation capabilities.
86+
87+
[⬇️ Download](https://github.com/stackql/stackql/releases/latest) •
88+
[✨ Explore](https://github.com/stackql/stackql) •
89+
[🚀 Follow](https://github.com/stackql)

0 commit comments

Comments
 (0)