SRP Json Express (JsonX) is a new and improved API for building and parsing json. Gone are the days of handles and memory management. SRP JsonX was built with workflow in mind.
Available in version 2.2 or later.
Stateful
To avoid dealing with handles, SRP JsonX relies on state. Under the hood, SRP JsonX maintains a stack of JsonX documents. Whenever you start a JsonX document, that document is placed at the top of the stack and becomes the current document. Every document has a current path, which defaults to the root of the document. These two states are important to navigating, updating, and building json documents with SRP JsonX. When you are done with a document, you call SRP_JsonX_End, which removes the current document from memory and makes the previous document on the stack the current one.
Creating Json
There are two routines for creating new json documents: SRP_JsonX_Begin and SRP_JsonX_BeginString. SRP_JsonX_Begin creates a new json data structure that can be built, navigated, and modified at will. SRP_JsonX_BeginString creates a new json string that can only be built top down.
$insert SRPJSONX
// Create a new document with a json object as the root. All documents are named for debugging purposes only
SRP_JsonX_Begin('MyDocument', '{')
// Since we are in an object, the first parameter should be a member name followed by a value
// In this case, the value is "[", which starts a new array and makes that array the current path
SRP_JsonX('employees', '[')
// Since we are in an array, the first parameter should be a value. In this case, we are starting a new object
SRP_JsonX('{')
SRP_JsonX('firstname', 'John') ; // Since we're in an object, the first parameter is a member name and the second is its value
SRP_JsonX('lastname', 'Doe')
SRP_JsonX('age', 21)
SRP_JsonX('}')
// Note on the previous line that passing "}" closes an object and moves the current path back to the parent, so when we call this next
// line, we are back in the array. Once again, we'll add an employee object
SRP_JsonX('{')
SRP_JsonX('firstname', 'Anna')
SRP_JsonX('lastname', 'Smith')
SRP_JsonX('age', 32)
SRP_JsonX('}')
// We can also pass json strings as a value, which get fully parsed and added to the current path, which is currently the employees array
SRP_JsonX('{"firstname":"Peter", "lastname":"Jones", "age":43}')
// This line closes the array and sets the current path back to the root object
SRP_JsonX(']')
// When you pass numbers as values, JsonX assumes you want that value to be unquoted in the final json
SRP_JsonX('count', 4)
// To pass a boolean value, we need to add a hint parameter. Hints always come after values
SRP_JsonX('active', 1, 'Bool')
// To set a something to null, omit the value. If you cannot omit the value, you can set the hint to 'Null'
SRP_JsonX('alwaysnull')
// If you want a number to be quoted in the json, use the 'String' hint
SRP_JsonX('alwaysstring', 4.321, 'String')
// We're all done, so let's turn the document into pretty formatted json and end it at the same time
Json = SRP_JsonX_End('Pretty')
In this example, we start a new document called MyDocument. The document name is for debugging purposes only, so use whatever you want. The second parameter defines the new document's root. It must be "{" or "[". Note that this new document is now the active one and it's current path is pointing to the root of the document.
SRP_JsonX is a special routine whose parameters are interpreted according to the current state. The comment above help explain how SRP_JsonX makes its decisions. As you can see,
To get the final json output, we call SRP_JsonX_End. This routine does two things. It optionally returns the current document as a json string, then it removes the current document from memory and makes the previous document on the stack the current one.
Glossary
Document: An active JsonX data structure in memory.
Element: A member of
