docs » hs.watchable

Creates a table that can be watched by other modules for key changes

• path - the global name for this internal table that external code can refer to the table as.
• externalChanges - an optional boolean, default false, specifying whether external code can make changes to keys within this table (bi-directional communication).

• a table with metamethods which will notify external code which is registered to watch this table for key-value changes.

• This constructor is used by code which wishes to share state information which other code may register to watch.

• You may specify any string name as a path, but it must be unique -- an error will occur if the path name has already been registered.

• All key-value pairs stored within this table are potentially watchable by external code -- if you wish to keep some data private, do not store it in this table.

• externalChanges will apply to all keys within this table -- if you wish to only allow some keys to be externally modifiable, you will need to register separate paths.

• If external changes are enabled, you will need to register your own watcher with hs.watchable.watch if action is required when external changes occur.

Creates a watcher that will be invoked when the specified key in the specified path is modified.

• path - a string specifying the path to watch. If key is not provided, then this should be a string of the form "path.key" where the key will be identified as the string after the last "."
• key - if provided, a string specifying the specific key within the path to watch.
• callback - an optional function which will be invoked when changes occur to the key specified within the path. The function should expect the following arguments:
  • watcher - the watcher object itself
  • path - the path being watched
  • key - the specific key within the path which invoked this callback
  • old - the old value for this key, may be nil
  • new - the new value for this key, may be nil

• a watchableObject

• This constructor is used by code which wishes to watch state information which is being shared by other code.

• The callback function is invoked after the new value has already been set -- the callback is a "didChange" notification, not a "willChange" notification.

• If the key (specified as a separate argument or as the final component of path) is "*", then all key-value pair changes that occur for the table specified by the path will invoke a callback. This is a shortcut for watching an entire table, rather than just a specific key-value pair of the table.

• It is possible to register a watcher for a path that has not been registered with hs.watchable.new yet. Retrieving the current value with hs.watchable:value in such a case will return nil.

Get or set whether this watcher should be notified even when the new value is identical to the current value

• notify - an optional boolean specifying whether or not the watchableObject should trigger a callback when the value of the watched path is set to its current value (i.e. it is set, but doesn't actually change value)

• if a boolean for notify is specified, returns the watchableObject; otherwise returns a boolean specifying whether or not a callback is initiated when the value of the path is set, but doesn't actually change value.

Change or remove the callback function for the watchableObject.

• fn - an optional function, or an explicit nil to remove, specifying the new callback function to receive notifications for this watchableObject

• if a value is specified and is a function, an object with a __call metamethod, or an explicit nil, returns the watchableObject; otherwise returns the current callback.

• see hs.watchable.watch for a description of the arguments the callback function should expect.

Externally change the value of the key-value pair being watched by the watchableObject

• key - if the watchableObject was defined with a key of "*", this argument is required and specifies the specific key of the watched table to change the value of. If a specific key was specified when the watchableObject was defined, this argument must not be provided.
• value - the new value for the key.

• the watchableObject

• if external changes are not allowed for the specified path, this method generates an error

Temporarily stop notifications about the key-value pair(s) watched by this watchableObject.

• None

• the watchableObject

• Only pauses notifications for this specific watchableObject -- if other watchers are set for the path watched by this watcher, they will still receive notifications if enabled and not paused.

Removes the watchableObject so that key-value pairs watched by this object no longer generate notifications.

• None

• nil

• Only releases this specific watchableObject -- if other watchers are set for the path watched by this object, they remain bound.

Resume notifications about the key-value pair(s) watched by this watchableObject which were previously paused.

• None

• the watchableObject

• Only resumes notifications for this specific watchableObject -- if other watchers are set for the path watched by this watcher are currently paused, they will remain paused.

Get the current value for the key-value pair being watched by the watchableObject

• key - if the watchableObject was defined with a key of "*", this argument is required and specifies the specific key of the watched table to retrieve the value for. If a specific key was specified when the watchableObject was defined, this argument is ignored.

• The current value for the key-value pair being watched by the watchableObject. May be nil.