Sorting Nested JSON Objects

JSON Objects can contain an arbitrary number of keys and values (for which the value may itself be another JSON object). For example, a nested JSON object called "Monsters" might look like this:

Note that each value in the key-value pairs in the above object is actually a complete JSON object in its own right.

It is occasionally useful to be able to sort a JSON object that contains other JSON objects based on a value in one of the "sub-objects." For instance, if a JSON object exists that contains token names and distances to those tokens from a given point, one may want to sort the JSON so that the nearest objects are first, and the farthest are last.

Or, using the above "Monsters" example, one may wish to sort it by name, or by HP, or by HD.

The following macro routine is a generic method to sort JSON objects based on an arbitrary value within a nested object.

Contents 1 Assumptions 2 Macro Code and Discussion 2.1 Create Sample Object 2.2 Request Sorting Key and Sort Direction from User 2.3 Set Basic Variables 2.4 Extract the Value of sortKey from each Nested Object 2.5 Iterating through keyList and Each Nested Object 2.6 Outputting the Results in an Attractive Fashion

Assumptions

• This macro requires the use of a JSON object supporting version of MapTool; it was written and tested in version 1.3.b53.
• The macro is generic, and will run using any given JSON object conforming to the general "nested object" structure. In this case, a nested JSON object is created in the beginning so that there is a sample object to sort. However: this routine should be applicable to JSON arrays of objects as well - it would simply require using the index of the nested object rather than the nested object's key.
• It can be unclear which object is being discussed when you have multiply nested objects. In the following explanation, "nested object" will always refer to an object contained within a larger JSON. So, the larger object is Monsters, while Troll would be a nested object.

Macro Code and Discussion

Please see the full macro code for the complete macro.

Create Sample Object

This sequence simply creates a sample object to practice sorting. In actual use, you may wish to pass an object as an argument, or pull an object from a token's properties, as necessary.

Request Sorting Key and Sort Direction from User

This section is also optional (and not useful if this macro will be used as a function/called macro), but for the example code it makes it easier to experiment with. This section uses input() to gather user input, and abort() to halt processing if the user hits "Cancel." Finally, it uses an IF(): roll option to set a variable with a "friendly" indicator of sort direction, which will be used at the end in the final output.

Set Basic Variables

This segment initializes some variables that will be used later:

• sortObj is the object to be sorted (in this case, the JSON Object Monsters)
• sortOn is the value on which to sort (name, HD, or HP)
• sortDirection is the direction of the sort, which will be passed to listSort()
• sortObjContentList is a list - created using json.fields() - of each nested object within Monsters; effectively it is a list of the "names" of each monster
• keyList is a list that will contain the value that corresponds to the thing we're sorting on - so if you choose to sort by name, then keyList will ultimately contain the value of name for each monster in the Monsters object
• sortedJSON will hold the new, nicely sorted JSON object; the original object will be unchanged.

Extract the Value of sortKey from each Nested Object

Here, we use FOREACH() to loop through each element in sortObjContentList (in other words, go one-by-one through the list of monster names). The FOREACH() option lets us say that item holds the value of each of those (so for the first pass, item holds the first monster name in the list, and on the second pass, it moves to the next, and so on). We need to do this so that we can extract the detailed information about each monsters from the Monsters object (in this case, we assign the detailed information to a new variable called itemDetail).

With the nested objects extracted, we can then retrieve the value of the thing we're sorting on by using json.get() on the variable itemDetail. We stick that value in the previously empty list keyList.

Finally, once we've gone through each nested object held within Monsters and each nested object's value for our chosen sort (remember, we put that information in the variable sortKey) has been added to keyList, we're finished with the loop.

Now we actually can determine what the right order will ultimately be - we sort keyList using listSort() based on the direction specified by the user. This is a critical step! We've gone through each object, and figured out what the value of the thing we're sorting on is - so if we're sorting on "name", we've gone and actually retrieved each object's name, and put it in a list with the others. We then sort that list, which tells us the final order to use when we reassemble the main object!

Iterating through keyList and Each Nested Object

This is the most complex part of the routine. FOREACH(): through each element in the variable keyList (which, you will recall, contains the values corresponding to sortKey for each nested object). For each element in keyList, we then loop through all of the nested objects in Monsters to see which one(s) match up to the current element of keyList.

So, for example, if the current value - key - in the outer loop is 4, and we are sorting by "HD", the inner loop will iterate through each nested object and check to see if the value of "HD" for that nested object is equal to 4.

If a match is found, the matching nested object is added to sortedJSON using json.set(). In this fashion, we're using keyList to tell us what order the final nested objects should be in, and we then just need to go through our nested objects, setting them in that order via the following code.

Outputting the Results in an Attractive Fashion

The final step is to output results. The use of json.indent() here simply makes the sorted JSON object easy to read.

Token: A visual marker representing a character, monster, or NPCMacro: A series of text instructions used to automate processes in MapTool.Roll Option: One of several "switches" that alter how the macro code following the switch is executed