Skip to content

Commit 1a2c9d2

Browse files
claudechrismo
claude
authored and
chrismo
committed
Add recipes section to website
Document all SuperKit recipe functions (string, array, integer, character, format, records, escape) as browsable pages on the Jekyll site, with a parent index page and Recipes section on the homepage. https://claude.ai/code/session_012dhrHYqypaFKT7JR8wTimP
1 parent 2d34188 commit 1a2c9d2

File tree

9 files changed

+557
-0
lines changed

9 files changed

+557
-0
lines changed

‎_build/recipes/array.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: Array
3+
layout: default
4+
nav_order: 2
5+
parent: Recipes
6+
---
7+
8+
# Array Recipes
9+
10+
Source: `array.spq`
11+
12+
---
13+
14+
## sk_in_array
15+
16+
Puts value in an array if value isn't an array itself.
17+
18+
**Type:** function
19+
20+
| Argument | Description |
21+
|----------|-------------|
22+
| `value` | any |
23+
24+
```supersql
25+
sk_in_array(1)
26+
-- => [1]
27+
28+
sk_in_array([1])
29+
-- => [1]
30+
```
31+
32+
---
33+
34+
## sk_array_flatten
35+
36+
Flattens an array of arrays into a single array.
37+
38+
**Type:** operator
39+
40+
```supersql
41+
[1,2,[3,4],5] | sk_array_flatten
42+
-- => [1,2,3,4,5]
43+
44+
[[1,2],[3,4]] | sk_array_flatten
45+
-- => [1,2,3,4]
46+
```

‎_build/recipes/character.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Character
3+
layout: default
4+
nav_order: 4
5+
parent: Recipes
6+
---
7+
8+
# Character Recipes
9+
10+
Source: `character.spq` (includes `string.spq`)
11+
12+
---
13+
14+
## sk_seq
15+
16+
Generates a sequence 0..n-1 (like generate_series).
17+
18+
**Type:** operator
19+
20+
| Argument | Description |
21+
|----------|-------------|
22+
| `n` | Number of elements to generate |
23+
24+
```supersql
25+
sk_seq(3)
26+
-- => 0, 1, 2
27+
```
28+
29+
---
30+
31+
## sk_hex_digits
32+
33+
Returns the 16 hex digit characters as an array.
34+
35+
**Type:** function
36+
37+
```supersql
38+
sk_hex_digits()
39+
-- => ["0","1","2","3","4","5","6","7","8","9","a","b","c","d","e","f"]
40+
```
41+
42+
---
43+
44+
## sk_chr
45+
46+
Converts an integer (0-127) to its ASCII character.
47+
48+
**Type:** function
49+
50+
| Argument | Description |
51+
|----------|-------------|
52+
| `code` | ASCII code (0-127) |
53+
54+
```supersql
55+
sk_chr(65)
56+
-- => 'A'
57+
```
58+
59+
---
60+
61+
## sk_alpha
62+
63+
Converts 1-26 to A-Z.
64+
65+
**Type:** function
66+
67+
| Argument | Description |
68+
|----------|-------------|
69+
| `n` | Number 1-26 |
70+
71+
```supersql
72+
sk_alpha(3)
73+
-- => 'C'
74+
```

‎_build/recipes/escape.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Escape
3+
layout: default
4+
nav_order: 7
5+
parent: Recipes
6+
---
7+
8+
# Escape Recipes
9+
10+
Source: `escape.spq`
11+
12+
Functions for safely escaping values for CSV, TSV, and shell contexts, plus
13+
patterns for safe text ingestion from shell pipelines.
14+
15+
---
16+
17+
## sk_csv_field
18+
19+
Escapes a string for use as a CSV field per RFC 4180. Wraps in double quotes
20+
and doubles internal quotes when the value contains commas, quotes, or
21+
newlines. Plain values pass through unchanged.
22+
23+
**Type:** function
24+
25+
| Argument | Description |
26+
|----------|-------------|
27+
| `s` | The string to escape |
28+
29+
```supersql
30+
sk_csv_field('plain')
31+
-- => 'plain'
32+
33+
sk_csv_field('hello, world')
34+
-- => quoted and wrapped
35+
```
36+
37+
---
38+
39+
## sk_csv_row
40+
41+
Builds a CSV row from an array of values. Each element is cast to string and
42+
escaped with sk_csv_field, then joined with commas.
43+
44+
**Type:** function
45+
46+
| Argument | Description |
47+
|----------|-------------|
48+
| `arr` | Array of values to format as a CSV row |
49+
50+
---
51+
52+
## sk_shell_quote
53+
54+
Wraps a string in POSIX shell single quotes. Internal single quotes are escaped
55+
so the result is safe for shell interpolation. Protects against injection of `$`,
56+
backticks, and other shell metacharacters.
57+
58+
**Type:** function
59+
60+
| Argument | Description |
61+
|----------|-------------|
62+
| `s` | The string to quote |
63+
64+
```supersql
65+
sk_shell_quote('hello world')
66+
-- => single-quoted string
67+
68+
sk_shell_quote('has $var')
69+
-- => single-quoted, $ not expanded
70+
```
71+
72+
---
73+
74+
## sk_tsv_field
75+
76+
Escapes a value for use in a TSV field. Casts to string, then replaces literal
77+
tab and newline characters with their backslash-escaped forms.
78+
79+
**Type:** function
80+
81+
| Argument | Description |
82+
|----------|-------------|
83+
| `s` | The value to escape |
84+
85+
---
86+
87+
## Shell Patterns for Safe Text Ingestion
88+
89+
The key insight: never interpolate untrusted text into a SuperQL string literal.
90+
Pipe raw text through `super` with `-i line` and let the serializer handle
91+
escaping. These patterns work from any language that can spawn a subprocess.
92+
93+
### safe_text_to_record
94+
95+
Pipe raw text into super to build a record without string interpolation.
96+
97+
```bash
98+
echo "$text" | super -s -i line -c "values {body: this}" -
99+
```
100+
101+
### safe_text_to_string
102+
103+
Pipe raw text through super to get a properly escaped SUP string literal.
104+
105+
```bash
106+
echo "$text" | super -s -i line -c "values this" -
107+
```
108+
109+
### safe_multiline_to_record
110+
111+
Collapse multiline text into a single record field.
112+
113+
```bash
114+
echo "$text" | super -s -i line \
115+
-c 'aggregate s:=collect(this) | values {body: join(s, "\n")}' -
116+
```
117+
118+
### safe_append_to_sup_file
119+
120+
Append a timestamped record with raw text to a `.sup` file.
121+
122+
```bash
123+
echo "$text" | super -s -i line \
124+
-c "values {ts: now(), body: this}" - >> data.sup
125+
```

‎_build/recipes/format.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Format
3+
layout: default
4+
nav_order: 5
5+
parent: Recipes
6+
---
7+
8+
# Format Recipes
9+
10+
Source: `format.spq`
11+
12+
---
13+
14+
## sk_format_bytes
15+
16+
Returns the size in bytes in human readable format.
17+
18+
**Type:** function
19+
20+
| Argument | Description |
21+
|----------|-------------|
22+
| `value` | Must be castable to uint64 |
23+
24+
```supersql
25+
sk_format_bytes(1048576)
26+
-- => '1 MB'
27+
28+
sk_format_bytes(0)
29+
-- => '0 B'
30+
```
31+
32+
Supports units up to EB (exabytes). The full unit list: B, KB, MB, GB, TB, PB, EB.

‎_build/recipes/index.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Recipes
3+
layout: default
4+
has_children: true
5+
nav_order: 5
6+
---
7+
8+
# Recipes
9+
10+
Reusable SuperSQL functions and operators for common tasks. Include them in your
11+
queries with `from` or `-I`:
12+
13+
```supersql
14+
from 'string.spq' | values sk_capitalize('hello')
15+
```
16+
17+
```bash
18+
super -I string.spq -c "values sk_capitalize('hello')"
19+
```
20+
21+
Recipe source files are available in the
22+
[superdb-mcp](https://github.com/chrismo/superdb-mcp/tree/main/docs/recipes)
23+
repository.

‎_build/recipes/integer.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Integer
3+
layout: default
4+
nav_order: 3
5+
parent: Recipes
6+
---
7+
8+
# Integer Recipes
9+
10+
Source: `integer.spq`
11+
12+
---
13+
14+
## sk_clamp
15+
16+
Clamps a value between min and max.
17+
18+
**Type:** function
19+
20+
| Argument | Description |
21+
|----------|-------------|
22+
| `i` | The value to clamp. |
23+
| `min` | The minimum value. |
24+
| `max` | The maximum value. |
25+
26+
```supersql
27+
sk_clamp(1, 2, 3)
28+
-- => 2
29+
30+
sk_clamp(4, 2, 3)
31+
-- => 3
32+
33+
sk_clamp(2, 2, 3)
34+
-- => 2
35+
```
36+
37+
---
38+
39+
## sk_min
40+
41+
Returns the minimum of two values.
42+
43+
**Type:** function
44+
45+
| Argument | Description |
46+
|----------|-------------|
47+
| `a` | The first value. |
48+
| `b` | The second value. |
49+
50+
```supersql
51+
sk_min(1, 2)
52+
-- => 1
53+
54+
sk_min(3, 2)
55+
-- => 2
56+
```
57+
58+
---
59+
60+
## sk_max
61+
62+
Returns the maximum of two values.
63+
64+
**Type:** function
65+
66+
| Argument | Description |
67+
|----------|-------------|
68+
| `a` | The first value. |
69+
| `b` | The second value. |
70+
71+
```supersql
72+
sk_max(1, 2)
73+
-- => 2
74+
75+
sk_max(3, 2)
76+
-- => 3
77+
```

0 commit comments

Comments
 (0)