bplist: update docs with from_ns_keyed_archiver reference, add error …

…case to function

format/apple/bplist/bplist.md

@@ -27,6 +27,29 @@ $ fq torepr com.apple.UIAutomation.plist
 }
 ```
 
+### Decoding NSKeyedArchiver serialized objects
+
+A common way that Swift and Objective-C libraries on macOS serialize objects
+is through the NSKeyedArchiver API, which flattens objects into a list of elements
+and class descriptions that are reconstructed into an object graph using CFUID
+elements in the property list. `fq` includes a function, `from_ns_keyed_archiver`,
+which will rebuild this object graph into a friendly representation. The `bplist`
+data must first be passed through `torepr` to create a JSON representation.
+
+If no parameters are supplied, it will assume that there is a CFUID located at
+`."$top".root` that specifies the root from which decoding should occur. If this
+is not present, the user must specify a root object in the `.$objects` list from
+which to decode.
+
+The following examples show how this might be used (in this case, in the `fq` REPL):
+```
+# Assume $top.root is present
+bplist> torepr | from_ns_keyed_archiver
+
+# Specify optional root
+bplist> torepr | from_ns_keyed_archiver(1)
+```
+
 ### Authors
 - David McDonald
 [@dgmcdona](https://github.com/dgmcdona)

format/apple/bplist/ns_keyed_archiver.jq

@@ -1,9 +1,8 @@
-def from_ns_keyed_archiver(root):
+def from_ns_keyed_archiver($root):
   (  
-    . as 
-      {
-        "$objects": $objects
-      }
+    . as {
+      "$objects": $objects
+    }
   | def _f($id; $seen_ids):
       def _r($id):
         if $seen_ids | has("\($id)") then "cycle-\($id)"
@@ -65,13 +64,8 @@ def from_ns_keyed_archiver(root):
         end
       );
     def _f($id): _f($id; {"\($id)": true});
-    _f(root)
+    _f($root)
   );
 
 def from_ns_keyed_archiver:
-  ( . as 
-      {
-        "$top": {root: $root}
-      }
-    | from_ns_keyed_archiver($root.cfuid)
-  );
+    from_ns_keyed_archiver(."$top"?.root?.cfuid // error("root node not found, must specify index"));