JSON Related Functions
JSON (JavaScript Object Notation) is a lightweight data format
commonly used for web APIs and data exchange. Sheerpower provides
two powerful functions for working with JSON data:
JSON$() for converting Sheerpower clusters into JSON
strings, and jsonutil$() for parsing and manipulating
existing JSON data. Together, these functions make it easy to
integrate Sheerpower applications with web services and modern
data workflows.
JSON$() - Converting Clusters to JSON
The JSON$() function converts Sheerpower cluster arrays
into properly formatted JSON strings.
Syntax
string$ = JSON$(clustername [, row_option])
Where:
- clustername - The cluster to convert
- row_option - Optional. Leave it out to convert the current row:
the row added last, or the one
set cluster name: row n selected.
Give a row number to convert that row, or -1 to convert every row.
The result is a JSON object named after the cluster, and each field appears under its
name without the $ or other type sigil.
Example 1: Every Row
Pass -1 to convert the whole cluster array:
cluster person: id$, name$, age
add cluster person
person->id$ = "1"
person->name$ = "Alice"
person->age = 30
end add
add cluster person
person->id$ = "2"
person->name$ = "Bob"
person->age = 25
end add
json_output$ = JSON$(person, -1)
print json_output$
Output:
{
"person":[
{
"id":"1",
"name":"Alice",
"age":30
},
{
"id":"2",
"name":"Bob",
"age":25
}
]
}
Without a row option, JSON$() converts only the current row —
here Bob, the row added last:
print JSON$(person)
Output:
{
"person":
{
"id":"2",
"name":"Bob",
"age":25
}
}
Example 2: Nested Objects from a Cluster Template
Embed a cluster template with prefix cluster, and its fields become a
nested object named after the template:
cluster address: street$, city$, zip$
cluster person: id$, name$, age, prefix cluster address
add cluster person
person->id$ = "1"
person->name$ = "Alice"
person->age = 30
person->address->street$ = "123 Main St"
person->address->city$ = "Springfield"
person->address->zip$ = "12345"
end add
add cluster person
person->id$ = "2"
person->name$ = "Bob"
person->age = 25
person->address->street$ = "456 Elm St"
person->address->city$ = "Shelbyville"
person->address->zip$ = "67890"
end add
json_output$ = JSON$(person, -1)
print json_output$
Output:
{
"person":[
{
"id":"1",
"name":"Alice",
"age":30,
"address": {
"street":"123 Main St",
"city":"Springfield",
"zip":"12345"
}
},
{
"id":"2",
"name":"Bob",
"age":25,
"address": {
"street":"456 Elm St",
"city":"Shelbyville",
"zip":"67890"
}
}
]
}
Example 3: Single Row Output
Give a row number to convert just that row:
// Using the person cluster from Example 2
single_person$ = JSON$(person, 1) // Get first row only
print single_person$
Output:
{
"person":
{
"id":"1",
"name":"Alice",
"age":30,
"address": {
"street":"123 Main St",
"city":"Springfield",
"zip":"12345"
}
}
}
jsonutil$() - Working with JSON Data
The jsonutil$() function parses, extracts, and
manipulates JSON data using JSON Pointer syntax.
Syntax
result$ = jsonutil$(json_input$ [, json_pointer$])
Where:
- json_input$ - The JSON string to process
- json_pointer$ - Optional JSON Pointer path to
extract specific values; without it the whole document comes back, formatted for reading
Example 1: Extracting Values
Extract specific values from JSON:
json_data$ = '{"name":"Alice","age":30,"city":"Springfield"}'
name$ = jsonutil$(json_data$, '/name')
age$ = jsonutil$(json_data$, '/age')
city$ = jsonutil$(json_data$, '/city')
print "Name: "; name$
print "Age: "; age$
print "City: "; city$
Output:
Name: Alice
Age: 30
City: Springfield
Example 2: Working with Arrays
Extract values from JSON arrays:
json_array$ = '[{"name":"Alice","age":30},{"name":"Bob","age":25}]'
first_name$ = jsonutil$(json_array$, '/0/name')
second_age$ = jsonutil$(json_array$, '/1/age')
print "First person: "; first_name$
print "Second person age: "; second_age$
Output:
First person: Alice
Second person age: 25
Example 3: Pretty-Printing JSON
With no pointer (or an empty one), jsonutil$() returns the whole document, formatted for reading:
json_data$ = '{"name":"Alice","age":30,"city":"Springfield"}'
print jsonutil$(json_data$)
Output:
{
"name": "Alice",
"age": 30,
"city": "Springfield"
}
Example 4: Converting JSON to Clusters
Load JSON data into a Sheerpower cluster with cluster input. The rows sit in an array under a key named after the cluster, and each name maps to the field of the same name:
cluster employee: name$, age, department$
json_data$ = '{"employee":[' +
'{"name":"Alice","age":30,"department":"Engineering"},' +
'{"name":"Bob","age":25,"department":"Sales"},' +
'{"name":"Carol","age":35,"department":"Marketing"}]}'
open file json_ch: name '@employees.json', access output
print #json_ch: json_data$
close #json_ch
cluster input name '@employees.json': employee
print "Employees:"
collect cluster employee
end collect
for each employee
print employee->name$; " ("; str$(employee->age); ") - "; employee->department$
next employee
Output:
Employees:
Alice (30) - Engineering
Bob (25) - Sales
Carol (35) - Marketing
Practical Use Cases
Web API Integration
Combine both functions for complete API workflows:
// Prepare data to send to an API
cluster order: id$, product$, quantity, price
add cluster order
order->id$ = "ORD001"
order->product$ = "Widget"
order->quantity = 5
order->price = 12.99
end add
// Convert to JSON for API request
api_request$ = JSON$(order, 1)
print "Sending to API: "; api_request$
// Simulate API response
api_response$ = '{"status":"success","order_id":"ORD001","total":64.95}'
// Extract response data
status$ = jsonutil$(api_response$, '/status')
total$ = jsonutil$(api_response$, '/total')
print "API Status: "; status$
print "Order Total: $"; total$
Note: These JSON functions make Sheerpower
applications fully compatible with modern web services, REST APIs,
and JSON-based data exchange formats. The combination of
JSON$() and jsonutil$() provides complete
round-trip JSON support.
(Show/Hide Sheerpower JSON Takeaways)
Sheerpower JSON Takeaways
JSON$() converts Sheerpower clusters (including nested ones)
into properly formatted JSON strings.- Converts the current row by default; a row number converts that row,
and -1 converts every row (
row_option).
jsonutil$() parses and manipulates JSON using JSON Pointer
paths (e.g., /0/name).- Handles arrays and nested objects with simple pointer syntax; with no pointer it
returns the whole document formatted for reading.
cluster input loads JSON back into a Sheerpower cluster
(the rows under a key named after the cluster).- Together they enable full JSON round-trips:
generate → send → parse → reload.
- Ideal for integrating Sheerpower with REST APIs, modern data workflows,
and JSON-based services.
