Fixes and embeds documentation

README.md

@@ -51,7 +51,7 @@ bitcoin_blkdat,
 [bitcoin_block](doc/formats.md#bitcoin_block),
 bitcoin_script,
 bitcoin_transaction,
-bplist,
+[bplist](doc/formats.md#bplist),
 bsd_loopback_frame,
 [bson](doc/formats.md#bson),
 bzip2,

doc/formats.md

@@ -27,7 +27,7 @@
 |[`bitcoin_block`](#bitcoin_block) |Bitcoin&nbsp;block                                                                       |<sub>`bitcoin_transaction`</sub>|
 |`bitcoin_script`                  |Bitcoin&nbsp;script                                                                      |<sub></sub>|
 |`bitcoin_transaction`             |Bitcoin&nbsp;transaction                                                                 |<sub>`bitcoin_script`</sub>|
-|`bplist`                          |Apple&nbsp;Binary&nbsp;Property&nbsp;List                                                |<sub></sub>|
+|[`bplist`](#bplist)               |Apple&nbsp;Binary&nbsp;Property&nbsp;List                                                |<sub></sub>|
 |`bsd_loopback_frame`              |BSD&nbsp;loopback&nbsp;frame                                                             |<sub>`inet_packet`</sub>|
 |[`bson`](#bson)                   |Binary&nbsp;JSON                                                                         |<sub></sub>|
 |`bzip2`                           |bzip2&nbsp;compression                                                                   |<sub>`probe`</sub>|
@@ -257,6 +257,46 @@ Decode value as bitcoin_block
 ... | bitcoin_block({has_header:false})
 ```
 
+## bplist
+
+### Show full decoding
+```sh
+$ fq -d bplist dv Info.plist
+```
+
+### Timestamps
+Timestamps in Apple Binary Property Lists are encoded as Cocoa Core Data
+timestamps, where the raw value is the floating point number of seconds since
+January 1, 2001. By default, `fq` will render the raw floating point value. In
+order to get the raw value or string description, use the `todescription`
+function, you can use the `tovalue` and `todescription` functions:
+
+```sh
+$ fq 'torepr.SomeTimeStamp | tovalue' Info.plist
+685135328
+
+$ fq 'torepr.SomeTimeStamp | todescription' Info.plist
+"2022-09-17T19:22:08Z"
+```
+
+
+### Get JSON representation
+```sh
+$ fq torepr com.apple.UIAutomation.plist
+{
+  "UIAutomationEnabled": true
+}
+```
+
+### Authors
+- David McDonald
+[@dgmcdona](https://github.com/dgmcdona)
+
+### References
+- http://fileformats.archiveteam.org/wiki/Property_List/Binary
+- https://medium.com/@karaiskc/understanding-apples-binary-property-list-format-281e6da00dbd
+- https://opensource.apple.com/source/CF/CF-550/CFBinaryPList.c
+
 ## bson
 
 ### Convert represented value to JSON

format/bplist/bplist.go

@@ -11,7 +11,7 @@ import (
 	"github.com/wader/fq/pkg/scalar"
 )
 
-//go:embed bplist.jq
+//go:embed bplist.jq bplist.md
 var bplistFS embed.FS
 
 func init() {

format/bplist/bplist.md

@@ -3,10 +3,25 @@
 $ fq -d bplist dv Info.plist
 ```
 
-### Get JSON representation
-```
-$ fq torepr com.apple.UIAutomation.plist
+### Timestamps
+Timestamps in Apple Binary Property Lists are encoded as Cocoa Core Data
+timestamps, where the raw value is the floating point number of seconds since
+January 1, 2001. By default, `fq` will render the raw floating point value. In
+order to get the raw value or string description, use the `todescription`
+function, you can use the `tovalue` and `todescription` functions:
 
+```sh
+$ fq 'torepr.SomeTimeStamp | tovalue' Info.plist
+685135328
+
+$ fq 'torepr.SomeTimeStamp | todescription' Info.plist
+"2022-09-17T19:22:08Z"
+```
+
+
+### Get JSON representation
+```sh
+$ fq torepr com.apple.UIAutomation.plist
 {
   "UIAutomationEnabled": true
 }

pkg/decode/decode.go

@@ -803,7 +803,7 @@ func (d *D) FieldStructArrayLoop(name string, structName string, condFn func() b
 	})
 }
 
-// FieldStructArrayN decodes an array of elements with a known count.
+// FieldStructNArray decodes an array of elements with a known count.
 func (d *D) FieldStructNArray(name string, structName string, count int64, fn func(d *D)) *D {
 	return d.FieldArray(name, func(d *D) {
 		for i := int64(0); i < count; i++ {