@chrismo/superkit 1.0.0

package/docs/recipes/records.spq

@@ -0,0 +1,61 @@
+-- sk_include array.spq
+
+-- the built-in `fields` function is similar, but puts each field into its own
+-- nested array, though it also handles nested keys. This keys operator here
+-- attempts to emulate jq's keys, which does not go deep but only lists the
+-- top-level ones.
+
+fn skdoc_keys(): (
+  cast(
+    {name:"sk_keys",
+     type:"op",
+     desc:"Returns the keys of the top-level fields in a record. This does not go deep into nested records.",
+     args:[],
+     examples:[{i:"{a:1,b:{c:333}} | sk_keys",o:"['a','b']"}
+               {i:"{x:10,y:20,z:30} | sk_keys",o:"['x','y','z']"}] }, <skdoc>)
+)
+
+op sk_keys: (
+  fields(this) | unnest this | values this[0] | uniq | collect(this)
+)
+
+fn skdoc_merge_records(): (
+  cast(
+    {name:"sk_merge_records",
+     type:"op",
+     desc:"Merges an array of records into a single record by combining the fields. If there are duplicate keys, the last one wins.",
+     args:[],
+     examples:[{i:"[{a:1},{b:{c:333}}] | sk_merge_records",o:"{a:1,b:{c:333}}"}] }, <skdoc>)
+)
+
+op sk_merge_records: (
+  this::string
+  | replace(this, "},{" ",")
+  | parse_sup(this[1:-1])
+)
+
+-- # this sort of approach suffers from an illegal left-hand assignment:
+-- ❯ zq '[{a:1},{b:{c:333}}] | (over this with obj={} | flatten(this) | obj[key[0]]:=value )'
+
+-- # this was a better step from Phil, but doesn't work on nested records
+-- over this
+-- | over flatten(this)
+-- | collect_map(|{key[0]:value}|)
+-- | values parse_sup(replace(this::string, "|", ""))'
+
+fn skdoc_add_ids(): (
+  cast(
+    {name:"sk_add_ids",
+     type:"op",
+     desc:"Prepends an incrementing id field to each record. Always returns an array.",
+     args:[],
+     examples:[{i:"[{a:3},{b:4}] | sk_add_ids",o:"[{id:1,a:3},{id:2,b:4}]"}] }, <skdoc>)
+)
+
+op sk_add_ids: (
+  sk_in_array(this)
+  | unnest this
+  | count
+  | values {id:count,...that}
+  | collect(this)
+)

package/docs/recipes/string.md

@@ -0,0 +1,177 @@
+---
+title: String
+layout: default
+nav_order: 1
+parent: Recipes
+---
+
+# String Recipes
+
+Source: `string.spq` (includes `integer.spq`)
+
+---
+
+## sk_slice
+
+Returns a slice of the string passed in, even if indexes are out of range.
+
+**Type:** function
+
+| Argument | Description |
+|----------|-------------|
+| `s` | The string to slice. |
+| `start` | Starting index, zero-based, inclusive. |
+| `end` | Ending index, exclusive. |
+
+```supersql
+sk_slice('howdy')
+-- => 'Howdy'
+```
+
+**Implementation:**
+
+```supersql
+fn sk_slice(s, start, end): (
+  s[sk_clamp(start, -len(s), len(s)):sk_clamp(end, -len(s), len(s))]
+)
+```
+
+---
+
+## sk_capitalize
+
+Upper the first character of the string, lower the remaining string.
+
+**Type:** function
+
+| Argument | Description |
+|----------|-------------|
+| `s` | The string to capitalize. |
+
+```supersql
+sk_capitalize('hoWDy')
+-- => 'Howdy'
+```
+
+**Implementation:**
+
+```supersql
+fn sk_capitalize(s): (
+  f"{upper(sk_slice(s, 0, 1))}{lower(sk_slice(s,1,len(s)))}"
+)
+```
+
+---
+
+## sk_titleize
+
+Splits string by space and capitalizes each word.
+
+**Type:** function
+
+| Argument | Description |
+|----------|-------------|
+| `s` | The string to titleize |
+
+```supersql
+sk_titleize('once uPON A TIME')
+-- => 'Once Upon A Time'
+```
+
+**Implementation:**
+
+```supersql
+fn sk_titleize(s): (
+  [unnest split(s, " ") | values sk_capitalize(this)] | join(this, " ")
+)
+```
+
+---
+
+## sk_pad_left
+
+Inserts pad_char to the left of the string until it reaches target_length.
+
+**Type:** function
+
+| Argument | Description |
+|----------|-------------|
+| `s` | The string to pad |
+| `pad_char` | The character to pad with |
+| `target_length` | The target length of the string |
+
+```supersql
+values sk_pad_left('abc', ' ', 5)
+-- => '  abc'
+```
+
+**Implementation:**
+
+```supersql
+fn sk_pad_left(s, pad_char, target_length): (
+  len(s) < target_length ? sk_pad_left(f'{pad_char}{s}', pad_char, target_length) : s
+)
+```
+
+---
+
+## sk_pad_right
+
+Inserts pad_char to the right of the string until it reaches target_length.
+
+**Type:** function
+
+| Argument | Description |
+|----------|-------------|
+| `s` | The string to pad |
+| `pad_char` | The character to pad with |
+| `target_length` | The target length of the string |
+
+```supersql
+values sk_pad_right('abc', ' ', 5)
+-- => 'abc  '
+```
+
+**Implementation:**
+
+```supersql
+fn sk_pad_right(s, pad_char, target_length): (
+  len(s) < target_length ? sk_pad_right(f'{s}{pad_char}', pad_char, target_length) : s
+)
+```
+
+---
+
+## sk_urldecode
+
+URL decoder for SuperDB. Splits on `%`, decodes each hex-encoded segment, and joins back together.
+
+**Type:** operator
+
+| Argument | Description |
+|----------|-------------|
+| `url` | The URL-encoded string to decode |
+
+```bash
+super -I string.spq -s -c 'values sk_urldecode("%2Ftavern%20test")' -
+```
+
+**Implementation:**
+
+```supersql
+op sk_decode_seg s: (
+  len(s) == 0
+    ? s
+    : (is_error(hex(s[1:3]))
+        ? s
+        : hex(s[1:3])::string + s[3:])
+)
+
+op sk_urldecode url: (
+  split(url, "%")
+    | unnest this
+    | decode_seg this
+    | collect(this)
+    | join(this, "")
+)
+```

package/docs/recipes/string.spq

@@ -0,0 +1,105 @@
+-- sk_include integer.spq
+-- sk_include integer.spq -- to test duplicate includes
+
+op skdoc_slice: (
+  cast(
+    {name:"sk_slice",
+     type:"func",
+     desc:"Returns a slice of the string passed in, even if indexes are out of range.",
+     args:[{name:"s",desc:"The string to slice."}
+           {name:"start",desc:"Starting index, zero-based, inclusive."}
+           {name:"end",desc:"Ending index, exclusive."}],
+     examples:[{i:"sk_slice('howdy')",o:"'Howdy'"}] }, <skdoc>)
+)
+
+-- This isn't necessary with zq, but during early releases of super, the
+-- behavior of slice was changed to return an error if the indexes are out of
+-- range. There was discussion of possibly returning to the old behavior.
+fn sk_slice(s, start, end): (
+  s[sk_clamp(start, -len(s), len(s)):sk_clamp(end, -len(s), len(s))]
+)
+
+op skdoc_capitalize: (
+  cast(
+    {name:"sk_capitalize",
+     type:"func",
+     desc:"Upper the first character of the string, lower the remaining string.",
+     args:[{name:"s",desc:"The string to capitalize."}],
+     examples:[{i:"sk_capitalize('hoWDy')",o:"'Howdy'"}] }, <skdoc>)
+)
+
+fn sk_capitalize(s): (
+  f"{upper(sk_slice(s, 0, 1))}{lower(sk_slice(s,1,len(s)))}"
+)
+
+op skdoc_titleize: (
+  cast(
+    {name:"sk_titleize",
+     type:"func",
+     desc:"Splits string by space and capitalizes each word.",
+     args:[{name:"s",desc:"The string to titleize"}],
+     examples:[{i:"sk_titleize('once uPON A TIME')",o:"'Once Upon A Time'"}] }, <skdoc>)
+)
+
+fn sk_titleize(s): (
+  -- this could be smarter, ignoring insignificant words
+  -- and such, but that will be a lot more complex.
+  [unnest split(s, " ") | values sk_capitalize(this)] | join(this, " ")
+)
+
+fn skdoc_pad_left(): (
+  cast(
+    {name:"sk_pad_left",
+     type:"func",
+     desc:"Inserts pad_char to the left of the string until it reaches target_length.",
+     args:[{name:"s",desc:"The string to pad"}
+           {name:"pad_char",desc:"The character to pad with"}
+           {name:"target_length",desc:"The target length of the string"}],
+     examples:[{i:"values sk_pad_left('abc', ' ', 5)",o:"'  abc'"}] }, <skdoc>)
+)
+
+fn sk_pad_left(s, pad_char, target_length): (
+  len(s) < target_length ? sk_pad_left(f'{pad_char}{s}', pad_char, target_length) : s
+)
+
+fn skdoc_pad_right(): (
+  cast(
+    {name:"sk_pad_right",
+     type:"func",
+     desc:"Inserts pad_char to the right of the string until it reaches target_length.",
+     args:[{name:"s",desc:"The string to pad"}
+           {name:"pad_char",desc:"The character to pad with"}
+           {name:"target_length",desc:"The target length of the string"}],
+     examples:[{i:"values sk_pad_right('abc', ' ', 5)",o:"'abc  '"}] }, <skdoc>)
+)
+
+fn sk_pad_right(s, pad_char, target_length): (
+  len(s) < target_length ? sk_pad_right(f'{s}{pad_char}', pad_char, target_length) : s
+)
+
+-- TODO: skdoc_urldecode
+
+-- URL Decoder for SuperDB
+-- Usage: super -I urldecode.spq -s -c 'values sk_urldecode(this)' - <<< '"%%2Ftavern%%20test"'
+-- Or inline the definitions in your query
+
+-- Helper operator to decode a single segment after splitting on %%
+-- If the segment starts with valid 2-char hex, converts it to the character
+-- Otherwise returns the segment as-is
+op sk_decode_seg s: (
+  len(s) == 0
+    ? s
+    : (is_error(hex(s[1:3]))
+        ? s
+        : hex(s[1:3])::string + s[3:])
+)
+
+-- Main URL decoder operator
+-- Splits on %%, decodes each hex-encoded segment, and joins back together
+op sk_urldecode url: (
+  split(url, "%%")
+    | unnest this
+    | sk_decode_seg this
+    | collect(this)
+    | join(this, "")
+)