# hs.watchable

A minimalistic Key-Value-Observer framework for Lua.

This module allows you to generate a table with a defined label or path that can be used to share data with other modules or code. Other modules can register as watchers to a specific key-value pair within the watchable object table and will be automatically notified when the key-value pair changes.

The goal is to provide a mechanism for sharing state information between separate and (mostly) unrelated code easily and in an independent fashion.

# API Overview

Constructors - API calls which return an object, typically one that offers API methods

new
watch

Methods - API calls which can only be made on an object returned by a constructor

callback
change
pause
release
resume
value

# API Documentation

# Constructors

# new


Signature	`hs.watchable.new(path, [externalChanges]) -> table`
Type	Constructor
Description	Creates a table that can be watched by other modules for key changes
Parameters	`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).
Returns	a table with metamethods which will notify external code which is registered to watch this table for key-value changes.
Notes	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.
Examples	None
Source	extensions/watchable/watchable.lua line 188

# watch

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.watchable.watch(path, [key], callback) -> watchableObject | | Type | Constructor | | Description | Creates a watcher that will be invoked when the specified key in the specified path is modified. | | Parameters |

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

| | Returns |

a watchableObject

| | Notes |

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.

# Methods

# callback


Signature	`hs.watchable:callback(fn) -> watchableObject`
Type	Method
Description	Change or remove the callback function for the watchableObject.
Parameters	`fn` - a function, or an explicit nil to remove, specifying the new callback function to receive notifications for this watchableObject
Returns	the watchableObject
Notes	see hs.watchable.watch for a description of the arguments the callback function should expect.
Examples	None
Source	extensions/watchable/watchable.lua line 100

# change


Signature	`hs.watchable:change([key], value) -> watchableObject`
Type	Method
Description	Externally change the value of the key-value pair being watched by the watchableObject
Parameters	`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.
Returns	the watchableObject
Notes	if external changes are not allowed for the specified path, this method generates an error
Examples	None
Source	extensions/watchable/watchable.lua line 144

# pause


Signature	`hs.watchable:pause() -> watchableObject`
Type	Method
Description	Temporarily stop notifications about the key-value pair(s) watched by this watchableObject.
Parameters	None
Returns	the watchableObject
Notes	None
Examples	None
Source	extensions/watchable/watchable.lua line 61

# release


Signature	`hs.watchable:release() -> nil`
Type	Method
Description	Removes the watchableObject so that key-value pairs watched by this object no longer generate notifications.
Parameters	None
Returns	nil
Notes	None
Examples	None
Source	extensions/watchable/watchable.lua line 81

# resume


Signature	`hs.watchable:resume() -> watchableObject`
Type	Method
Description	Resume notifications about the key-value pair(s) watched by this watchableObject which were previously paused.
Parameters	None
Returns	the watchableObject
Notes	None
Examples	None
Source	extensions/watchable/watchable.lua line 71

# value


Signature	`hs.watchable:value([key]) -> currentValue`
Type	Method
Description	Get the current value for the key-value pair being watched by the watchableObject
Parameters	`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.
Returns	The current value for the key-value pair being watched by the watchableObject. May be nil.
Notes	None
Examples	None
Source	extensions/watchable/watchable.lua line 125