Creates and parses JSON.

Syntax

Result = SRP_Json(Handle, Service, Param1, Param2, Param3)

Returns

The service result.

Parameters

ParameterDescription
HandleHandle to JSON Entity. Required.
ServiceThe service to execute against the given JSON Entity Handle. Required.
Param1Generic parameter show purpose depends upon the Service being used. Optional.
Param2Generic parameter show purpose depends upon the Service being used. Optional.
Param3Generic parameter show purpose depends upon the Service being used. Optional.

Remarks

With RESTful WebAPI services becoming more prominent, the need to build and parse JSON is ever increasing. SRP_Json provides an API that not only makes this task easier, it also ensures the operations will happen quickly. Like many of our SRP Utilities, this single method provides multiple functions through services.

To get started, here are some terminologies you should become familiar with:

  • JSON: JavaScript Object Notation. This is a lightweight interchange format utilized by many modern WebAPIs.
  • JSON Entity: SRP_Json creates and manipulates JSON entities. A JSON entity might be one of the following types: Object, Array, Number, String, or Boolean.
  • JSON Entity Handle: SRP_Json creates or returns JSON Entity Handles, which are simply numbers that point to a specific entity in memory. These handles are also passed to SRP_Json to manipulate a specific entity. You must never alter a handle yourself.
  • JSON object: A JSON Entity that is of type "Object".
  • JSON array: A JSON Entity that is of type "Array".
  • value: A number, string, or boolean value as opposed to a JSON Entity Handle.
  • member: A JSON entity that is a child of a JSON object. A member is identified by a name. For example, a JSON object can have a member whose name is "id."
  • element: A JSON entity that is a child of a JSON array. An element is identified by an index. The first element in an array is always 1.

QuickStart Guide

The full list of services are provided below, but first lets get a bird's eye view of what it's like to use the API. We'll start with building a JSON from scratch, then we'll show how to parse JSON and extract values. In both cases, we'll use the following sample JSON:

{"employees":[
    {"firstName":"John", "lastName":"Doe"},
    {"firstName":"Anna", "lastName":"Smith"},
    {"firstName":"Peter", "lastName":"Jones"}
]}

Here is how you parse JSON. The following example assumes we have the entire JSON contents above in a variable called SampleJSON:

// Parse the SampleJSON string
ParseResult = SRP_Json(EmployeesHandle, "Parse", SampleJSON)

// The result is "" if parsing was successful
If ParseResult EQ "" then
   
   // Success! Now get the employee array
   EmployeeArrayHandle = SRP_Json(EmployeesHandle, "Get", "employees")
   If EmployeeArrayHandle NE 0 then
       
       // Loop through each employee, extracting first and last name
       NumEmployees = SRP_Json(EmployeeArrayHandle, "GetCount")
       For iEmployee = 1 to NumEmployees
           FirstName = SRP_Json(EmployeeArrayHandle, "GetValue", "[":i:"].firstName")
           LastName = SRP_Json(EmployeeArrayHandle, "GetValue", "[":i:"].lastName")
       Next iEmployee
       
   end
   
 end else
   
   // There was an error in parsing, so show it to the user
   Msg(@Window, ParseResult:@FM:@FM:@FM:"!")
   
 end

// We're all done with the JSON entity that was created when parsing
SRP_Json(EmployeesHandle, "Release")

Now, let's create the sample JSON from scratch:

// Create the root object, which we'll call employees
If SRP_Json(EmployeesHandle, "New") then
   
   // Create a new array
   If SRP_Json(EmployeeArrayHandle, "New", "Array") then
       
       // Add the first employee
       If SRP_Json(SingleEmployeeHandle, "New") then
           SRP_Json(SingleEmployeeHandle, "SetValue", "firstName", "John")
           SRP_Json(SingleEmployeeHandle, "SetValue", "lastName", "Doe")
           SRP_Json(EmployeeArrayHandle, "Add", SingleEmployeeHandle)
           SRP_Json(SingleEmployeeHandle, "Release")
       end
       
       // Add the second employee
       If SRP_Json(SingleEmployeeHandle, "New") then
           SRP_Json(SingleEmployeeHandle, "SetValue", "firstName", "Anna")
           SRP_Json(SingleEmployeeHandle, "SetValue", "lastName", "Smith")
           SRP_Json(EmployeeArrayHandle, "Add", SingleEmployeeHandle)
           SRP_Json(SingleEmployeeHandle, "Release")
       end
       
       // Add the third employee
       If SRP_Json(SingleEmployeeHandle, "New") then
           SRP_Json(SingleEmployeeHandle, "SetValue", "firstName", "Peter")
           SRP_Json(SingleEmployeeHandle, "SetValue", "lastName", "Jones")
           SRP_Json(EmployeeArrayHandle, "Add", SingleEmployeeHandle)
           SRP_Json(SingleEmployeeHandle, "Release")
       end
       
       // Now add the array as a member of the root object
       SRP_Json(EmployeesHandle, "Set", "employees", EmployeeArrayHandle)
       
       // All done with the array object
       SRP_Json(EmployeeArrayHandle, "Release")
   
   end
   
   // Now get the actual JSON
   SampleJSON = SRP_Json(EmployeesHandle, "Stringify", "STYLED")
   
   // All done with the root object
   SRP_Json(EmployeesHandle, "Release")
   
end

Services

SRP_Json provides the following services. The first parameter is always a handle to an entity. Sometimes this handle is just an empty or unassigned variable, such as when you want to create a new JSON Entity. All other times the handle references a JSON Entity already in memory. The rest of the parameters depend upon the service in question, and if you are using the latest SRP Editor you'll see the tooltips change once you select a service--making it easy to know how to use it.

ServiceDescription
AddAdds a JSON Entity to a JSON array.
AddValueAdds a value to a JSON array.
ContainsDetermines if a JSON object contains the given member or if a JSON array contains the given index.
GetReturns a descendant JSON Entity within a given JSON Entity.
GetCountReturns the number of members in a JSON object or elements in a JSON array.
GetMembersReturns a list of a JSON object's members.
GetValueReturns a descendant value within a given JSON Entity.
NewCreates a new JSON Entity.
ParseParses a standardized JSON string into a new JSON Entity.
ReleaseDeallocates a JSON Entity from memory.
RemoveRemoves a member from a JSON object or an element from a JSON array.
RemoveAllRemoves all members from a JSON obect or all elements from a JSON array.
SetSets a member within a JSON object or element within a JSON array to the given JSON Entity.
SetValueSets a member within a JSON object or element within a JSON array to the given value.
StringifyFormats the given JSON Entity into a standardized JSON string.
TypeReturns a JSON Entity's type.

Click on the service above to read more details.

  • No labels