As I mentioned in the first post in this series, I’ve been working on a set of macros to help me better track conditions on characters for D&D 4th Edition in MapTool. Building those macros has led me deeper into some of the capabilities of the MapTool macro language that I had previously avoided. Part 1 of the series focused on JSON objects; today we talk about JSON arrays.

What is a JSON array?

In any context, an array is basically a list. “1, 2, 3” is an array. A shopping list is an array.

A JSON array is a list enclosed in brackets and separated by commas for use in MapTool. As for what it’s a list OF, well, JSON arrays are flexible on that point.

You can have a JSON array that’s a list of numbers:

[r: MyJSONArray='[12, 3, -44]' ]

You can have a JSON array that’s a list of words:

[r: MyJSONArray='["Red", "Purple", "Yellow"]' ]

You can have a JSON array that’s a mixture of numbers and words:

[r: MyJSONArray='["Red", 3, -44]' ]

More interestingly, you can have a JSON array that’s a list of JSON objects – or even a list of other JSON arrays!

JSONObject1=[r: JsonObject1= '{"Color":"Red", "Number":12}' ]<br>
JSONObject2=[r: JsonObject2= '{"Color":"Purple", "Number":3}' ]<br>
JSONObject3=[r: JsonObject3= '{"Color":"Yellow", "Number":-44}' ]<br>
[h: MyJSONArray=' [ ]' ]
Array step 1=[r: MyJSONArray=json.append(MyJSONArray, JSONObject1) ]<br>
Array step 2=[r: MyJSONArray=json.append(MyJSONArray, JSONObject2) ]<br>
Array complete=[r: MyJSONArray=json.append(MyJSONArray, JSONObject3) ]<br>
<br>Second item = [r: SecondItem=json.get(MyJSONArray, 1)]
<br>Color of second item = [r: SecondItemColor=json.get(SecondItem, "Color")]

How do you build a JSON array?

As you can see from the examples above, you can build a simple JSON array in a manner very similar to building a JSON object. The contents of the array are separated by commas and enclosed in square brackets [ ], and the whole thing is enclosed in single quotes so that MapTool will allow you to use double quotes inside the array (so that it can contain words).

Another option I showed was to use the json.append function in MapTool. You need to start with an existing or blank JSON array (hence the MyJSONArray = ‘[ ]’ bit, creating a blank JSON array). You then append the new item to the end of the array.

What do you do with a JSON array?

As with a JSON object, a JSON array is useful if you store it as a property on a library token and then have it available for other macros to use later. It’s also useful because it’s an array – a list of things. With a list, you can do things like loop through each thing on the list using a FOREACH loop and do something to each thing on the list.

If you want to get some information out of an array, the simplest way to do it is to use the json.get command along with the appropriate index in the array. Each thing in the array has an index number, but you’ll want to keep in mind that the indexes start from zero.

Let me repeat that: The first item in an array is item 0, followed by item 1, and so on.

So, going back to my second array example, if I want to know what the middle of the three elements is, I’d do the following:

[r: MyJSONArray='["Red", "Purple", "Yellow"]' ]<br>
The middle color is [r: json.get(MyJSONArray, 1)]

Which returns:

You’ll note that picked index 1 in my json.get statement. If I’d wanted it to say “Red” (the first element of the list), I would have asked for json.get(MyJSONArray, 0). Very important to remember.

If I want to know how many items are in the JSON array, I can use json.length. Keep in mind that my three-item array with have json.length=3, but the highest index number will be 2 (because it starts counting from zero). Confusing, yes.

How do I change what’s in a JSON array?

Technically speaking, you can’t edit a JSON array. However, you can re-save a new array with the same name that’s based off an existing array.

If you have a particular element of the array that you want to set to a new value, you can use the json.set command.

Original array: [r: MyJSONArray='["Red", "Purple", "Yellow"]' ]<br>
I'm changing the array now... [h: MyJSONArray=json.set(MyJSONArray, 1, "Green")]<br>
New array: [r: MyJSONArray]

This returns:

What I’ve done is created a new array that is just like the original array except that I’ve set the second element (index 1 is the second element, remember) to the value “Green” instead of whatever it was before. I’ve saved this new array with the SAME NAME as the original array. So, I’ve effectively changed the original array, but I’ve technically created a new array with the same name (which accomplishes the same thing).

Another useful command is json.remove, which gives you the array minus whatever you’ve removed.

Original array: [r: MyJSONArray='["Red", "Purple", "Yellow"]' ]<br>
If I remove the middle element, I get this new array: [r: NewJSONArray=json.remove(MyJSONArray, 1)]

This returns:

If I’d used MyJSONArray= instead of NewJSONArray= in the second line, I would have effectively edited the array to remove the second element (index 1).

JSON objects within JSON arrays

Now, keep in mind that you can get fancy with JSON arrays. The things in the array can themselves be JSON objects or, messier still, JSON arrays. My last example in the opening section shows you one of these. It can get a little confusing depending on how deep you want to go, but there are definitely times when it’s useful to have lists of pairs of things (like colors with numbers, or token names with conditions).

Comparing JSON objects and JSON arrays

Bringing it all together, what are these things all about?

JSON objects are enclosed in curly braces { }. JSON arrays are enclosed in square brackets [ ].

JSON objects consist of labels and values (Name: Bob. Age: 23). JSON arrays are just lists of things (Bob, 23). However, you can put objects within arrays. You can also put objects within objects or arrays within objects or arrays within arrays… it can get messy!

To get a value out of an object, you can use json.get and then specify which key you want (PersonName=json.get(MyJSONObject, “Name”)). To get a value out of an array, you can use json.get and then specify the index of the item in the array that you want, with the first item having an index of 0 (PersonName=json.get(MyJSONArray, 0)).

Next step

So what’s next? Well, I keep talking about storing these objects and arrays on library tokens, so I think it’s time I talked about what a library token is.