P: SDK: Documentation for "bind_to_object" and "key" properties incorrect

[johnrellis]

Most of the documentation for the LrView "bind_to_object" and "key" properties is incorrect and omits important information.  From the LR 14.3 SDK:

API Reference

LrView.bind() says in multiple places "bind_to_object" is a string. But in fact it is an observable table returned by LrBinding.makePropertyTable().

LrView.bind() omits the following about "key":  A key name for the observed property. If "key" is of the form "x.y", then it refers to the key "y" in the table bound to key "x" in the current bound table.  Are multiple dots allowed, e.g. "x.y.z"?

LrBinding.andAllKeys() and LrBinding.orAllKeys() say "bind_to_object" is a string, but it is in fact a table as specified in LrView.bind().

LrBinding: Can the various instances of "key" be in in hierarchical form, as in LrView.bind()?  

Lightroom Classic SDK Guide

Page 105: Says "bind_to_object:  Optional. The name of an observable table which overrides the value of the property." This is incorrect -- it is an observable table returned by LrBinding.makePropertyTable().

Page 107: Says "bind_to_object or object: Optional. The name of an observable table..." This is incorrect -- it is an observable table returned by LrBinding.makePropertyTable().

* * *

See also this previous bug report, which fixed one instance of missing information but not everything listed above:

https://community.adobe.com/t5/lightroom-classic-bugs/p-sdk-lrview-bind-key-fails-when-quot-key-quot...

[Rikk Flohr: Photography]

Thanks, @johnrellis  I will get it logged for a future SDK documentation update. 

[drtonyb]

@johnrellis 

Hopefully it will get corrected soon.

You wrote

If "key" is of the form "x.y", then it refers to the key "y" in the table bound to key "y" in the current bound table.

I think that should be "y" in the table bound to key "x" as in

If "key" is of the form "x.y", then it refers to the key "y" in the table bound to key "x" in the current bound table

[johnrellis]

"I think that should be "y" in the table bound to key "x" as in"

Thanks, corrected it.

[drtonyb]

@johnrellis 

Regarding a key of the form "x.y", Lua does allow it as a key, but it can lead to nasty, obscure errors:

a = {}

a['x.y'] = 1 -- this is ok

print( a['x.y'] ) -- this is ok

print ( a.x.y ) -- this is an error because a.x doesn't exist

a = { x.y = 1 } -- this is a Lua error

a = { 'x.y' = 1 } -- this is a Lua error

I would strongly discourage the use of strings containing dots of the form 'x.y' as field names in a table.

[johnrellis]

The original bug report was about my Copy Settings plugin using key names supplied by the user (the user-supplied names of masks in develop settings).  From the point of view of the plugin source code, they were just opaque strings that would have worked just fine as keys except for this (at the time) undocumented feature of LrView.bind(). There was no danger of the kind of programming mistake you described.

[drtonyb]

@johnrellis 

Thanks, that makes complete sense.